attr_utils.autoattrs

Sphinx directive for documenting attrs classes.

New in version 0.1.0.

Attention

Due to changes in the typing module autoattrs is only officially supported on Python 3.7 and above.

Attention

This module has the following additional requirements:

sphinx<7,>=3.2.0
sphinx-toolbox>=3.3.0

These can be installed as follows:

python -m pip install attr-utils[sphinx]
.. autoattrs::

Autodoc directive to document an attrs class.

It behaves much like autoclass. It can be used directly or as part of automodule.

Docstrings for parameters in __init__ can be given in the class docstring or alongside each attribute (see autoattribute for the syntax). The second option is recommended as it interacts better with other parts of autodoc. However, the class docstring can be used to override the description for a given parameter.

:no-init-attribs: (flag)

Excludes attributes taken as arguments in __init__ from the output, even if they are documented.

This may be useful for simple classes where converter functions aren’t used.

This option cannot be used as part of automodule.

API Reference

Classes:

AttrsDocumenter(​*args)

Sphinx autodoc Documenter for documenting attrs classes.

Functions:

setup(​app)

Setup attr_utils.autoattrs.
class AttrsDocumenter(*args)[source]

Bases: PatchedAutoSummClassDocumenter

Sphinx autodoc Documenter for documenting attrs classes.

Changed in version 0.3.0:

  • Parameters for __init__ can be documented either in the class docstring or alongside the attribute. The class docstring has priority.

  • Added support for autodocsumm.

Methods:

can_document_member(​member, membername, …)

Called to see if a member can be documented by this documenter.

add_content(​more_content[, no_docstring])

Add extra content (from docstrings, attribute docs etc.), but not the class docstring.

import_object(​[raiseerror])

Import the object given by self.modname and self.objpath and set it as self.object.

sort_members(​documenters, order)

Sort the given member list and add attribute docstrings to the class docstring.

filter_members(​members, want_all)

Filter the list of members to always include init attributes unless the :no-init-attribs: flag was given.

generate(​[more_content, real_modname, …])

Generate reST for the object given by self.name, and possibly for its members.
classmethod can_document_member(member, membername, isattr, parent)[source]

Called to see if a member can be documented by this documenter.

Parameters
Return type

bool

add_content(more_content, no_docstring=False)[source]

Add extra content (from docstrings, attribute docs etc.), but not the class docstring.

Parameters
import_object(raiseerror=False)[source]

Import the object given by self.modname and self.objpath and set it as self.object.

If the object is an attrs class attr_utils.docstrings.add_attrs_doc() will be called.

Parameters

raiseerror (bool) – Default False.

Return type

bool

Returns

True if successful, False if an error occurred.

sort_members(documenters, order)[source]

Sort the given member list and add attribute docstrings to the class docstring.

Parameters
Return type

List[Tuple[Documenter, bool]]

filter_members(members, want_all)[source]

Filter the list of members to always include init attributes unless the :no-init-attribs: flag was given.

Parameters
Return type

List[Tuple[str, Any, bool]]

generate(more_content=None, real_modname=None, check_module=False, all_members=False)[source]

Generate reST for the object given by self.name, and possibly for its members.

Parameters

  • more_content (Optional[Any]) – Additional content to include in the reST output. Default None.

  • real_modname (Optional[str]) – Module name to use to find attribute documentation. Default None.

  • check_module (bool) – If True, only generate if the object is defined in the module name it is imported from. Default False.

  • all_members (bool) – If True, document all members. Default False.

setup(app)[source]

Setup attr_utils.autoattrs.

Parameters

app (Sphinx)

Return type

SphinxExtMetadata