Python domain customization¶

python_type_aliases : dict[str, str] = {}¶

Maps names or dotted names appearing in type annotations in Python signatures to the corresponding fully-qualified name.

An entire module can be mapped by specifying a source name that ends in ".". The target name must either:

• end in ".", to transform the source module name to a different module name; or

• be the empty string "", to map the module name to the global namespace.

Note

This substitution happens before cross references are resolved, and affects both the cross-reference target and the displayed text. Therefore, the target name must be a valid cross-reference target if cross-referencing is desired. In contrast, the python_module_names_to_strip_from_xrefs affects only the displayed text, not the cross-reference target.

For example, to:

• map MyUnqualifiedType to alias_ex.MyUnqualifiedType, and

• map the example_mod._internal module to example_mod,

add the following to conf.py:

python_type_aliases = {
    "MyUnqualifiedType": "alias_ex.MyUnqualifiedType",
    "example_mod._internal.": "example_mod.",
}

Python signature modified by type alias¶

.. py:function:: foo(a: MyUnqualifiedType, \
                     b: example_mod._internal.Foo) -> str
   :noindex:

   Function description.

foo(a: alias_ex.MyUnqualifiedType, b: example_mod.Foo) -> str

Function description.

python_resolve_unqualified_typing : bool = True¶

Specifies whether to add the following mappings to python_type_aliases:

• Any -> typing.Any

• Tuple -> typing.Tuple

• Optional -> typing.Optional

• Union -> typing.Union

• Literal -> typing.Literal

• Callable -> typing.Callable

• List -> typing.List

• Dict -> typing.Dict

• Set -> typing.Set

• FrozenSet -> typing.FrozenSet

• Sequence -> typing.Sequence

• Type -> typing.Type

If python_transform_type_annotations_pep585 is also set to True, then these aliases are additionally subject to that mapping.

python_transform_type_annotations_pep585 : bool = True¶

Specifies whether to add the following PEP 585 mappings to python_type_aliases:

• typing.Tuple -> tuple

• typing.List -> list

• typing.Dict -> dict

• typing.DefaultDict -> collections.defaultdict

• typing.OrderedDict -> collections.OrderedDict

• typing.Counter -> collections.Counter

• typing.Set -> set

• typing.Callable -> collections.abc.Callable

• typing.Deque -> collections.deque

• typing.FrozenSet -> frozenset

• typing.Type -> type

• typing.AbstractSet -> collections.abc.Set

• typing.ByteString -> collections.abc.ByteString

• typing.Collection -> collections.abc.Collection

• typing.Container -> collections.abc.Container

• typing.ItemsView -> collections.abc.ItemsView

• typing.KeysView -> collections.abc.KeysView

• typing.Mapping -> collections.abc.Mapping

• typing.MappingView -> collections.abc.MappingView

• typing.MutableMapping -> collections.abc.MutableMapping

• typing.MutableSequence -> collections.abc.MutableSequence

• typing.MutableSet -> collections.abc.MutableSet

• typing.Sequence -> collections.abc.Sequence

• typing.ValuesView -> collections.abc.ValuesView

• typing.Iterable -> collections.abc.Iterable

• typing.Iterator -> collections.abc.Iterator

• typing.Generator -> collections.abc.Generator

• typing.Hashable -> collections.abc.Hashable

• typing.Reversible -> collections.abc.Reversible

• typing.Sized -> collections.abc.Sized

• typing.Coroutine -> collections.abc.Coroutine

• typing.AsyncGenerator -> collections.abc.AsyncGenerator

• typing.AsyncIterable -> collections.abc.AsyncIterable

• typing.AsyncIterator -> collections.abc.AsyncIterator

• typing.Awaitable -> collections.abc.Awaitable

• typing.ContextManager -> contextlib.AbstractContextManager

• typing.AsyncContextManager -> contextlib.AbstractAsyncContextManager

• typing.Pattern -> re.Pattern

• typing.re.Pattern -> re.Pattern

• typing.Match -> re.Match

• typing.re.Match -> re.Match

python_transform_type_annotations_pep604 : bool = True¶

Converts type annotations involving typing.Optional, typing.Union, and/or typing.Literal to the more concise PEP 604 form.

.. py:function:: foo(x: typing.Optional[int], \
                     y: typing.Union[int, float])
   :noindex:

foo(x: int | None, y: int | float)

python_transform_type_annotations_concise_literal : bool = True¶

If set to True, converts typing.Literal[a] to a if a is a constant.

This option requires that python_transform_type_annotations_pep604 is also enabled.

.. py:function:: foo(x: typing.Literal[1, 2, "abc"])
   :noindex:

.. py:function:: foo(x: ~typing.Literal[1, 2, "abc"])
   :noindex:

foo(x: 1 | 2 | "abc")

foo(x: 1 | 2 | "abc")

Warning

The concise syntax is non-standard and not accepted by Python type checkers.

python_transform_typing_extensions : bool = True¶

Transforms a reference to typing_extensions.X within a type annotation into a reference to typing.X.

python_strip_self_type_annotations : bool = True¶

Strip type annotations from the initial self parameter of methods.

Since the self type is usually evident from the context, removing them may improve readability of the documentation.

Note

This option is useful when generating documentation from pybind11 modules, as pybind11 adds these type annotations.

.. py:class:: Example
   :noindex:

   .. py:method:: foo(self: Example, a: int) -> int
      :noindex:

      Does something with the object.

class Example

foo(self, a: int) -> int

Does something with the object.

python_module_names_to_strip_from_xrefs : list[str] = []¶

List of module names to strip from cross references. This option does not have any effect on the cross-reference target; it only affects what is displayed.

For example, to hide the tensorstore_demo module name in cross references, add the following to conf.py:

python_module_names_to_strip_from_xrefs = ["tensorstore_demo"]

Python signature modified by module name stripping¶

.. py:function:: foo(a: tensorstore_demo.Dim) -> str
   :noindex:

   Function description.

foo(a: Dim) -> str

Function description.

See also

To strip all modules, rather than a limited set, the built-in python_use_unqualified_type_names configuration option may be used instead.

python_strip_return_type_annotations : re.Pattern | None = '.*.(__setitem__|__init__)'¶

Regular expression pattern that matches the full name (including module) of functions for which any return type annotations should be stripped.

Setting this to None disables stripping of return type annotations.

By default, the return type is stripped from __init__ and __setitem__ functions (which usually return None).

Note

This option is useful when generating documentation from pybind11 modules, as pybind11 adds these type annotations.

.. py:class:: Example
   :noindex:

   .. py:method:: __setitem__(self, a: int, b: int) -> None
      :noindex:

      Does something with the object.

class Example

__setitem__(self, a: int, b: int)

Does something with the object.

python_strip_property_prefix : bool = False¶

Strip the property prefix from py:property object descriptions.

Overloaded functions¶

The Sphinx Python domain supports documenting multiple signatures together as part of the same object description:

.. py:function:: overload_example1(a: int) -> int
                 overload_example1(a: float) -> float
                 overload_example1(a: str) -> str

   Does something with an `int`, `float`, or `str`.

However, it does not provide a way to document each overload with a separate description, except by using the :noindex: option to avoid a warning from duplicate definitions.

This theme extends the Python domain directives with an :object-ids: option to allow multiple overloads of a given function to be documented separately:

The value of the :object-ids: option must be a JSON-encoded array of strings, where each string specifies the full object name (including module name) to use for each signature. The object ids must start with the actual module name, if any, but the remainder of the id need not match the name specified in the signature.

.. py:function:: overload_example2(a: int) -> int
                 overload_example2(a: float) -> float
   :object-ids: ["overload_example2(int)", "overload_example2(float)"]

   Does something with an `int` or `float`.

.. py:function:: overload_example2(a: str) -> str
   :object-ids: ["overload_example2(str)"]

   Does something with a `str`.

If this option is specified, and generate_synopses is enabled, then a synopsis will be stored even if :noindex is also specified.

Separate page for object description¶

Normally, the Python domain generates an id attribute for each object description based on its full name. This may be used in a URL to target a specific object description, e.g. api/tensorstore.html#tensorstore.IndexDomain.

If an entire page is dedicated to a single object description, this id is essentially redundant, e.g. api/tensorstore.IndexDomain.html#tensorstore.IndexDomain.

This theme extends the Python domain directives (as well as the corresponding auto<objtype> directives provided by the sphinx.ext.autodoc extension) with a :nonodeid: option:

.. py:function:: func(a: int) -> int
   :nonodeid:

If this option is specified, the object description itself will not have an id, and any cross references to the object will simply target the page. Additionally, any table of contents entry for the page will have an associated icon if one has been configured for the object type.