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

Bases: _ASyncMethodDirective

Sphinx task directive.

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: _ASyncFunctionDirective

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

Bases: _ASyncFunctionDocumenter

Document ASyncFunction 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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: _ASyncFunctionDirective

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: _ASyncFunctionDirective

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

Bases: _ASyncFunctionDocumenter

Document ASyncFunction 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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: _ASyncFunctionDirective

Sphinx task directive.

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

Bases: _ASyncFunctionDocumenter

Document ASyncFunction 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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: object

get_signature_prefix(sig)

prefix_env: str

class a_sync.sphinx.ext._ASyncFunctionDirective

Bases: _ASyncDirective, PyFunction

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

Bases: _ASyncWrapperDocumenter, FunctionDocumenter

__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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: _ASyncDirective, PyMethod

__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:

• name_cls (tuple[str, str])

• sig (str)

• signode (desc_signature)

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:

• modname (str)

• name_cls (tuple[str, str])

Return type:

str

get_location()

Get current location info for logging.

Return type:

str

get_signature_prefix(sig)

May return a prefix to put before the object name in the signature.

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.

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.

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.

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.

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

Bases: _ASyncWrapperDocumenter, MethodDocumenter

__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:

• line (str)

• source (str)

• lineno (int)

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)

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

check_module()

Check if self.object is really defined in the module given by self.modname.

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

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 argument signature of self.object.

Should return None if the object does not have a signature.

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:

• obj (Any)

• name (str)

• defargs (Any)

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:

• actual (Signature)

• overload (Signature)

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:

• modname (str | None)

• parents (Any)

• path (str)

• base (str)

Return type:

tuple[str | None, list[str]]

sort_members(documenters, order)

Sort the given member list.

Parameters:

• documenters (list[tuple[Documenter, bool]])

• order (str)

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

Bases: object

classmethod can_document_member(member, membername, isattr, parent)

check_module()

document_members(all_members=False)

typ: type

a_sync.sphinx.ext.autodoc_skip_member_handler(app, what, name, obj, skip, options)

Handler for autodoc-skip-member event.

a_sync.sphinx.ext.setup(app)

Setup Sphinx extension.

Module contents