Python 독스트링
깨끗하고 잘 문서화된 코드를 작성하는 데 있어 Python 개발자는 독스트링이라는 비밀 무기를 사용할 수 있습니다. 문서 문자열의 약자인 Docstring은 문서의 목적과 기능을 전달하는 데 매우 중요합니다. 파이썬 함수, 모듈, 클래스.
Python의 독스트링(Docstring)이란 무엇입니까?
파이썬 문서 문자열(또는 독스트링)은 문서를 다음과 연결하는 편리한 방법을 제공합니다. Python 모듈 , 함수, 클래스 및 메서드. 이는 주석과 같이 특정 코드 세그먼트를 문서화하는 데 사용되는 소스 코드에 지정됩니다. 기존 소스 코드 주석과 달리 독스트링은 함수가 수행하는 작업이 아닌 무엇을 수행하는지 설명해야 합니다.
- 독스트링 선언 : 독스트링은 클래스, 메소드 또는 함수 선언 바로 아래에 '세 개의 작은따옴표' 또는 세 개의 큰따옴표를 사용하여 선언됩니다. 모든 함수에는 독스트링이 있어야 합니다.
- 독스트링에 접근하기 : 독스트링은 객체의 __doc__ 메소드나 도움말 함수를 사용하여 접근할 수 있습니다. 아래 예제는 독스트링을 선언하고 액세스하는 방법을 보여줍니다.
독스트링은 어떤 모습이어야 할까요?
- 문서 문자열 줄은 대문자로 시작하고 마침표로 끝나야 합니다.
- 첫 번째 줄은 간단한 설명이어야 합니다.
- 문서 문자열에 더 많은 줄이 있는 경우 두 번째 줄은 비어 있어야 하며 요약과 나머지 설명을 시각적으로 구분해야 합니다.
- 다음 줄은 객체의 호출 규칙, 부작용 등을 설명하는 하나 이상의 단락이어야 합니다.
Python의 독스트링
이 기사에서 다룰 주제는 다음과 같습니다.
- 삼중따옴표로 묶인 문자열
- Google 스타일 Docstring
- Numpydoc 스타일 Docstring
- 한 줄 독스트링
- 여러 줄 독스트링
- Docstring의 들여쓰기
- 클래스의 독스트링
- Python 주석과 Docstring의 차이점
삼중따옴표로 묶인 문자열
이것은 Python에서 가장 일반적인 Docstring 형식입니다. 문서 텍스트를 묶기 위해 삼중따옴표(작은따옴표 또는 큰따옴표)를 사용하는 것이 포함됩니다. 삼중따옴표로 묶인 문자열은 여러 줄에 걸쳐 있을 수 있으며 함수, 클래스 또는 모듈 정의 바로 아래에 배치되는 경우가 많습니다.
예시 1: 세 개의 작은따옴표 사용
파이썬3
def> my_function():> > '''Demonstrates triple double quotes> > docstrings and does nothing really.'''> > > return> None> print> (> 'Using __doc__:'> )> print> (my_function.__doc__)> print> (> 'Using help:'> )> help> (my_function)> |
산출:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.
예시 2: 삼중큰따옴표 사용
파이썬3
def> my_function():> > ' '> 'Demonstrates triple double quotes docstrings and does nothing really'> ' '> > > return> None> print> (> 'Using __doc__:'> )> print> (my_function.__doc__)> print> (> 'Using help:'> )> help> (my_function)> |
산출:
Using __doc__: Demonstrates triple double quotes docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function() Demonstrates triple double quotes docstrings and does nothing really.
Google 스타일 Docstring
Google 스타일 독스트링은 특정 형식을 따르며 Google의 문서 스타일 가이드에서 영감을 받았습니다. 매개변수, 반환 값, 설명을 포함하여 Python 코드를 문서화하는 구조화된 방법을 제공합니다.
파이썬3
def> multiply_numbers(a, b):> > '''> > Multiplies two numbers and returns the result.> > Args:> > a (int): The first number.> > b (int): The second number.> > Returns:> > int: The product of a and b.> > '''> > return> a> *> b> print> (multiply_numbers(> 3> ,> 5> ))> |
산출
15
Numpydoc 스타일 Docstring
Numpydoc 스타일의 독스트링은 과학 및 데이터 분석 커뮤니티, 특히 수치 계산 및 데이터 조작과 관련된 함수 및 클래스를 문서화하는 데 널리 사용됩니다. 이는 매개변수 및 반환 값을 문서화하기 위한 몇 가지 추가 규칙이 포함된 Google 스타일 Docstring의 확장입니다.
파이썬3
def> divide_numbers(a, b):> > '''> > Divide two numbers.> > Parameters> > ----------> > a : float> > The dividend.> > b : float> > The divisor.> > Returns> > -------> > float> > The quotient of the division.> > '''> > if> b> => => 0> :> > raise> ValueError(> 'Division by zero is not allowed.'> )> > return> a> /> b> print> (divide_numbers(> 3> ,> 6> ))> |
산출
0.5
한 줄 독스트링
이름에서 알 수 있듯이, 한 줄 독스트링은 한 줄에 맞습니다. 명백한 경우에 사용됩니다. 닫는 따옴표는 시작 따옴표와 같은 줄에 있습니다. 이것은 단일 라이너에 더 좋아 보입니다. 예를 들어:
파이썬3
def> power(a, b):> > ' '> 'Returns arg1 raised to power arg2.'> ' '> > > return> a> *> *> b> print> (power.__doc__)> |
산출:
Returns arg1 raised to power arg2.
여러 줄 독스트링
여러 줄 독스트링은 한 줄 독스트링과 마찬가지로 요약 줄, 빈 줄, 더 자세한 설명으로 구성됩니다. 요약 줄은 시작 인용문과 같은 줄이나 다음 줄에 있을 수 있습니다. 아래 예는 여러 줄의 독스트링을 보여줍니다.
파이썬3
def> add_numbers(a, b):> > '''> > This function takes two numbers as input and returns their sum.> > Parameters:> > a (int): The first number.> > b (int): The second number.> > Returns:> > int: The sum of a and b.> > '''> > return> a> +> b> print> (add_numbers(> 3> ,> 5> ))> |
산출:
8
Docstring의 들여쓰기
전체 독스트링은 첫 번째 줄의 따옴표와 동일하게 들여쓰기됩니다. 독스트링 처리 도구는 독스트링의 두 번째 줄과 그 다음 줄에서 균일한 양의 들여쓰기를 제거합니다. 이는 첫 번째 줄 뒤의 공백이 아닌 모든 줄의 최소 들여쓰기와 동일합니다. 독스트링의 첫 번째 줄(즉, 첫 번째 새 줄까지)의 들여쓰기는 중요하지 않으며 제거됩니다. 독스트링에서 뒷줄의 상대 들여쓰기는 유지됩니다.
파이썬3
class> Employee:> > '''> > A class representing an employee.> > Attributes:> > name (str): The name of the employee.> > age (int): The age of the employee.> > department (str): The department the employee works in.> > salary (float): The salary of the employee.> > '''> > def> __init__(> self> , name, age, department, salary):> > '''> > Initializes an Employee object.> > Parameters:> > name (str): The name of the employee.> > age (int): The age of the employee.> > department (str): The department the employee works in.> > salary (float): The salary of the employee.> > '''> > self> .name> => name> > self> .age> => age> > self> .department> => department> > self> .salary> => salary> > def> promote(> self> , raise_amount):> > '''> > Promotes the employee and increases their salary.> > Parameters:> > raise_amount (float): The raise amount to increase the salary.> > Returns:> > str: A message indicating the promotion and new salary.> > '''> > self> .salary> +> => raise_amount> > return> f> '{self.name} has been promoted! New salary: ${self.salary:.2f}'> > def> retire(> self> ):> > '''> > Marks the employee as retired.> > Returns:> > str: A message indicating the retirement status.> > '''> > # Some implementation for retiring an employee> > return> f> '{self.name} has retired. Thank you for your service!'> # Access the Class docstring using help()> help> (Employee)> |
산출:
class Employee | A class representing an employee. | | Attributes: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | Methods defined here: | | __init__(self, name, age, department, salary) | Initializes an Employee object. | | Parameters: | name (str): The name of the employee. | age (int): The age of the employee. | department (str): The department the employee works in. | salary (float): The salary of the employee. | | promote(self, raise_amount) | Promotes the employee and increases their salary. | | Parameters: | raise_amount (float): The raise amount to increase the salary. | | Returns: | str: A message indicating the promotion and new salary. | | retire(self) | Marks the employee as retired. | | Returns: | str: A message indicating the retirement status.
클래스의 독스트링
클래스와 메소드에 대한 독스트링을 작성하는 방법을 보여주는 예를 들어보겠습니다. 돕다' docstring에 액세스하는 데 사용됩니다.
파이썬3
class> ComplexNumber:> > '''> > This is a class for mathematical operations on complex numbers.> > Attributes:> > real (int): The real part of the complex number.> > imag (int): The imaginary part of the complex number.> > '''> > def> __init__(> self> , real, imag):> > '''> > The constructor for ComplexNumber class.> > Parameters:> > real (int): The real part of the complex number.> > imag (int): The imaginary part of the complex number.> > '''> > self> .real> => real> > self> .imag> => imag> > def> add(> self> , num):> > '''> > The function to add two Complex Numbers.> > Parameters:> > num (ComplexNumber): The complex number to be added.> > Returns:> > ComplexNumber: A complex number which contains the sum.> > '''> > re> => self> .real> +> num.real> > im> => self> .imag> +> num.imag> > return> ComplexNumber(re, im)> # Access the Class docstring using help()> help> (ComplexNumber)> # Access the method docstring using help()> help> (ComplexNumber.add)> |
산출:
Help on class ComplexNumber in module __main__: class ComplexNumber(builtins.objects) | This is a class for mathematical operations on complex numbers. | | Attributes: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | Methods defined here: | | __init__(self, real, imag) | The constructor for ComplexNumber class. | | Parameters: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | add(self, num) | The function to add two Complex Numbers. | | Parameters: | num (ComplexNumber): The complex number to be added. | | Returns: | ComplexNumber: A complex number which contains the sum. Help on method add in module __main__: add(self, num) unbound __main__.ComplexNumber method The function to add two Complex Numbers. Parameters: num (ComplexNumber): The complex number to be added. Returns: ComplexNumber: A complex number which contains the sum.
Python 주석, 문자열 및 Docstring의 차이점
문자열: Python에서 문자열은 작은따옴표(' ') 또는 큰따옴표( )로 묶인 일련의 문자입니다. 문자열은 텍스트 데이터를 나타내는 데 사용되며 문자, 숫자, 기호 및 공백을 포함할 수 있습니다. 이는 Python의 기본 데이터 유형 중 하나이며 다양한 문자열 방법을 사용하여 조작할 수 있습니다.
여러분 모두 Python 독스트링에 대한 아이디어를 갖고 있을 것입니다. 하지만 Python 주석과 독스트링의 차이점이 무엇인지 궁금한 적이 있습니까? 그것들을 살펴보자.
독자가 소스 코드를 이해할 수 있도록 개발자가 제공하는 유용한 정보입니다. 코드에 사용된 논리 또는 그 일부를 설명합니다. 을 사용하여 작성됩니다.
#>
기호.
예:
파이썬3
# Python program to demonstrate comments> print> (> 'GFG'> )> name> => 'Abhishek Shakya'> #demostrate String> |
산출:
GFG
위에서 언급한 Python Docstring은 문서를 Python 모듈, 함수, 클래스 및 메서드와 연결하는 편리한 방법을 제공합니다.
