Examples

The demos below exercise every rendering improvement sphinx-autodoc-typehints-gp ships beyond stock Sphinx + autodoc. Each section opens with a one-line “what’s interesting here”, then shows the rendered output from a small demo module (docs/_ext/api_demo_typehints_gp.py), then a callout pointing at the specific HTML shape worth noticing.

Source-text parameter defaults

autodoc_preserve_defaults=True is on by default in gp_sphinx.defaults, so each method’s =… default renders as the literal source text rather than the runtime repr(). Sentinel instances like <api_demo_typehints_gp._DefaultRetry object at 0x…> become the symbolic name DEFAULT_RETRY instead.

Dataclass field(default_factory=…) rendering

The synthetic-init listener walks dataclasses.fields(...) after Sphinx introspects the dataclass and substitutes the factory call’s source text. Stdlib container types render as their literal forms ([], {}, set(), frozenset(), ()); named callable factories render as Name().

class api_demo_typehints_gp.HookCounters

class

class

class api_demo_typehints_gp.HookCounters

Bases: object

Dataclass exercising every default-factory shape.

Each field uses field(default_factory=...) with a stdlib container type or a custom callable. After the synthetic-init listener runs, the rendered __init__ signature shows the factory call source text instead of =<factory>.

alerts: list[str]

attribute

attribute

alerts: list[str]

index: dict[str, int]

attribute

attribute

index: dict[str, int]

names: set[str]

attribute

attribute

names: set[str]

tags: tuple[str, ...]

attribute

attribute

tags: tuple[str, ...]

__init__(alerts=[], index={}, names=set(), tags=(), transports=[])

method

method

__init__(alerts=[], index={}, names=set(), tags=(), transports=[])

Parameters:

• alerts (list[str])

• index (dict[str, int])

• names (set[str])

• tags (tuple[str, ...])

• transports (list[Transport])

Return type:

None

transports: list[Transport]

attribute

attribute

transports: list[Transport]

What to look for: the __init__ signature shows alerts=[], index={}, names=set(), tags=(), transports=[] — no <factory> placeholders.

Long module-level constants

GpDataDocumenter / GpAttributeDocumenter route every :value: line through a resolver chain. TruncateLongRepr(threshold=200) collapses long values to <...truncated, N chars>; short values render unchanged.

api_demo_typehints_gp.SHORT_DEFAULT: str = 'admin'

data

data

api_demo_typehints_gp.SHORT_DEFAULT: str = 'admin'

A short, readable module-level constant — renders as-is.

api_demo_typehints_gp.LONG_DEFAULT_RULES: list[tuple[str, str]] = <...truncated, 930 chars>

data

data

api_demo_typehints_gp.LONG_DEFAULT_RULES: list[tuple[str, str]] = <...truncated, 930 chars>

A long list[tuple[str, str]] used as a documented constant.

The repr() exceeds the 200-char threshold so the rendered :value: collapses to <...truncated, N chars> instead of sprawling across the page.

What to look for: SHORT_DEFAULT shows 'admin' directly; LONG_DEFAULT_RULES shows <...truncated, N chars> instead of the 20-tuple list blob.

Cross-referenced default values

Stage C’s DefaultValueXrefTransform walks every <span class="default_value"> inside a <dt> signature, AST-parses the text, and turns documented identifier references into clickable cross-references in the same <a class="reference internal"> <code class="xref py py-obj">…</code></a> shape that inline :py:obj: roles produce. Undocumented or unparseable defaults fall back to plain text.

api_demo_typehints_gp.open_session(transport, *, scope=CacheScope.Session, retry=DEFAULT_RETRY, label='default')

function

function

api_demo_typehints_gp.open_session(transport, *, scope=CacheScope.Session, retry=DEFAULT_RETRY, label='default')

Open a session against transport.

The scope and retry defaults both reference documented targets on this same page; Stage C’s xref transform turns each documented identifier inside a default-value span into a clickable cross-reference using the canonical :py:obj:-styled HTML shape (<a class="reference internal" href="…"><code class="xref py py-obj">…</code></a>).

Parameters:

• transport (Transport) – The documented transport instance.

• scope (CacheScope) – Scope at which session state is cached.

• retry (_DefaultRetry) – Retry sentinel; pass an explicit policy to override.

• label (str) – Optional label propagated to log records.

Returns:

The same transport, now bound to the session.

Return type:

Transport

Raises:

ConnectionFailure – Raised when the transport cannot be opened after the retry policy is exhausted.

What to look for: the scope= and retry= defaults link to Session and DEFAULT_RETRY respectively. Hover the rendered defaults — they’re real anchors, not just styled text.

api_demo_typehints_gp.with_lambda_default(callback=lambda : ...)

function

function

api_demo_typehints_gp.with_lambda_default(callback=lambda : ...)

Demonstrate Stage C’s plain-text fallback for lambda defaults.

ast.parse of the default succeeds but the lambda branch isn’t handled by the xref transform; the rendered default sits as plain text inside the default_value span (no spurious <code class="xref"> styling that would imply a missing link target).

Parameters:

callback (object)

Return type:

None

What to look for: the callback=lambda: None default falls back to plain text inside the default_value span — no broken-looking <code class="xref"> styling on something that can’t link.

Field-list xref styling

FieldListXrefStyleTransform normalises every Python-domain pending_xref inside a field list to a single <a><code class="xref py py-class | py-exc">…</code></a> shape — the same HTML inline :py:class: roles produce. Parameter types, return types, and raises exception names all match. The whole name (type, optional) prefix on each parameter row is wrapped in <span class="gp-sphinx-field-prefix"> so a single CSS rule renders the prefix in monospace; Returns prose stays in body font.

The open_session autodoc above already demonstrates this — its Parameters, Return, and Raises sections each render the canonical shape on every Python identifier reference.

Documented targets used by the demos

class api_demo_typehints_gp.CacheScope

class

class

class api_demo_typehints_gp.CacheScope

Bases: Enum

Where a cached entry lives in the storage hierarchy.

Process = 'process'

attribute

attribute

Process = 'process'

Session = 'session'

attribute

attribute

Session = 'session'

Global = 'global'

attribute

attribute

Global = 'global'

class api_demo_typehints_gp.Transport

class

class

class api_demo_typehints_gp.Transport

Bases: object

Documented internal transport — referenced as a parameter type.

exception api_demo_typehints_gp.ConnectionFailure

exception

exception

exception api_demo_typehints_gp.ConnectionFailure

Bases: Exception

Raised when a connection attempt fails after exhausting retries.

api_demo_typehints_gp.DEFAULT_RETRY: _DefaultRetry = <api_demo_typehints_gp._DefaultRetry object>

data

data

api_demo_typehints_gp.DEFAULT_RETRY: _DefaultRetry = <api_demo_typehints_gp._DefaultRetry object>

Sentinel default for retry= parameters on connection helpers.

When retry is DEFAULT_RETRY the helper picks a transport-aware retry policy from the bound transport’s retry_policy attribute.

Copyable config snippet

extensions = [
    "sphinx_autodoc_typehints_gp",
    "sphinx_autodoc_typehints_gp.extension",
]