numpydoc_decorator

此软件包允许您以编程方式构建numpy风格的文档字符串，并使用装饰器应用它们。这可能很有用，因为

• 您的文档中的一些部分，如参数描述，可以在函数之间共享，从而避免重复。

• 参数和返回值的类型信息将自动从类型注解中提取并添加到文档字符串中，从而避免在两个地方维护类型信息。

安装

pip安装numpydoc_decorator

使用

记录函数

以下是记录函数的示例

from numpydoc_decorator import doc


@doc(
    summary="Say hello to someone.",
    extended_summary="""
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
        eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
        minim veniam, quis nostrud exercitation ullamco laboris nisi ut
        aliquip ex ea commodo consequat. Duis aute irure dolor in
        reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
        pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
        culpa qui officia deserunt mollit anim id est laborum.
    """,
    parameters=dict(
        name="The name of the person to greet.",
        language="The language in which to greet as an ISO 639-1 code.",
    ),
    returns="A pleasant greeting.",
    raises=dict(
        NotImplementedError="If the requested language has not been implemented yet.",
        ValueError="If the language is not a valid ISO 639-1 code."
    ),
    see_also=dict(
        print="You could use this function to print your greeting.",
    ),
    notes="""
        This function is useful when greeting someone else. If you would
        like something to talk about next, you could try [1]_.
    """,
    references={
        "1": """
            O. McNoleg, "The integration of GIS, remote sensing, expert systems
            and adaptive co-kriging for environmental habitat modelling of the
            Highland Haggis using object-oriented, fuzzy-logic and neural-
            network techniques," Computers & Geosciences, vol. 22, pp. 585-588,
            1996.
        """,
    },
    examples="""
        Here is how to greet a friend in English:

        >>> print(greet("Ford Prefect"))
        Hello Ford Prefect!

        Here is how to greet someone in another language:

        >>> print(greet("Tricia MacMillan", language="fr"))
        Salut Tricia MacMillan!

    """,
)
def greet(
    name: str,
    language: str = "en",
) -> str:
    if len(language) != 2:
        raise ValueError("language must be an ISO 639-1 code")
    if language == "en":
        return f"Hello {name}!"
    elif language == "fr":
        return f"Salut {name}!"
    else:
        raise NotImplementedError(f"language {language} not implemented")

以下是将要创建并附加到装饰函数上的文档字符串

>>> print(greet.__doc__)

Say hello to someone.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.

Parameters
----------
name : str
    The name of the person to greet.
language : str, optional, default: 'en'
    The language in which to greet as an ISO 639-1 code.

Returns
-------
str
    A pleasant greeting.

Raises
------
NotImplementedError
    If the requested language has not been implemented yet.
ValueError
    If the language is not a valid ISO 639-1 code.

See Also
--------
print : You could use this function to print your greeting.

Notes
-----
This function is useful when greeting someone else. If you would like
something to talk about next, you could try [1]_.

References
----------
.. [1] O. McNoleg, "The integration of GIS, remote sensing, expert systems
    and adaptive co-kriging for environmental habitat modelling of the
    Highland Haggis using object-oriented, fuzzy-logic and neural- network
    techniques," Computers & Geosciences, vol. 22, pp. 585-588, 1996.

Examples
--------
Here is how to greet a friend in English:

>>> print(greet("Ford Prefect"))
Hello Ford Prefect!

Here is how to greet someone in another language:

>>> print(greet("Tricia MacMillan", language="fr"))
Salut Tricia MacMillan!

共享参数

如果您有多个函数共有的参数，这里有一种您可以采取的方法

from numpydoc_decorator import doc
from typing_extensions import Annotated


class params:
    name = Annotated[str, "The name of a person."]
    language = Annotated[str, "An ISO 639-1 language code."]


@doc(
    summary="Say hello to someone you know.",
    returns="A personal greeting.",
)
def say_hello(
    name: params.name,
    language: params.language,
) -> str:
    pass


@doc(
    summary="Say goodbye to someone you know.",
    returns="A personal parting.",
)
def say_goodbye(
    name: params.name,
    language: params.language,
) -> str:
    pass

以下是生成的文档字符串

>>> print(say_hello.__doc__)

Say hello to someone you know.

Parameters
----------
name : str
    The name of a person.
language : str
    An ISO 639-1 language code.

Returns
-------
str
    A personal greeting.

>>> print(say_goodbye.__doc__)

Say goodbye to someone you know.

Parameters
----------
name : str
    The name of a person.
language : str
    An ISO 639-1 language code.

Returns
-------
str
    A personal parting.

或者，为了更明确地说明注解类型文档字符串的值，您可以使用typing_extensions.Doc，例如

from numpydoc_decorator import doc
from typing_extensions import Annotated, Doc


class params:
    name = Annotated[str, Doc("The name of a person.")]
    language = Annotated[str, Doc("An ISO 639-1 language code.")]


@doc(
    summary="Say hello to someone you know.",
)
def say_hello(
    name: params.name,
    language: params.language,
) -> Annotated[str, Doc("A personal greeting.")]:
    pass


@doc(
    summary="Say goodbye to someone you know.",
)
def say_goodbye(
    name: params.name,
    language: params.language,
) -> Annotated[str, Doc("A personal parting.")]:
    pass

Pydantic字段也通过description属性支持

from numpydoc_decorator import doc
from typing_extensions import Annotated
from pydantic import Field


class params:
    name = Annotated[str, Field(description="The name of a person.")]
    language = Annotated[str, Field(description="An ISO 639-1 language code.")]


@doc(
    summary="Say hello to someone you know.",
    returns="A personal greeting.",
)
def say_hello(
    name: params.name,
    language: params.language,
) -> str:
    pass


@doc(
    summary="Say goodbye to someone you know.",
    returns="A personal parting.",
)
def say_goodbye(
    name: params.name,
    language: params.language,
) -> str:
    pass

注意事项

此软件包可能还没有涵盖许多边缘情况。如果您发现某些功能无法按预期工作，或者以不合理的方式偏离了numpydoc风格指南，请随时提交拉取请求。

请注意，在某些情况下，此软件包可能会偏离numpydoc风格指南。例如，如果一个函数没有任何类型注解，那么文档字符串中将没有类型信息。这样做的原因是，如果提供了所有类型信息，则应通过类型注解提供。然而，某些函数可能选择不为某些或所有参数注释类型，但我们仍然希望尽可能多地记录它们。

特定案例说明

• 数据类：此包应与在 数据类 实现中使用的 dataclasses 包 兼容。然而，将 @doc 放在 @dataclass 之前或之上是很重要的。