Module

autodoc.utils

Utility functions for autodoc system.

Provides text sanitization and common helpers for all extractors.

Typed Metadata Access:

Helper functions for type-safe access to DocElement.typed_metadata
with fallback to untyped metadata dict. See get_* functions below.
View source
21 Functions

Functions

_convert_sphinx_roles
Convert reStructuredText-style cross-reference roles to inline code. Handles common reStructuredTe…
1 str 
def _convert_sphinx_roles(text: str) -> str

Convert reStructuredText-style cross-reference roles to inline code.

Handles common reStructuredText roles:

  • ClassNameorClassName→ClassName
  • function_name()→function_name()
  • method_name()→method_name()
  • module_name→module_name
  • attribute_name→attribute_name
  • ExceptionName→ExceptionName

Parameters 1

Name Type Default Description
text str —

Text containing reStructuredText roles

Returns

str —

Text with roles converted to inline code

sanitize_text
Clean user-provided text for markdown generation. This function is the single source of truth for …
1 str 
def sanitize_text(text: str | None) -> str

Clean user-provided text for markdown generation.

This function is the single source of truth for text cleaning across all autodoc extractors. It prevents common markdown rendering issues by:

  • Removing leading/trailing whitespace
  • Dedenting indented blocks (prevents accidental code blocks)
  • Normalizing line endings
  • Collapsing excessive blank lines

Parameters 1

Name Type Default Description
text str | None —

Raw text from docstrings, help text, or API specs

Returns

str —

Cleaned text safe for markdown generation

truncate_text
Truncate text to a maximum length, adding suffix if truncated.
3 str 
def truncate_text(text: str, max_length: int = 200, suffix: str = '...') -> str

Truncate text to a maximum length, adding suffix if truncated.

Parameters 3

Name Type Default Description
text str —

Text to truncate
max_length int 200

Maximum length (default: 200)
suffix str '...'

Suffix to add if truncated (default: '...')

Returns

str —

Truncated text

auto_detect_prefix_map
Auto-detect grouping from __init__.py hierarchy. Scans source directories for packages (directorie…
2 dict[str, str] 
def auto_detect_prefix_map(source_dirs: list[Path], strip_prefix: str = '') -> dict[str, str]

Auto-detect grouping from init.py hierarchy.

Scans source directories for packages (directories containing init.py) and builds a prefix map for every package path. Each entry maps the full dotted module path to its slash-separated path relative to the stripped prefix (e.g., "cli.templates" → "cli/templates"). Using the full path ensures nested packages stay under their parent directories (cli/templates lives under cli/).

Parameters 2

Name Type Default Description
source_dirs list[Path] —

Directories to scan for packages
strip_prefix str ''

Optional dotted prefix to remove from detected modules

Returns

dict[str, str] —

Prefix map: {"package.path": "group_path"}

apply_grouping
Apply grouping config to qualified module name.
2 tuple[str | None, str] 
def apply_grouping(qualified_name: str, config: dict[str, Any]) -> tuple[str | None, str]

Apply grouping config to qualified module name.

Parameters 2

Name Type Default Description
qualified_name str —

Full module name (e.g., "bengal.cli.templates.blog")
config dict[str, Any] —

Grouping config dict with mode and prefix_map

Returns

tuple[str | None, str] —

Tuple of (group_name, remaining_path):

  • group_name: Top-level group (or None if no grouping)
  • remaining_path: Path after group prefix

get_python_class_bases
Get class base classes with type-safe access.
1 tuple[str, ...] 
def get_python_class_bases(element: DocElement) -> tuple[str, ...]

Get class base classes with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "class"

Returns

tuple[str, ...] —

Tuple of base class names (e.g., ("ABC", "Mixin"))

get_python_class_decorators
Get class decorators with type-safe access.
1 tuple[str, ...] 
def get_python_class_decorators(element: DocElement) -> tuple[str, ...]

Get class decorators with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "class"

Returns

tuple[str, ...] —

Tuple of decorator names (e.g., ("dataclass", "frozen"))

get_python_class_is_dataclass
Check if class is a dataclass with type-safe access.
1 bool 
def get_python_class_is_dataclass(element: DocElement) -> bool

Check if class is a dataclass with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "class"

Returns

bool —

True if class has @dataclass decorator

get_python_function_decorators
Get function/method decorators with type-safe access.
1 tuple[str, ...] 
def get_python_function_decorators(element: DocElement) -> tuple[str, ...]

Get function/method decorators with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "function" or "method"

Returns

tuple[str, ...] —

Tuple of decorator names (e.g., ("classmethod", "override"))

get_python_function_is_property
Check if function is a property with type-safe access.
1 bool 
def get_python_function_is_property(element: DocElement) -> bool

Check if function is a property with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "function" or "method"

Returns

bool —

True if function has @property decorator

get_python_function_signature
Get function signature with type-safe access.
1 str 
def get_python_function_signature(element: DocElement) -> str

Get function signature with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "function" or "method"

Returns

str —

Signature string (e.g., "def build(force: bool = False) -> None")

get_python_function_return_type
Get function return type with type-safe access.
1 str | None 
def get_python_function_return_type(element: DocElement) -> str | None

Get function return type with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "function" or "method"

Returns

str | None —

Return type string or None

get_cli_command_callback
Get CLI command callback name with type-safe access.
1 str | None 
def get_cli_command_callback(element: DocElement) -> str | None

Get CLI command callback name with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "command"

Returns

str | None —

Callback function name or None

get_cli_command_option_count
Get CLI command option count with type-safe access.
1 int 
def get_cli_command_option_count(element: DocElement) -> int

Get CLI command option count with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "command"

Returns

int —

Number of options

get_cli_group_command_count
Get CLI group command count with type-safe access.
1 int 
def get_cli_group_command_count(element: DocElement) -> int

Get CLI group command count with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "command-group"

Returns

int —

Number of subcommands

get_openapi_tags
Get OpenAPI endpoint tags with type-safe access.
1 tuple[str, ...] 
def get_openapi_tags(element: DocElement) -> tuple[str, ...]

Get OpenAPI endpoint tags with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "openapi_endpoint"

Returns

tuple[str, ...] —

Tuple of tag names (e.g., ("users", "admin"))

get_openapi_method
Get OpenAPI HTTP method with type-safe access.
1 str 
def get_openapi_method(element: DocElement) -> str

Get OpenAPI HTTP method with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "openapi_endpoint"

Returns

str —

HTTP method string (e.g., "GET", "POST")

get_openapi_path
Get OpenAPI endpoint path with type-safe access.
1 str 
def get_openapi_path(element: DocElement) -> str

Get OpenAPI endpoint path with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "openapi_endpoint"

Returns

str —

Path string (e.g., "/users/{id}")

get_openapi_operation_id
Get OpenAPI operation ID with type-safe access.
1 str | None 
def get_openapi_operation_id(element: DocElement) -> str | None

Get OpenAPI operation ID with type-safe access.

Parameters 1

Name Type Default Description
element DocElement —

DocElement with element_type "openapi_endpoint"

Returns

str | None —

Operation ID string or None

get_function_parameters
Get normalized function/method parameters across all extractor types. This is the canonical way to…
2 list[dict[str, Any]] 
def get_function_parameters(element: DocElement, exclude_self: bool = True) -> list[dict[str, Any]]

Get normalized function/method parameters across all extractor types.

This is the canonical way to access parameters in templates. It handles:

  • Python functions/methods (typed_metadata.parameters or metadata.args)
  • CLI options (typed_metadata or metadata.options)
  • OpenAPI endpoints (typed_metadata.parameters or metadata.parameters)

Each parameter is normalized to a consistent dict format:

{
    "name": str,           # Parameter name
    "type": str | None,    # Type annotation/schema type
    "default": str | None, # Default value
    "required": bool,      # Whether required (derived from default)
    "description": str,    # Description from docstring
}

Parameters 2

Name Type Default Description
element DocElement —

DocElement to extract parameters from
exclude_self bool True

If True, excludes 'self' and 'cls' parameters (default True)

Returns

list[dict[str, Any]] —

List of normalized parameter dicts (empty list if element has no params)

get_function_return_info
Get normalized return type information across all extractor types. Returns a consistent dict forma…
1 dict[str, Any] 
def get_function_return_info(element: DocElement) -> dict[str, Any]

Get normalized return type information across all extractor types.

Returns a consistent dict format:

{
    "type": str | None,        # Return type annotation
    "description": str | None, # Return description from docstring
}

Parameters 1

Name Type Default Description
element DocElement —

DocElement to extract return info from

Returns

dict[str, Any] —

Dict with 'type' and 'description' keys (both None if not applicable)