API Reference¶

Annotation rendering¶

sphinx_autodoc_typehints_gp.build_annotation_paragraph(annotation, env, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.build_annotation_paragraph(annotation, env, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return a paragraph containing rendered annotation nodes.

Parameters:

annotation (Any) – Annotation object or raw string.
env (BuildEnvironment) – Sphinx build environment used to create pending_xref nodes.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Paragraph containing the rendered annotation nodes.

Return type:

nodes.paragraph

Examples

>>> build_annotation_paragraph
<function build_annotation_paragraph at 0x...>

sphinx_autodoc_typehints_gp.build_annotation_display_paragraph(annotation, env, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.build_annotation_display_paragraph(annotation, env, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return a paragraph using the shared display policy for annotations.

Literal-only union displays collapse to a literal enum marker so table cells and fact rows stay compact. All other annotations render through the standard shared annotation-node pipeline.

Parameters:

annotation (Any) – Annotation object or raw string.
env (BuildEnvironment | None) – Sphinx build environment used to create pending_xref nodes. When omitted, the helper falls back to a plain literal rendering for non-enum displays.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text before applying the display policy.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Paragraph containing either the compact enum marker or the rendered annotation nodes.

Return type:

nodes.paragraph

Examples

>>> paragraph = build_annotation_display_paragraph(
...     "Literal['open', 'closed']",
...     None,
... )
>>> paragraph.astext()
'enum'
>>> build_annotation_display_paragraph("str", None).astext()
'str'

sphinx_autodoc_typehints_gp.build_resolved_annotation_paragraph(annotation, app, docname, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.build_resolved_annotation_paragraph(annotation, app, docname, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return a paragraph with any late-added annotation xrefs resolved.

Parameters (10)

Parameters:

annotation (Any) – Annotation object or raw string.
app (Sphinx) – Sphinx application used for environment and builder access.
docname (str) – Current document name used for reference resolution.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Paragraph containing resolved annotation nodes.

Return type:

nodes.paragraph

Examples

>>> build_resolved_annotation_paragraph
<function build_resolved_annotation_paragraph at 0x...>

sphinx_autodoc_typehints_gp.build_resolved_annotation_display_paragraph(annotation, app, docname, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.build_resolved_annotation_display_paragraph(annotation, app, docname, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return a resolved paragraph using the shared annotation display policy.

Parameters (10)

Parameters:

annotation (Any) – Annotation object or raw string.
app (Sphinx) – Sphinx application used for environment and builder access.
docname (str) – Current document name used for reference resolution.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text before applying the display policy.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Paragraph containing either the compact enum marker or resolved annotation nodes.

Return type:

nodes.paragraph

Examples

>>> app = t.cast("Sphinx", object())
>>> paragraph = build_resolved_annotation_display_paragraph(
...     "Literal['open', 'closed']",
...     app,
...     "index",
... )
>>> paragraph.astext()
'enum'

sphinx_autodoc_typehints_gp.render_annotation_nodes(annotation, env, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.render_annotation_nodes(annotation, env, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶

Render annotation content into Sphinx/docutils nodes.

Parameters:

annotation (Any) – Annotation object or raw string.
env (BuildEnvironment) – Sphinx build environment used to create pending_xref nodes.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Annotation nodes ready for insertion into a paragraph or table cell.

Return type:

list[Node]

Examples

>>> render_annotation_nodes
<function render_annotation_nodes at 0x...>

Annotation text and classification¶

sphinx_autodoc_typehints_gp.normalize_annotation_text(annotation, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.normalize_annotation_text(annotation, *, strip_none=False, collapse_literal=False, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return deterministic plain-text annotation content.

Parameters:

annotation (Any) – Annotation object or raw string.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit import or name aliases used to qualify string annotations.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Stable plain-text annotation.

Return type:

str

Examples

>>> normalize_annotation_text(int)
'int'
>>> normalize_annotation_text(
...     "Session",
...     module_name="libtmux.session",
...     qualify_unresolved=True,
... )
'libtmux.session.Session'
>>> normalize_annotation_text(
...     "Literal['open', 'closed']",
...     collapse_literal=True,
... )
"'open', 'closed'"

sphinx_autodoc_typehints_gp.normalize_type_collection_text(types, *, default) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.normalize_type_collection_text(types, *, default) ¶

Return a readable type expression for Sphinx config-like metadata.

Parameters:

types (object) – Config-style types value from app.add_config_value().
default (object) – Config default used when no explicit types are present.

Returns:

Human-readable type expression.

Return type:

str

Examples

>>> normalize_type_collection_text((bool, str))
'bool | str'
>>> normalize_type_collection_text((), default=None)
'None'

sphinx_autodoc_typehints_gp.classify_annotation_display(annotation, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.classify_annotation_display(annotation, *, strip_none=False, collapse_literal=True, module_name=None, aliases=None, qualify_unresolved=False) ¶

Return normalized annotation text plus enum-display metadata.

Parameters:

annotation (Any) – Annotation object or raw string.
strip_none (bool) – When True, drop None from X | None unions.
collapse_literal (bool) – When True, collapse Literal[...] to its member text before determining whether the display is enum-like.
module_name (str | None) – Module context used when resolving forward-reference strings.
aliases (dict[str, str] | None) – Explicit alias mapping used to qualify annotation names.
qualify_unresolved (bool) – When True, unqualified non-builtin names are resolved relative to module_name.

Returns:

Normalized text plus literal-enum classification metadata.

Return type:

AnnotationDisplay

Examples

>>> display = classify_annotation_display("Literal['open', 'closed']")
>>> display.text
"'open', 'closed'"
>>> display.literal_members
("'open'", "'closed'")
>>> classify_annotation_display("str | None", strip_none=True).is_literal_enum
False

class sphinx_autodoc_typehints_gp.AnnotationDisplay ¶ class[source] class[source] class sphinx_autodoc_typehints_gp.AnnotationDisplay ¶

Bases: object

Normalized annotation display metadata for UI and table renderers.

Examples

>>> display = AnnotationDisplay(
...     text="'open', 'closed'",
...     is_literal_enum=True,
...     literal_members=("'open'", "'closed'"),
... )
>>> display.is_literal_enum
True

Extension entry point¶

sphinx_autodoc_typehints_gp.setup(app) ¶ function[source] function[source] sphinx_autodoc_typehints_gp.setup(app) ¶

Set up the Sphinx extension.

Parameters:: app (Sphinx) – The Sphinx application instance.
Returns:: The extension metadata.
Return type:: dict[str, t.Any]

Examples

>>> setup
<function setup at 0x...>