Skip to main content

No project description provided

Project description

numpydoc_decorator

This package allows you to build numpy-style docstrings programmatically and apply them using a decorator. This can be useful because:

  • Parts of your documentation, such as parameter descriptions, can be shared between functions, avoiding the need to repeat yourself.

  • Type information for parameters and return values is automatically picked up from type annotations and added to the docstring, avoiding the need to maintain type information in two places.

Installation

pip install numpydoc_decorator

Usage

Documentation a function

Here is an example of documenting a function:

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")

Here is the docstring that will be created and attached to the decorated function:

>>> 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!

Shared parameters

If you have parameters which are common to multiple functions, here is an approach you can take:

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

Here are the generated docstrings:

>>> 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.

Notes

There are probably lots of edge cases that this package has not covered yet. If you find something doesn't work as expected, or deviates from the numpydoc style guide in an unreasonable way, please feel free to submit a pull request.

Note that this package does deviate from the numpydoc style guide under some circumstances. For example, if a function does not have any type annotations, then there will be no type information in the docstring. The rationale for this is that all type information, if provided, should be provided through type annotations. However, some functions may choose not to annotate types for some or all parameters, but we still want to document them as best we can.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

numpydoc_decorator-1.6.0.tar.gz (10.3 kB view details)

Uploaded Source

Built Distribution

numpydoc_decorator-1.6.0-py3-none-any.whl (10.1 kB view details)

Uploaded Python 3

File details

Details for the file numpydoc_decorator-1.6.0.tar.gz.

File metadata

  • Download URL: numpydoc_decorator-1.6.0.tar.gz
  • Upload date:
  • Size: 10.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.1 CPython/3.10.8 Linux/5.15.0-1034-azure

File hashes

Hashes for numpydoc_decorator-1.6.0.tar.gz
Algorithm Hash digest
SHA256 6ebc4792aabe52c1672aa39004c2e8e3966830b4816b215bf9881fd136c2ef78
MD5 c9f2a8505665d8d282dbd45aae969ba0
BLAKE2b-256 4708bab64464f3960c72d68d1503f0d9e527cfeb0ee6f34175b770da3f32be00

See more details on using hashes here.

Provenance

File details

Details for the file numpydoc_decorator-1.6.0-py3-none-any.whl.

File metadata

  • Download URL: numpydoc_decorator-1.6.0-py3-none-any.whl
  • Upload date:
  • Size: 10.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.1 CPython/3.10.8 Linux/5.15.0-1034-azure

File hashes

Hashes for numpydoc_decorator-1.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3775e9044c2718459f9c87ff579d5d8d3eb66ddbbf12e96042235eebaa447184
MD5 d6374aa23ebeea5ce883f3636155a62d
BLAKE2b-256 d2aba28ebc68b25f92c1b2e2341cf7003be3c6103993ce1646106898101a2301

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page