sphinx.domains.python.PyObject

class documentation

class PyObject(ObjectDescription[Tuple[str, str]]): (source)

Known subclasses: sphinx.domains.python.PyAttribute, sphinx.domains.python.PyClasslike, sphinx.domains.python.PyFunction, sphinx.domains.python.PyMethod, sphinx.domains.python.PyProperty, sphinx.domains.python.PyVariable

View In Hierarchy

Description of a general Python object. :cvar allow_nesting: Class is an object that allows for nested namespaces :vartype allow_nesting: bool

Method	`add_target_and_index`	Add cross-reference IDs and entries to self.indexnode, if applicable.
Method	`after_content`	Handle object de-nesting after content
Method	`before_content`	Handle object nesting before content
Method	`get_index_text`	Return the text for the index entry of the object.
Method	`get_signature_prefix`	May return a prefix to put before the object name in the signature.
Method	`handle_signature`	Transform a Python signature into RST nodes.
Method	`needs_arglist`	May return true if an empty argument list is to be generated even if the document contains none.
Class Variable	`allow_nesting`	Undocumented
Class Variable	`doc_field_types`	Undocumented
Class Variable	`option_spec`	Undocumented
Method	`_object_hierarchy_parts`	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 :py:meth:`_toc_entry_name` method.
Method	`_toc_entry_name`	Returns the text of the table of contents entry for the object.

Inherited from ObjectDescription:

Method	`get_field_type_map`	Undocumented
Method	`get_signatures`	Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
Method	`run`	Main directive entry function, called by docutils upon encountering the directive.
Method	`transform_content`	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.
Class Variable	`final_argument_whitespace`	Undocumented
Class Variable	`has_content`	Undocumented
Class Variable	`optional_arguments`	Undocumented
Class Variable	`required_arguments`	Undocumented
Instance Variable	`domain`	Undocumented
Instance Variable	`indexnode`	Undocumented
Instance Variable	`names`	Undocumented
Instance Variable	`objtype`	Undocumented
Instance Variable	`_doc_field_type_map`	Undocumented

Inherited from SphinxDirective (via ObjectDescription):

Method	`get_location`	Get current location info for logging.
Method	`get_source_info`	Get source and line number.
Method	`set_source_info`	Set source and line number to the node.
Property	`config`	Reference to the :class:`.Config` object.
Property	`env`	Reference to the :class:`.BuildEnvironment` object.

def add_target_and_index(self, name_cls, sig, signode): (source) ¶

overrides sphinx.directives.ObjectDescription.add_target_and_index

overridden in sphinx.domains.python.PyFunction

Add cross-reference IDs and entries to self.indexnode, if applicable. *name* is whatever :meth:`handle_signature()` returned.

Parameters
name_cls:`tuple[str, str]`	Undocumented
sig:`str`	Undocumented
signode:`desc_signature`	Undocumented

def after_content(self): (source) ¶

overrides sphinx.directives.ObjectDescription.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 :py:meth:`before_content`.

def before_content(self): (source) ¶

overrides sphinx.directives.ObjectDescription.before_content

Handle object nesting before content :py:class:`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 :py:meth:`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 :py:meth:`after_content`.

def get_index_text(self, modname, name): (source) ¶

overridden in sphinx.domains.python.PyAttribute, sphinx.domains.python.PyClasslike, sphinx.domains.python.PyFunction, sphinx.domains.python.PyMethod, sphinx.domains.python.PyProperty, sphinx.domains.python.PyVariable

Return the text for the index entry of the object.

Parameters
modname:`str`	Undocumented
name:`tuple[str, str]`	Undocumented
Returns
`str`	Undocumented

def get_signature_prefix(self, sig): (source) ¶

overridden in sphinx.domains.python.PyClasslike, sphinx.domains.python.PyFunction, sphinx.domains.python.PyMethod, sphinx.domains.python.PyProperty

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

Parameters
sig:`str`	Undocumented
Returns
`list[nodes.Node]`	Undocumented

def handle_signature(self, sig, signode): (source) ¶

overrides sphinx.directives.ObjectDescription.handle_signature

overridden in sphinx.domains.python.PyAttribute, sphinx.domains.python.PyDecoratorFunction, sphinx.domains.python.PyDecoratorMethod, sphinx.domains.python.PyProperty, sphinx.domains.python.PyVariable

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`	Undocumented
signode:`desc_signature`	Undocumented
Returns
`tuple[str, str]`	Undocumented

def needs_arglist(self): (source) ¶

overridden in sphinx.domains.python.PyFunction, sphinx.domains.python.PyMethod

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

Returns
`bool`	Undocumented

allow_nesting: bool = (source) ¶

overridden in sphinx.domains.python.PyClasslike

Undocumented

doc_field_types = (source) ¶

overrides sphinx.directives.ObjectDescription.doc_field_types

Undocumented

option_spec: OptionSpec = (source) ¶

overrides sphinx.directives.ObjectDescription.option_spec

Undocumented

def _object_hierarchy_parts(self, sig_node): (source) ¶

overrides sphinx.directives.ObjectDescription._object_hierarchy_parts

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 :py:meth:`_toc_entry_name` method. This method must not be used outwith table of contents generation.

Parameters
sig_node:`desc_signature`	Undocumented
Returns
`tuple[str, ...]`	Undocumented

def _toc_entry_name(self, sig_node): (source) ¶

overrides sphinx.directives.ObjectDescription._toc_entry_name

Returns the text of the table of contents entry for the object. This function is called once, in :py:meth:`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 :py:meth:`_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 (:meth:`PyObject._toc_entry_name`). The python domain sets the ``_toc_parts`` attribute within the :py:meth:`handle_signature()` method.

Parameters
sig_node:`desc_signature`	Undocumented
Returns
`str`	Undocumented