a_sync.sphinx package

Submodules

a_sync.sphinx.ext module

Sphinx documentation plugin used to document ASyncFunction instances.

Introduction

Usage

The ez-a-sync extension for Sphinx requires Sphinx 2.0 or later.

Add the extension to your docs/conf.py configuration module:

extensions = (...,
              'a_sync.sphinx.ext')

If you’d like to change the prefix for tasks in reference documentation then you can change the a_sync_function_prefix configuration value:

a_sync_function_prefix = '(function)'  # < default
a_sync_descriptor_prefix = '(descriptor)'  # < default
a_sync_generator_function_prefix = '(genfunc)'  # < default

With the extension installed autodoc will automatically find ASyncFunction objects (e.g. when using the automodule directive) and generate the correct (as well as add a (function) prefix), and you can also refer to the tasks using :task:proj.tasks.add syntax.

Use .. autotask:: to alternatively manually document a task.

class a_sync.sphinx.ext.ASyncDescriptorDirective[source]

Bases: _ASyncMethodDirective

Directive for ASyncDescriptor instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'abstractmethod': <function flag>, 'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'classmethod': <function flag>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'staticmethod': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str = 'a_sync_descriptor_prefix'
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext.ASyncDescriptorDocumenter[source]

Bases: _ASyncMethodDocumenter

Document ASyncDescriptor instance definitions.

typ

alias of ASyncDescriptor

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()

Format the arguments of the wrapped method.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

directivetype = 'method'
property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 50

order if autodoc_member_order is set to ‘groupwise’

objtype = 'a_sync_descriptor'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 1

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

class a_sync.sphinx.ext.ASyncFunctionAsyncDirective[source]

Bases: _ASyncFunctionDirective

Directive for ASyncFunctionAsyncDefault instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str = 'a_sync_function_async_prefix'
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext.ASyncFunctionAsyncDocumenter[source]

Bases: _ASyncFunctionDocumenter

Document ASyncFunctionAsyncDefault instance definitions.

typ

alias of ASyncFunctionAsyncDefault

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()

Format the arguments of the wrapped function.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

objtype = 'a_sync_function_async'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 13

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

class a_sync.sphinx.ext.ASyncFunctionDirective[source]

Bases: _ASyncFunctionDirective

Directive for ASyncFunction instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str = 'a_sync_function_prefix'
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext.ASyncFunctionDocumenter[source]

Bases: _ASyncFunctionDocumenter

Document ASyncFunction instance definitions.

typ

alias of ASyncFunction

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()

Format the arguments of the wrapped function.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

objtype = 'a_sync_function'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 15

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

class a_sync.sphinx.ext.ASyncFunctionSyncDirective[source]

Bases: _ASyncFunctionDirective

Directive for ASyncFunctionSyncDefault instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str = 'a_sync_function_sync_prefix'
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext.ASyncFunctionSyncDocumenter[source]

Bases: _ASyncFunctionDocumenter

Document ASyncFunctionSyncDefault instance definitions.

typ

alias of ASyncFunctionSyncDefault

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()

Format the arguments of the wrapped function.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

objtype = 'a_sync_function_sync'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 14

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

class a_sync.sphinx.ext.ASyncGeneratorFunctionDirective[source]

Bases: _ASyncFunctionDirective

Directive for ASyncGeneratorFunction instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str = 'a_sync_generator_function_prefix'
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext.ASyncGeneratorFunctionDocumenter[source]

Bases: _ASyncFunctionDocumenter

Document ASyncGeneratorFunction instance definitions.

typ

alias of ASyncGeneratorFunction

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()

Format the arguments of the wrapped function.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

objtype = 'a_sync_generator_function'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 0

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

class a_sync.sphinx.ext._ASyncDirective[source]

Bases: object

Base class for ASync directives.

get_signature_prefix(sig)[source]

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

prefix_env: str
class a_sync.sphinx.ext._ASyncFunctionDirective[source]

Bases: _ASyncDirective, PyFunction

Directive for ASyncFunction instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext._ASyncFunctionDocumenter[source]

Bases: _ASyncWrapperDocumenter, FunctionDocumenter

Documenter for ASyncFunction instances.

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()[source]

Format the arguments of the wrapped function.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

objtype = 'function'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 0

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

typ: type
class a_sync.sphinx.ext._ASyncMethodDirective[source]

Bases: _ASyncDirective, PyMethod

Directive for ASyncMethod instances.

__init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
_object_hierarchy_parts(sig_node)

Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g. ('module', 'submodule', 'Class', 'method')). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the _toc_entry_name() method.

This method must not be used outwith table of contents generation.

Parameters:

sig_node (desc_signature)

Return type:

tuple[str, …]

_toc_entry_name(sig_node)

Returns the text of the table of contents entry for the object.

This function is called once, in run(), to set the name for the table of contents entry (a special attribute _toc_name is set on the object node, later used in environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() when the table of contents entries are collected).

To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting toc_object_entries_show_parents. Domains must also override _object_hierarchy_parts(), with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed as sig_node['_toc_parts'] for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.

An example implementations of this method is within the python domain (PyObject._toc_entry_name()). The python domain sets the _toc_parts attribute within the handle_signature() method.

Parameters:

sig_node (desc_signature)

Return type:

str

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

add_target_and_index(name_cls, sig, signode)

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

Parameters:
Return type:

None

after_content()

Handle object de-nesting after content

If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.

If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in before_content().

Return type:

None

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

before_content()

Handle object nesting before content

PyObject represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, in after_content().

For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with after_content().

Return type:

None

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

error(message)
get_field_type_map()
Return type:

dict[str, tuple[Field, bool]]

get_index_text(modname, name_cls)

Return the text for the index entry of the object.

Parameters:
Return type:

str

get_location()

Get current location info for logging.

Added in version 4.2.

Return type:

str

get_signature_prefix(sig)

Get the signature prefix for the directive.

Parameters:

sig – The signature to process.

Returns:

A list of nodes representing the signature prefix.

Return type:

list

get_signatures()

Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.

Return type:

list[str]

get_source_info()

Get source and line number.

Added in version 3.0.

Return type:

tuple[str, int]

handle_signature(sig, signode)

Transform a Python signature into RST nodes.

Return (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

Parameters:

  • sig (str)

  • signode (desc_signature)

Return type:

tuple[str, str]

info(message)
needs_arglist()

May return true if an empty argument list is to be generated even if the document contains none.

Return type:

bool

parse_content_to_nodes(allow_section_headings=False)

Parse the directive’s content into nodes.

Parameters:

allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Return type:

list[Node]

Added in version 7.4.

parse_inline(text, *, lineno=-1)

Parse text as inline elements.

Parameters:

  • text (str) – The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno (int) – The line number where the interpreted text begins.

Returns:

A list of nodes (text and inline elements) and a list of system_messages.

Return type:

tuple[list[Node], list[system_message]]

Added in version 7.4.

parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)

Parse text into nodes.

Parameters:

  • text (str) – Text, in string form. StringList is also accepted.

  • allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset (int) – The offset of the content.

Return type:

list[Node]

Added in version 7.4.

run()

Main directive entry function, called by docutils upon encountering the directive.

This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:

  • find out if called as a domain-specific directive, set self.domain

  • create a desc node to fit all description inside

  • parse standard options, currently no-index

  • create an index node if needed as self.indexnode

  • parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError

  • add index entries using self.add_target_and_index()

  • parse the content and handle doc fields in it

Return type:

list[Node]

set_source_info(node)

Set source and line number to the node.

Added in version 2.1.

Parameters:

node (Node)

Return type:

None

severe(message)
transform_content(content_node)

Called after creating the content through nested parsing, but before the object-description-transform event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.

Parameters:

content_node (desc_content)

Return type:

None

warning(message)
_doc_field_type_map: dict[str, tuple[Field, bool]] = {}
allow_nesting = False
property config: Config

Reference to the Config object.

Added in version 1.8.

doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
domain: str | None = None
property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = True

May the final argument contain whitespace?

has_content = True

May the directive have content?

indexnode: addnodes.index
objtype: str
option_spec: ClassVar[OptionSpec] = {'abstractmethod': <function flag>, 'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'classmethod': <function flag>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'staticmethod': <function flag>}

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

prefix_env: str
required_arguments = 1

Number of required directive arguments.

class a_sync.sphinx.ext._ASyncMethodDocumenter[source]

Bases: _ASyncWrapperDocumenter, MethodDocumenter

Documenter for ASyncMethod instances.

__init__(directive, name, indent='')
Parameters:

  • directive (DocumenterBridge)

  • name (str)

  • indent (str)

Return type:

None

_call_format_args(**kwargs)
Parameters:

kwargs (Any)

Return type:

str

_find_signature()
Return type:

tuple[str | None, str | None] | None

add_content(more_content)

Add content from docstrings, attribute documentation and user.

Parameters:

more_content (StringList | None)

Return type:

None

add_directive_header(sig)

Add the directive header and options to the generated content.

Parameters:

sig (str)

Return type:

None

add_line(line, source, *lineno)

Append one line of generated reST to the output.

Parameters:
Return type:

None

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

Parameters:

  • func (Callable)

  • typ (type)

Return type:

Callable | None

classmethod can_document_member(member, membername, isattr, parent)

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

filter_members(members, want_all)

Filter the given member list.

Members are skipped if

  • they are private (except if given explicitly or the private-members option is set)

  • they are special methods (except if given explicitly or the special-members option is set)

  • they are undocumented (except if the undoc-members option is set)

The user can override the skipping decision by connecting to the autodoc-skip-member event.

Parameters:

  • members (list[ObjectMember])

  • want_all (bool)

Return type:

list[tuple[str, Any, bool]]

format_args()[source]

Format the arguments of the wrapped method.

Returns:

The formatted arguments.

Return type:

str

format_name()

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

Return type:

str

format_signature(**kwargs)

Format the signature (arguments and return annotation) of the object.

Let the user process it via the autodoc-process-signature event.

Parameters:

kwargs (Any)

Return type:

str

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

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

If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.

Parameters:

  • more_content (StringList | None)

  • real_modname (str | None)

  • check_module (bool)

  • all_members (bool)

Return type:

None

get_attr(obj, name, *defargs)

getattr() override for types such as Zope interfaces.

Parameters:
Return type:

Any

get_doc()

Decode and return lines of the docstring(s) for the object.

When it returns None, autodoc-process-docstring will not be called for this object.

Return type:

list[list[str]] | None

get_object_members(want_all)

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be None).

Parameters:

want_all (bool)

Return type:

tuple[bool, list[ObjectMember]]

get_real_modname()

Get the real module name of an object to document.

It can differ from the name of the module through which the object was imported.

Return type:

str

get_sourcename()
Return type:

str

import_object(raiseerror=False)

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

Returns True if successful, False if an error occurred.

Parameters:

raiseerror (bool)

Return type:

bool

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

Parameters:
Return type:

Signature

parse_name()

Determine what module to import and what attribute to document.

Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.

Return type:

bool

process_doc(docstrings)

Let the user process the docstrings before adding them.

Parameters:

docstrings (list[list[str]])

Return type:

Iterator[str]

resolve_name(modname, parents, path, base)

Resolve the module and name of the object to document given by the arguments and the current module/class.

Must return a pair of the module name and a chain of attributes; for example, it would return ('zipfile', ['ZipFile', 'open']) for the zipfile.ZipFile.open method.

Parameters:
Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:
Return type:

list[tuple[Documenter, bool]]

_new_docstrings: list[list[str]] | None = None
_signatures: list[str] = []
content_indent = '   '

indentation by which to indent the directive content

directivetype = 'method'
property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

member_order = 50

order if autodoc_member_order is set to ‘groupwise’

objtype = 'method'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
priority = 1

priority if multiple documenters return True from can_document_member

titles_allowed = True

true if the generated content may contain titles

typ: type
class a_sync.sphinx.ext._ASyncWrapperDocumenter[source]

Bases: object

Base class for documenters that handle wrapped ASync functions.

classmethod can_document_member(member, membername, isattr, parent)[source]

Determine if the member can be documented by this documenter.

Parameters:

  • member – The member to check.

  • membername – The name of the member.

  • isattr – Boolean indicating if the member is an attribute.

  • parent – The parent object.

Returns:

True if the member can be documented, False otherwise.

Return type:

bool

check_module()[source]

Check if the object is defined in the expected module.

Returns:

True if the object is defined in the expected module, False otherwise.

Return type:

bool

Note

Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.

document_members(all_members=False)[source]

Document members of the object.

Parameters:

all_members – Boolean indicating if all members should be documented.

typ: type
a_sync.sphinx.ext.autodoc_skip_member_handler(app, what, name, obj, skip, options)[source]

Handler for autodoc-skip-member event.

Parameters:

  • app – The Sphinx application object.

  • what – The type of the object being documented.

  • name – The name of the object.

  • obj – The object itself.

  • skip – Boolean indicating if the member should be skipped.

  • options – The options for the autodoc directive.

Returns:

True if the member should be skipped, False otherwise.

Return type:

bool

a_sync.sphinx.ext.setup(app)[source]

Setup Sphinx extension.

Parameters:

app – The Sphinx application object.

Returns:

A dictionary with metadata about the extension.

Return type:

dict

Module contents