2024. 2. 4. 19:22ㆍpython/intermediate
좋은 문서를 보유하는 것은 성공적인 Python 프로젝트의 중요한 특징입니다. 실제로 문서 작성은 어렵고 시간과 노력이 많이 들기 때문에 일부 개발자는 문서 작성을 꺼립니다. 다행히 대규모 언어 모델 (LLM)과 ChatGPT 와 같은 도구를 사용하면 Python 코드와 프로젝트를 빠르게 문서화할 수 있습니다.
Python에서는 독스트링을 사용하여 코드를 문서화 한 다음 이를 활용하여 프로젝트의 외부 문서를 풍부하게 만들 수 있습니다 . ChatGPT는 독스트링과 외부 문서를 작성하는 데 큰 도움이 될 수 있습니다.
이 튜토리얼을 최대한 활용하려면 ChatGPT 계정이 있어야 하며 프롬프트 엔지니어링을 사용하여 이 도구와 상호 작용하는 기본 사항을 알아야 합니다 . 또한 Python 코드를 문서화하는 방법의 기본 사항도 알아야 합니다.
Python 코드 문서화에 ChatGPT를 사용하면 얻을 수 있는 이점
모든 소프트웨어 프로젝트에는 고품질의 최신 문서를 보유하는 것이 중요합니다. 코드베이스가 잘 작성되고 프로젝트의 주요 아이디어가 혁신적이고 유용하더라도 문서화가 제대로 이루어지지 않으면 프로젝트가 실패하거나 눈에 띄지 않게 될 수 있습니다.
좋은 문서를 작성하려면 상당한 시간과 노력이 필요합니다. 그렇기 때문에 ChatGPT 와 같은 LLM(대규모 언어 모델)을 사용하는 것이 프로젝트 및 코드에 적절한 문서를 제공하기 위한 실행 가능한 대안이 될 수 있습니다.
Python 코드 문서화에 대한 ChatGPT의 이점 중 일부는 다음과 같습니다.
- 생산성 향상 : 코드 문서화 및 유지 관리와 관련된 작업을 자동화하여 상당한 시간과 노력을 절약할 수 있습니다.
- 품질 향상 : 문서가 정확하고, 최신이며, 포괄적인지 확인하는 데 도움이 됩니다. 향상된 사용자 경험 : 매력적이고 사용자 친화적인 문서를 생성하여 더 나은 사용자 경험을 제공할 수 있습니다.
- 비용 절감 : 문서 작성 및 유지 관리 비용을 줄이는 데 도움이 됩니다.
- 규정 준수 개선 : 문서가 표준 및 규정을 준수하는지 확인하여 문서를 더욱 일관되고 전문적으로 만들 수 있습니다.
ChatGPT를 사용하면 거의 즉시 Python 코드에 대한 멋진 문서를 생성할 수 있습니다. 다음 섹션에서는 Python 프로젝트를 위한 일관된 독스트링 및 사용자 친화적인 외부 문서를 생성하기 위한 보조 도구로 ChatGPT를 사용하는 기본 사항을 배웁니다.
Docstring 작성을 위한 효과적인 ChatGPT 프롬프트
Python 코드를 문서화하는 주요 방법은 docstring을 사용하는 것입니다. Python에서 독 스트링은 일반적으로 모듈 , 함수 , 클래스 및 메소드 의 첫 번째 줄을 차지하는 삼중 따옴표 로 묶인 문자열입니다. 이 문자열은 Python에서 특별한 의미를 가지며, .__doc__이라는 속성에 저장됩니다.
코드 편집기 및 IDE를 포함한 많은 Python 도구는 코드 문자열을 활용하여 코드를 작성할 때 실시간 도움말을 제공합니다. Docstring은 Python의 내장 도움말 시스템의 일부이기도 하며, help() 함수를 사용하여 액세스할 수 있습니다.
help(str)
이 예에서는 help()를 str 클래스를 인수로 사용하여 호출하고 클래스의 독스트링이 포함된 클래스 문서 페이지를 얻습니다.
print(str.__doc__)
이 경우 str 클래스의 .__doc__속성에 직접 액세스하여 클래스의 독스트링을 얻습니다. 결론적으로, 독스트링은 코드에 많은 가치를 추가합니다. 이는 귀하와 다른 Python 개발자가 Python 개체에 대해 배우기 위해 사용하는 기본 문서입니다.
Sphinx 또는 MkDocs 와 같은 도구를 사용하여 프로젝트 문서를 작성할 때 코드의 독스트링을 활용할 수도 있습니다 . 이러한 도구에는 독스트링을 추출하고 이를 프로젝트의 외부 문서의 일부로 만들 수 있는 플러그인과 기능이 있어 많은 시간을 절약할 수 있습니다.
Python에는 좋은 독스트링을 작성하기 위한 잘 확립된 규칙이 있습니다. 패키지, 모듈, 클래스, 메소드 및 함수 독스트링은 모두 특정 목표를 갖고 있으며 특정 지침을 따라야 합니다. PEP 257 에서 이러한 지침과 규칙을 찾을 수 있습니다.
PEP 257이 표준을 제공하지만 실제로 Python 생태계 전반에 걸쳐 건전하고 다양한 독스트링 스타일을 찾을 수 있습니다. 다음은 몇 가지 일반적인 대안입니다.
Google 스타일 독스트링 : 이 스타일은 Google에서 왔으며 회사의 오픈 소스 프로젝트에서 많은 예를 찾을 수 있습니다. NumPy docstring 표준 : 이 스타일은 NumPy 라이브러리용으로 개발되었으며 다른 많은 Python 프로젝트에서도 이를 채택했습니다. reStructuredText(RST) 또는 Sphinx docstring 형식 : 이 스타일은 reStructuredText를 기반으로 하며 문서 생성을 자동화하는 데 유용한 도구인 Sphinx에서 유래되었습니다. Epytext 스타일 : 이것은 원래 Epydoc 프로젝트 에서 생성된 독스트링의 형식을 지정하는 데 사용되는 경량 마크업 언어입니다 . 각 스타일에는 고유한 규칙이 있습니다. 일반적으로 하나의 스타일을 선택하고 Python 프로젝트 전체에서 일관되게 사용해야 합니다.
실제로 독스트링 스타일을 선택하는 것은 대부분 개인 취향의 문제입니다. 그러나 다음 특성을 포함하여 프로젝트의 특정 요구 사항도 고려해야 합니다.
프로젝트의 복잡성 : 크고 복잡한 프로젝트가 있는 경우 자세한 문서화를 허용하는 Sphinx 또는 NumPy 스타일의 이점을 누릴 수 있습니다. 대조적으로 소규모 프로젝트에는 기본적인 문서만 필요할 수 있으며 PEP 257 또는 Google 스타일 독스트링과 같은 것도 괜찮습니다. 문서 도구 : Sphinx 또는 MkDocs와 같은 도구를 사용하여 프로젝트 문서를 생성하는 경우 선택한 도구에서 가장 잘 지원되는 스타일을 사용해야 합니다. Python의 독스트링에 대한 짧은 배경 지식을 바탕으로 ChatGPT가 독스트링을 작성하도록 요청할 준비가 되었습니다.
프롬프트의 일부로 대상 코드 사용
독스트링 작성을 위한 프롬프트를 생성하는 가장 빠른 방법은 대상 코드를 프롬프트 자체의 일부로 포함하는 것입니다. 두 숫자를 더하는 함수의 독스트링을 생성하기 위한 프롬프트를 생성하는 다음 예를 고려해보세요:
당신: 다음 함수에 대한 한 줄 독스트링을 작성하세요.
챗GPT:
def add(a, b):
"""Adds two values."""
return a + b
이 프롬프트에서는 ChatGPT에 함수에 대한 한 줄 독스트링을 작성하도록 요청합니다. 결과는 매우 간단하고 읽기 쉽습니다. 이러한 유형의 독스트링은 인수 와 함수의 반환 값 에 대한 자세한 정보를 제공하지 않습니다 .
프롬프트를 좀 더 자세히 작성하고 특정 독스트링 스타일을 요청할 수 있습니다. 다음 프롬프트는 ChatGPT가 각각 Google, NumPy 및 Sphinx 스타일을 사용하여 add() 함수에 대한 독스트링을 생성하도록 합니다.
당신: 다음 함수에 대한 Google 스타일의 독스트링을 작성하세요:
def add(a, b):
return a + b
# 쳇GPT:
def add(a, b):
"""
Adds two values.
Parameters
----------
a : numeric
The first value to be added.
b : numeric
The second value to be added.
Returns
-------
numeric
The sum of the two input values.
"""
return a + b
당신: 다음 함수에 대한 NumPy 스타일의 독스트링을 작성하세요:
def add(a, b):
return a + b
# 챗GPT:
def add(a, b):
"""
Perform element-wise addition on two arrays.
Parameters
----------
a : numpy.ndarray or array-like
Input array or array-like object.
b : numpy.ndarray or array-like
Another input array or array-like object.
Returns
-------
numpy.ndarray
The result of element-wise addition.
Examples
--------
>>> add([1, 2, 3], [4, 5, 6])
array([5, 7, 9])
>>> add(2.5, 3.5)
6.0
>>> add(np.array([1, 2, 3]), np.array([4, 5, 6]))
array([5, 7, 9])
Notes
-----
- Broadcasting rules are applied for array inputs.
- Arrays are expected to be NumPy arrays or array-like objects.
"""
pass # function implementation goes here
당신: 다음 함수에 대한 Sphinx 스타일의 독스트링을 작성하세요:
# 파이썬
def add(a, b):
return a + b
# 챗GPT:
def add(a, b):
"""
Perform addition of two values.
This function takes two input values and returns their sum.
Parameters
----------
a : numeric
The first value to be added.
b : numeric
The second value to be added.
Returns
-------
numeric
The sum of the two input values.
Examples
--------
>>> add(2, 3)
5
>>> add(1.5, 2.5)
4.0
Notes
-----
- This function supports both integers and floating-point numbers.
- The function is not designed for array inputs.
"""
return a + b
이 세 개의 독스트링은 이전에 본 한 줄 독스트링보다 더 완전하고 세련되어 보입니다. 사용하려는 특정 스타일에 대한 정보를 추가하면 ChatGPT는 함수에 대한 완전한 독스트링을 생성할 수 있습니다. 물론 초기 결과가 완벽하지 않을 수도 있지만 좋은 출발점이 됩니다.
참고: ChatGPT는 독스트링의 형식 지정 및 스타일 지정에 매우 능숙합니다. 그러나 출력이 선택한 스타일과 완벽하게 호환되는지 확인하려면 항상 해당 문서를 상호 참조해야 합니다.
가장 중요한 점은 짧은 단일 문장을 프롬프트로 사용하여 완전한 독스트링을 얻었다는 것입니다. 이는 프로젝트의 생산성을 엄청나게 향상시킵니다.
ChatGPT를 사용하면 기능에 대한 독스트링을 생성할 수 있을 뿐만 아니라 모듈, 클래스 등을 사용할 수도 있습니다. 다음은 Circle 클래스와 해당 메소드에 대한 독스트링을 생성하는 방법에 대한 간단한 예입니다.
당신: 다음 클래스와 그 메소드에 대해 NumPy 스타일의 독스트링을 작성하세요:
class Circle:
def __init__(self, radius):
self.radius = radius
def calculate_area(self):
return round(math.pi * self.radius ** 2, 2)
ChatGPT:
class Circle:
"""
A Circle class to perform some circle-related operations.
Parameters
----------
radius : float
The radius of the circle.
Attributes
----------
radius : float
The radius of the circle.
Methods
-------
calculate_area():
Calculates the area of the circle.
"""
def __init__(self, radius):
"""
Constructs all the necessary attributes for the circle object.
Parameters
----------
radius : float
The radius of the circle.
"""
self.radius = radius
def calculate_area(self):
"""
Calculate the area of the circle.
Returns
-------
float
The area of the circle rounded to 2 decimal places.
"""
return round(math.pi * self.radius ** 2, 2)
단일 문장 프롬프트를 사용하여 ChatGPT가 클래스와 모든 해당 메서드에 대해 NumPy 스타일 독스트링을 생성하도록 했습니다. 이는 코드베이스에 큰 도움이 됩니다.
프롬프트에 서명만 포함
때로는 프롬프트의 일부로 대상 코드를 사용할 수 없습니다. 이는 개인 정보 보호 요구 사항 때문일 수도 있고 회사 코드를 안전하게 유지하려는 것일 수도 있습니다. 이 시나리오에서는 클래스, 메서드 및 함수의 시그니처 만 사용하는 프롬프트를 생성할 수 있습니다.
참고: ChatGPT의 데이터 사용과 관련하여 진행 중인 소송이 많이 있습니다. 어떤 경우든 ChatGPT의 이용 약관을 확인 하여 도구가 귀하에게 적합한지, 올바르게 사용하고 있는지 확인해야 합니다.
이러한 유형의 프롬프트를 생성하는 방법을 이해하려면 숫자가 주어진 간격 내에 속하는지 확인하는 함수의 서명을 고려하십시오.
당신: 다음 서명을 사용하여 함수에 대한 Google 스타일 독스트링을 작성합니다.
Python
def in_interval(number, start, end):ChatGPT:
def in_interval(number, start, end):
"""
Checks if a given number is within a specified interval.
This function takes three arguments: a number, and the start
and end points of an interval.
It checks whether the given number falls within the specified
interval or not.
Args:
number (int or float): The number to check.
start (int or float): The starting point of the interval.
end (int or float): The ending point of the interval.
Returns:
bool: True if the given number falls within the interval,
False otherwise.
Raises:
ValueError: If the start is larger than the end, or if
the number, start, or end are not numbers.
"""이 예에서 함수의 서명은 ChatGPT에 제공하는 유일한 컨텍스트입니다. LLM은 함수의 이름과 인수를 검사하고 적합한 문서 문자열을 생성할 만큼 똑똑합니다. 이러한 종류의 프롬프트에서는 설명적인 함수 및 인수 이름을 갖는 것이 핵심입니다. 그렇지 않으면 출력이 충분하지 않을 수 있습니다.
대부분의 경우 함수 시그니처에 유형 힌트를 추가하면 생성된 독스트링의 품질이 향상됩니다.
코드를 사용하지 않는 프롬프트 작성
코드의 입력과 출력을 설명하거나 코드의 기능에 대한 자세한 설명을 제공하여 프롬프트를 만들 수도 있습니다. 다시 말하지만, 이러한 유형의 프롬프트는 코드를 프롬프트의 일부로 업로드할 수 없는 경우에 유용합니다.
설명을 위해 다음은 정수가 소수인지 여부를 결정하는 함수에 대한 독스트링을 작성하도록 ChatGPT에 요청하는 프롬프트입니다.
당신: 정수를 인수로 취하고 소수인지 여부를 결정하는 함수에 대한 Google 스타일 독스트링을 작성합니다.
ChatGPT:
def is_prime_number(n):
"""
Determines if an input integer is a prime number.
This function takes an integer as an argument and checks
whether it is a prime number. A prime number is a
positive natural number greater than 1 that has no positive
integer divisors other than 1 and itself.
Args:
n (int): The integer to check.
Returns:
bool: True if the input integer is a prime number,
False otherwise.
Raises:
ValueError: If n is less than or equal to 1.
"""이 독스트링은 매우 완전하고 유용합니다. 여기에는 소수가 무엇인지에 대한 설명도 포함되어 있습니다. 정말 훌륭합니다! 추가로 조정하고 몇 가지 세부 사항을 다듬을 수 있습니다. 그러나 이미 훌륭한 출발점이 있습니다.
프롬프트에서 테스트 및 사용 예 요청
사용 예는 아마도 좋은 소프트웨어 문서의 가장 중요한 부분일 것입니다. 코드 예제를 통해 사용자는 코드 사용 방법과 작동 방식을 빠르게 이해할 수 있습니다. 종종 다른 개발자는 코드 예제를 찾을 때까지 문서를 샅샅이 살펴봅니다.
따라서 독스트링에 사용 예제를 추가하는 것은 큰 장점입니다. ChatGPT를 사용하면 사용 예를 제공하는 것은 프롬프트에 짧은 문장을 포함하는 것뿐입니다. 다음 프롬프트와 해당 출력을 고려하세요.
당신: 다음 함수에 대한 NumPy 스타일의 독스트링을 작성하세요. doctest 테스트 용으로 사용 예제가 포함된 섹션을 추가하세요.
파이썬
def add(a, b):
return a + b
ChatGPT:
def add(a, b):
"""
Add two numbers together.
This function takes two numbers (either integers or floats)
as arguments and returns their sum.
Parameters
----------
a : int or float
The first number to add.
b : int or float
The second number to add.
Returns
-------
int or float
The sum of the two input numbers.
Examples
--------
>>> add(1, 2)
3
>>> add(5.5, 2.5)
8.0
>>> add(100, -50)
50
"""
return a + b강조 표시된 줄은 함수의 사용 예를 보여줍니다. 프롬프트에서 ChatGPT에 예제의 doctest 테스트 형식을 사용하도록 지시했습니다. 이는 두 가지 중요한 자산을 제공합니다.
- 사용 예
- 코드에 대한 기본 테스트
두 가지 혜택을 한 번에 받아보실 수 있습니다! 문서에는 사용자를 위한 멋진 사용 예제가 포함되어 있으며 동시에 코드를 더욱 강력하게 만드는 데 도움이 되는 테스트도 포함되어 있습니다. 명령을 사용하여 이러한 doctest 테스트를 실행할 수 있습니다.
출처 : https://realpython.com/document-python-code-with-chatgpt/
'python > intermediate' 카테고리의 다른 글
| Python에서 여러 반환 유형에 대해 유형 힌트를 사용하는 방법 I (1) | 2024.02.06 |
|---|---|
| ChatGPT로 Python 코드와 프로젝트를 문서화하세요 II (0) | 2024.02.05 |
| Python 코드 문서화: 전체 가이드 (0) | 2024.02.03 |
| 향상된 노트북 경험을 위한 JupyterLab II (0) | 2024.02.02 |
| 향상된 노트북 경험을 위한 JupyterLab I (1) | 2024.02.01 |