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.

For example, to map MyUnqualifiedType to alias_ex.MyUnqualifiedType, add the following to conf.py:

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

Python signature modified by type alias¶

.. py:function:: foo(x: MyUnqualifiedType) -> str
   :noindex:

   Function description.

foo(x: alias_ex.MyUnqualifiedType) → 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_qualify_parameter_ids : bool = True¶

Specifies whether function parameters should be assigned fully-qualified ids (for cross-linking purposes) of the form <parent-id>.<param-name> based on the id of the parent declaration.

If set to False, instead the shorter unqualified id p-<param-name> is used. This option should only be set to False if each Python declaration is on a separate page.