Module

autodoc.extractors.python

Python API documentation extractor.

Extracts documentation from Python source files via AST parsing. No imports required - fast and reliable.

View source
1 Class

Classes

PythonExtractor
Extract Python API documentation via AST parsing. Features: - No imports (AST-only) - fast and rel…
23

Extract Python API documentation via AST parsing.

Features:

  • No imports (AST-only) - fast and reliable
  • Extracts modules, classes, functions, methods
  • Type hint support
  • Docstring extraction
  • Signature building
  • Alias detection
  • Inherited member synthesis

Performance:

  • ~0.1-0.5s per file
  • No dependencies loaded
  • No side effects
Inherits from Extractor

Methods 2

extract
Extract documentation from Python source.
1 list[DocElement] 
def extract(self, source: Path) -> list[DocElement]

Extract documentation from Python source.

Parameters 1
source Path

Directory or file path
Returns

list[DocElement] —

List of DocElement objects

get_output_path
Get output path for element. Packages (modules from __init__.py) generate _ind…
1 Path | None 
def get_output_path(self, element: DocElement) -> Path | None

Get output path for element.

Packages (modules from init.py) generate _index.md files to act as section indexes. With grouping enabled, modules are organized under group directories based on package hierarchy or explicit configuration.

Examples (without grouping): bengal (package) → bengal/_index.md bengal.core (package) → bengal/core/_index.md bengal.core.site (module) → bengal/core/site.md

Examples (with grouping, strip_prefix="bengal."): bengal.core (package) → core/_index.md bengal.cli.templates.blog (module) → templates/blog.md

Parameters 1
element DocElement
Returns

Path | None —

Path object for output location, or None if element should be skipped

Internal Methods 21
__init__
Initialize extractor.
2 None 
def __init__(self, exclude_patterns: list[str] | None = None, config: dict[str, Any] | None = None)

Initialize extractor.

Parameters 2
exclude_patterns list[str] | None

Glob patterns to exclude (e.g., "/tests/")
config dict[str, Any] | None

Configuration dict with include_inherited, exclude_patterns, etc.
_init_grouping
Initialize grouping configuration.
0 dict[str, Any] 
def _init_grouping(self) -> dict[str, Any]

Initialize grouping configuration.

Returns

dict[str, Any] —

Grouping config dict with mode and prefix_map

_extract_directory
Extract from all Python files in directory.
1 list[DocElement] 
def _extract_directory(self, directory: Path) -> list[DocElement]

Extract from all Python files in directory.

Parameters 1
directory Path
Returns

list[DocElement]

_should_skip
Check if file should be skipped. Handles common exclusion patterns: - Hidden d…
1 bool 
def _should_skip(self, path: Path) -> bool

Check if file should be skipped.

Handles common exclusion patterns:

  • Hidden directories (starting with .)
  • Virtual environments (.venv, venv, env, .env)
  • Site-packages (dependencies)
  • Build artifacts (pycache, build, dist)
  • Test files and directories
Parameters 1
path Path
Returns

bool

_extract_file
Extract documentation from a single Python file.
1 list[DocElement] 
def _extract_file(self, file_path: Path) -> list[DocElement]

Extract documentation from a single Python file.

Parameters 1
file_path Path
Returns

list[DocElement]

_extract_module
Extract module documentation.
3 DocElement | None 
def _extract_module(self, tree: ast.Module, file_path: Path, source: str) -> DocElement | None

Extract module documentation.

Parameters 3
tree ast.Module
file_path Path
source str
Returns

DocElement | None

_extract_class
Extract class documentation.
3 DocElement | None 
def _extract_class(self, node: ast.ClassDef, file_path: Path, parent_name: str = '') -> DocElement | None

Extract class documentation.

Parameters 3
node ast.ClassDef
file_path Path
parent_name str
Returns

DocElement | None

_extract_function
Extract function/method documentation.
3 DocElement | None 
def _extract_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: Path, parent_name: str = '') -> DocElement | None

Extract function/method documentation.

Parameters 3
node ast.FunctionDef | ast.AsyncFunctionDef
file_path Path
parent_name str
Returns

DocElement | None

_build_signature
Build function signature string.
1 str 
def _build_signature(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> str

Build function signature string.

Parameters 1
node ast.FunctionDef | ast.AsyncFunctionDef
Returns

str

_extract_arguments
Extract argument information.
1 list[dict[str, Any]] 
def _extract_arguments(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[dict[str, Any]]

Extract argument information.

Parameters 1
node ast.FunctionDef | ast.AsyncFunctionDef
Returns

list[dict[str, Any]]

_to_parsed_docstring
Convert ParsedDoc to frozen ParsedDocstring.
1 ParsedDocstring | None 
def _to_parsed_docstring(self, parsed: Any) -> ParsedDocstring | None

Convert ParsedDoc to frozen ParsedDocstring.

Parameters 1
parsed Any

ParsedDoc from docstring_parser
Returns

ParsedDocstring | None —

ParsedDocstring dataclass or None

_to_parameter_info
Convert arg dict to ParameterInfo.
1 ParameterInfo 
def _to_parameter_info(self, arg: dict[str, Any]) -> ParameterInfo

Convert arg dict to ParameterInfo.

Parameters 1
arg dict[str, Any]

Dict with name, annotation, default, docstring
Returns

ParameterInfo —

ParameterInfo dataclass

_has_yield
Check if function contains yield statement.
1 bool 
def _has_yield(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool

Check if function contains yield statement.

Parameters 1
node ast.FunctionDef | ast.AsyncFunctionDef

Function AST node
Returns

bool —

True if function is a generator

_annotation_to_string
Convert AST annotation to string.
1 str | None 
def _annotation_to_string(self, annotation: ast.expr | None) -> str | None

Convert AST annotation to string.

Parameters 1
annotation ast.expr | None
Returns

str | None

_expr_to_string
Convert AST expression to string.
1 str 
def _expr_to_string(self, expr: ast.expr) -> str

Convert AST expression to string.

Parameters 1
expr ast.expr
Returns

str

_infer_module_name
Infer module name from file path relative to source root.
1 str 
def _infer_module_name(self, file_path: Path) -> str

Infer module name from file path relative to source root.

Parameters 1
file_path Path
Returns

str

_get_relative_source_path
Get source path relative to source root for GitHub links.
1 Path 
def _get_relative_source_path(self, file_path: Path) -> Path

Get source path relative to source root for GitHub links.

Parameters 1
file_path Path

Absolute file path
Returns

Path —

Path relative to source root (e.g., "bengal/core/page.py")

_should_include_inherited
Check if inherited members should be included for element type.
1 bool 
def _should_include_inherited(self, element_type: str = 'class') -> bool

Check if inherited members should be included for element type.

Parameters 1
element_type str

Type of element ("class" or "exception")
Returns

bool —

True if inherited members should be included

_synthesize_inherited_members
Add inherited members to a class element.
1 None 
def _synthesize_inherited_members(self, class_elem: DocElement) -> None

Add inherited members to a class element.

Parameters 1
class_elem DocElement

Class DocElement to augment with inherited members
_detect_aliases
Detect simple assignment aliases at module level. Patterns detected: - alias =…
3 dict[str, str] 
def _detect_aliases(self, tree: ast.Module, module_name: str, defined_names: set[str]) -> dict[str, str]

Detect simple assignment aliases at module level.

Patterns detected:

  • alias = original (ast.Name)
  • alias = module.original (ast.Attribute)
Parameters 3
tree ast.Module

Module AST
module_name str

Current module qualified name
defined_names set[str]

Set of names defined in this module
Returns

dict[str, str] —

Dict mapping alias_name -> qualified_original

_extract_all_exports
Extract __all__ exports if present.
1 list[str] | None 
def _extract_all_exports(self, tree: ast.Module) -> list[str] | None

Extract all exports if present.

Parameters 1
tree ast.Module
Returns

list[str] | None