**kwargs 매개 변수를 문서화하는 올바른 방법은 무엇입니까?
저는 Spinx와 autodoc 확장을 사용하여 Python 모듈에 대한 API 문서를 생성하고 있습니다.특정 매개 변수를 잘 문서화하는 방법은 알 수 있지만, 다음을 문서화하는 방법에 대한 예는 찾을 수 없습니다.**kwargs매개 변수
이것들을 명확하게 기록할 수 있는 좋은 예를 가진 사람이 있습니까?
이 질문을 발견한 후 다음 사항에 대해 결론을 내렸는데, 이는 유효한 스핑크스이며 상당히 잘 작동합니다.
def some_function(first, second="two", **kwargs):
r"""Fetches and returns this thing
:param first:
The first parameter
:type first: ``int``
:param second:
The second parameter
:type second: ``str``
:param \**kwargs:
See below
:Keyword Arguments:
* *extra* (``list``) --
Extra stuff
* *supplement* (``dict``) --
Additional content
"""
그r"""..."""이것을 "원시" 문서 문자열로 만들기 위해 필요하며 따라서.\*온전함(스핑크스가 리터럴로 선택할 수 있음)*그리고 "codice_1"의 시작이 아님).
선택한 형식(괄호 형식과 m-대시로 구분된 설명이 있는 글머리 기호 목록)은 스핑크스가 제공하는 자동 형식과 일치하는 것입니다.
일단 "키워드 인수" 섹션을 기본 "매개 변수" 섹션처럼 보이게 만든 후에는 처음부터 매개 변수 섹션을 롤링하는 것이 더 쉬워질 수도 있습니다(다른 답변 중 일부 참조). 하지만 개념 증명을 위해 이 방법은 보충적인 기능을 제공하기 위한 한 가지 방법입니다.**kwargs이미 스핑크스를 사용하고 있는 경우.
스핑크스가 구문 분석한 Google 스타일 문서 문자열
고지 사항: 테스트되지 않았습니다.
스핑크스 문서 문자열 예제의 이 컷아웃에서,*args그리고.**kwargs확장되지 않은 상태로 유지됩니다.
def module_level_function(param1, *args, param2=None, **kwargs):
"""
...
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
컴팩트함을 위해 다음과 같은 솔루션을 제안합니다.
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*param3 (int): description
*param4 (str):
...
**key1 (int): description
**key2 (int): description
...
어떻게,Optional에 필요하지 않습니다.**key논쟁들.
그렇지 않으면 아래에 *args를 명시적으로 나열할 수 있습니다.Other Parameters그리고.**kwargs의 밑에Keyword Args(docstring 섹션 참조):
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
Other Parameters:
param3 (int): description
param4 (str):
...
Keyword Args:
key1 (int): description
key2 (int): description
...
문서에는 스핑크스에 대한 docstring 예제가 있습니다.구체적으로 다음을 보여줍니다.
def public_fn_with_googley_docstring(name, state=None):
"""This function does something.
Args:
name (str): The name to use.
Kwargs:
state (bool): Current state to be in.
Returns:
int. The return code::
0 -- Success!
1 -- No good.
2 -- Try again.
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> print public_fn_with_googley_docstring(name='foo', state=None)
0
BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`.
"""
return 0
스핑크스에 대해 명시적으로 물어보셨지만, 구글 파이썬 스타일 가이드도 참고하겠습니다.그들의 문서 문자열 예시는 그들이 특별히 무장괴한들을 부르지 않는다는 것을 의미하는 것 같습니다.(기타_silly_변수=변수)
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass
A-B-B는 하위 프로세스 관리 문서를 참조할 때 수락된 답변에 대해 질문이 있습니다.모듈을 가져오면 inspect.get source를 통해 모듈 문서 문자열을 빠르게 확인할 수 있습니다.
사일런트 고스트의 추천을 사용한 파이썬 인터프리터의 예:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
물론 도움말 기능을 통해 모듈 설명서를 볼 수도 있습니다.예: 도움말(하위 프로세스)
저는 개인적으로 하위 프로세스 docstring for kwargs의 팬은 아니지만 Google 사례와 마찬가지로 스핑크스 문서 예제에 나와 있는 것처럼 kwargs를 별도로 나열하지 않습니다.
def call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete, then
return the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()
A-B-B의 질문에 대한 이 답변을 포함하는 이유는 코드에 대한 통찰력과 영감을 얻기 위해 모듈의 소스 또는 설명서를 이러한 방식으로 검토할 수 있다는 점에 주목할 가치가 있기 때문입니다.
만약 당신이 이것을 numpydoc 스타일로 하는 방법을 찾고 있다면, 2018년 판다 문서 스프린트의 spinx 확장 나폴레옹과 docstring 가이드의 numpydoc 예에서 설명한 것처럼 유형을 지정하지 않고 매개변수 섹션에서 간단히 언급할 수 있습니다.
다음은 LSST 개발자 가이드에서 찾은 예로, 설명이 무엇이어야 하는지를 매우 잘 설명합니다.**kwargs매개변수:
def demoFunction(namedArg, *args, flag=False, **kwargs):
"""Demonstrate documentation for additional keyword and
positional arguments.
Parameters
----------
namedArg : `str`
A named argument that is documented like always.
*args : `str`
Additional names.
Notice how the type is singular since the user is expected to pass individual
`str` arguments, even though the function itself sees ``args`` as an iterable
of `str` objects).
flag : `bool`
A regular keyword argument.
**kwargs
Additional keyword arguments passed to `otherApi`.
Usually kwargs are used to pass parameters to other functions and
methods. If that is the case, be sure to mention (and link) the
API or APIs that receive the keyword arguments.
If kwargs are being used to generate a `dict`, use the description to
document the use of the keys and the types of the values.
"""
또는 @Jonas Adler가 제안한 내용을 바탕으로 matplotlib 설명서 가이드의 이 예에서도 섹션에 및 설명을 추가하는 것이 더 낫습니다.
다른 사람이 유효한 구문을 찾고 있다면..다음은 문서 문자열의 예입니다.제가 이렇게 했을 뿐인데, 여러분들에게 유용하기를 바라지만, 특별히 어떤 것에도 부합한다고 주장할 수는 없습니다.
def bar(x=True, y=False):
"""
Just some silly bar function.
:Parameters:
- `x` (`bool`) - dummy description for x
- `y` (`string`) - dummy description for y
:return: (`string`) concatenation of x and y.
"""
return str(x) + y
def foo (a, b, **kwargs):
"""
Do foo on a, b and some other objects.
:Parameters:
- `a` (`int`) - A number.
- `b` (`int`, `string`) - Another number, or maybe a string.
- `\**kwargs` - remaining keyword arguments are passed to `bar`
:return: Success
:rtype: `bool`
"""
return len(str(a) + str(b) + bar(**kwargs)) > 20
이것은 사용하는 문서 유형에 따라 다르지만, numpydoc 스타일을 사용하는 경우 문서화하는 것이 좋습니다.**kwargs…을 사용하여
예를 들어, 쿼니안의 예는 다음과 같습니다.
def some_function(first, second="two", **kwargs):
"""Fetches and returns this thing
Parameters
----------
first : `int`
The first parameter
second : `str`, optional
The second parameter
Other Parameters
----------------
extra : `list`, optional
Extra stuff. Default ``[]``.
suplement : `dict`, optional
Additional content. Default ``{'key' : 42}``.
"""
특히 기본값은 기능 서명에서 명확하지 않으므로 기본값을 지정하는 것이 좋습니다.
문서에 대한 실제 링크를 찾을 수 없지만 작동합니다(스핑크스 3.4.3 사용).
class Foo:
"""A Foo implementation
:param str foo: Foo
:param int bar: Bar
:keyword str key1: kwarg 1
:keyword str key2: kwarg 2
:keyword int key3: kwarg 3
"""
def __init__(self, foo, bar, **kwargs):
pass
저는 -모듈의 문서가 좋은 예라고 생각합니다.상위/상위 클래스에 대한 모든 매개 변수의 전체 목록을 제공합니다.그럼 그 목록을 참조해서 다른 모든 사건들을 확인하세요.**kwargs.
언급URL : https://stackoverflow.com/questions/1137161/what-is-the-correct-way-to-document-a-kwargs-parameter
'programing' 카테고리의 다른 글
| 중복 키 + 자동 증분 문제 mysql (0) | 2023.08.24 |
|---|---|
| MySQL: 다른 datetime 필드에 datetime 삽입 (0) | 2023.08.24 |
| 파이썬 코드 라인이 들여쓰기 중첩 수준을 알 수 있습니까? (0) | 2023.08.24 |
| 웹 사이트에서 IE9이 호환 모드로 전환되는 이유는 무엇입니까? (0) | 2023.08.24 |
| IE에서 .change()를 인식하도록 jQuery를 가져오는 중 (0) | 2023.08.24 |