python ¤

Python handler for mkdocstrings.

Modules:

config –

Deprecated. Import from mkdocstrings_handlers.python directly.
handler –

Deprecated. Import from mkdocstrings_handlers.python directly.
rendering –

Deprecated. Import from mkdocstrings_handlers.python directly.

Classes:

AutoStyleOptions –

Auto style docstring options.
AutorefsHook –

Autorefs hook.
GoogleStyleOptions –

Google style docstring options.
Inventory –

An inventory.
NumpyStyleOptions –

Numpy style docstring options.
PerStyleOptions –

Per style options.
PythonConfig –

Python handler configuration.
PythonHandler –

The Python handler class.
PythonInputConfig –

Python handler configuration.
PythonInputOptions –

Accepted input options.
PythonOptions –

Final options passed as template context.
SphinxStyleOptions –

Sphinx style docstring options.
SummaryOption –

Summary option.

Functions:

do_as_attributes_section –

Build an attributes section from a list of attributes.
do_as_classes_section –

Build a classes section from a list of classes.
do_as_functions_section –

Build a functions section from a list of functions.
do_as_modules_section –

Build a modules section from a list of modules.
do_backlink_tree –

Build a tree of backlinks.
do_crossref –

Deprecated. Filter to create cross-references.
do_filter_objects –

Filter a dictionary of objects based on their docstrings.
do_format_attribute –

Format an attribute.
do_format_code –

Format code.
do_format_signature –

Format a signature.
do_get_template –

Get the template name used to render an object.
do_multi_crossref –

Deprecated. Filter to create cross-references.
do_order_members –

Order members given an ordering method.
do_split_path –

Split object paths for building cross-references.
get_handler –

Return an instance of PythonHandler.

Attributes:

Order –

Ordering methods.
Tree –

A tree type. Each node holds a tuple of items.
do_stash_crossref –

Filter to stash cross-references (and restore them after formatting and highlighting).

Order `module-attribute` ¤


Order = Literal['alphabetical', 'source']

Ordering methods.

Used by:

python do_order_members

Tree `module-attribute` ¤


Tree = dict[tuple[_T, ...], 'Tree']

A tree type. Each node holds a tuple of items.

do_stash_crossref `module-attribute` ¤


do_stash_crossref = _StashCrossRefFilter()

Filter to stash cross-references (and restore them after formatting and highlighting).

AutoStyleOptions `dataclass` ¤


AutoStyleOptions(
    method: Literal["heuristics", "max_sections"] = "heuristics",
    style_order: list[str] = lambda: ["sphinx", "google", "numpy"](),
    default: str | None = None,
    per_style_options: PerStyleOptions = PerStyleOptions(),
)

Auto style docstring options.

Methods:

from_data –

Create an instance from a dictionary.

Attributes:

default (str | None) –

The default docstring style to use if no other style is detected.
method (Literal['heuristics', 'max_sections']) –

The method to use to determine the docstring style.
per_style_options (PerStyleOptions) –

Per-style options.
style_order (list[str]) –

The order of the docstring styles to try.

default `class-attribute` `instance-attribute` ¤


default: str | None = None

The default docstring style to use if no other style is detected.

method `class-attribute` `instance-attribute` ¤


method: Literal['heuristics', 'max_sections'] = 'heuristics'

The method to use to determine the docstring style.

per_style_options `class-attribute` `instance-attribute` ¤


per_style_options: PerStyleOptions = field(default_factory=PerStyleOptions)

Per-style options.

style_order `class-attribute` `instance-attribute` ¤


style_order: list[str] = field(default_factory=lambda: ['sphinx', 'google', 'numpy'])

The order of the docstring styles to try.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

AutorefsHook ¤


AutorefsHook(current_object: Object | Alias, config: dict[str, Any])

Autorefs hook.

With this hook, we're able to add context to autorefs (cross-references), such as originating file path and line number, to improve error reporting.

Parameters:

current_object ¤
(Object | Alias) –

The object being rendered.
config ¤
(dict[str, Any]) –

The configuration dictionary.

Methods:

expand_identifier –

Expand an identifier.
get_context –

Get the context for the current object.

Attributes:

config –

The configuration options.
current_object –

The current object being rendered.

config `instance-attribute` ¤


config = config

The configuration options.

current_object `instance-attribute` ¤


current_object = current_object

The current object being rendered.

expand_identifier ¤


expand_identifier(identifier: str) -> str

Expand an identifier.

Parameters:

identifier ¤
(str) –

The identifier to expand.

Returns:

str –

The expanded identifier.

get_context ¤


get_context() -> Context

Get the context for the current object.

Returns:

Context –

The context.

GoogleStyleOptions `dataclass` ¤


GoogleStyleOptions(
    ignore_init_summary: bool = False,
    returns_multiple_items: bool = True,
    returns_named_value: bool = True,
    returns_type_in_property_summary: bool = False,
    receives_multiple_items: bool = True,
    receives_named_value: bool = True,
    trim_doctest_flags: bool = True,
    warn_unknown_params: bool = True,
)

Google style docstring options.

Attributes:

ignore_init_summary (bool) –

Whether to ignore the summary in __init__ methods' docstrings.
receives_multiple_items (bool) –

Whether to parse multiple items in Receives sections.
receives_named_value (bool) –

Whether to parse Receives section items as name and description, rather than type and description.
returns_multiple_items (bool) –

Whether to parse multiple items in Yields and Returns sections.
returns_named_value (bool) –

Whether to parse Yields and Returns section items as name and description, rather than type and description.
returns_type_in_property_summary (bool) –

Whether to parse the return type of properties at the beginning of their summary: str: Summary of the property.
trim_doctest_flags (bool) –

Whether to remove doctest flags from Python example blocks.
warn_unknown_params (bool) –

Warn about documented parameters not appearing in the signature.

ignore_init_summary `class-attribute` `instance-attribute` ¤


ignore_init_summary: bool = False

Whether to ignore the summary in __init__ methods' docstrings.

receives_multiple_items `class-attribute` `instance-attribute` ¤


receives_multiple_items: bool = True

Whether to parse multiple items in Receives sections.

When true, each item's continuation lines must be indented. When false (single item), no further indentation is required.

receives_named_value `class-attribute` `instance-attribute` ¤


receives_named_value: bool = True

Whether to parse Receives section items as name and description, rather than type and description.

When true, type must be wrapped in parentheses: (int): Description.. Names are optional: name (int): Description.. When false, parentheses are optional but the items cannot be named: int: Description.

returns_multiple_items `class-attribute` `instance-attribute` ¤


returns_multiple_items: bool = True

Whether to parse multiple items in Yields and Returns sections.

When true, each item's continuation lines must be indented. When false (single item), no further indentation is required.

returns_named_value `class-attribute` `instance-attribute` ¤


returns_named_value: bool = True

Whether to parse Yields and Returns section items as name and description, rather than type and description.

When true, type must be wrapped in parentheses: (int): Description.. Names are optional: name (int): Description.. When false, parentheses are optional but the items cannot be named: int: Description.

returns_type_in_property_summary `class-attribute` `instance-attribute` ¤


returns_type_in_property_summary: bool = False

Whether to parse the return type of properties at the beginning of their summary: str: Summary of the property.

trim_doctest_flags `class-attribute` `instance-attribute` ¤


trim_doctest_flags: bool = True

Whether to remove doctest flags from Python example blocks.

warn_unknown_params `class-attribute` `instance-attribute` ¤


warn_unknown_params: bool = True

Warn about documented parameters not appearing in the signature.

Inventory `dataclass` ¤


Inventory(url: str, base: str | None = None, domains: list[str] = lambda: ['py']())

An inventory.

Attributes:

base (str | None) –

The base URL of the inventory.
domains (list[str]) –

The domains to load from the inventory.
url (str) –

The URL of the inventory.

base `class-attribute` `instance-attribute` ¤


base: str | None = None

The base URL of the inventory.

domains `class-attribute` `instance-attribute` ¤


domains: list[str] = field(default_factory=lambda: ['py'])

The domains to load from the inventory.

url `instance-attribute` ¤


url: str

The URL of the inventory.

NumpyStyleOptions `dataclass` ¤


NumpyStyleOptions(
    ignore_init_summary: bool = False,
    trim_doctest_flags: bool = True,
    warn_unknown_params: bool = True,
)

Numpy style docstring options.

Attributes:

ignore_init_summary (bool) –

Whether to ignore the summary in __init__ methods' docstrings.
trim_doctest_flags (bool) –

Whether to remove doctest flags from Python example blocks.
warn_unknown_params (bool) –

Warn about documented parameters not appearing in the signature.

ignore_init_summary `class-attribute` `instance-attribute` ¤


ignore_init_summary: bool = False

Whether to ignore the summary in __init__ methods' docstrings.

trim_doctest_flags `class-attribute` `instance-attribute` ¤


trim_doctest_flags: bool = True

Whether to remove doctest flags from Python example blocks.

warn_unknown_params `class-attribute` `instance-attribute` ¤


warn_unknown_params: bool = True

Warn about documented parameters not appearing in the signature.

PerStyleOptions `dataclass` ¤


PerStyleOptions(
    google: GoogleStyleOptions = GoogleStyleOptions(),
    numpy: NumpyStyleOptions = NumpyStyleOptions(),
    sphinx: SphinxStyleOptions = SphinxStyleOptions(),
)

Per style options.

Methods:

from_data –

Create an instance from a dictionary.

Attributes:

google (GoogleStyleOptions) –

Google-style options.
numpy (NumpyStyleOptions) –

Numpydoc-style options.
sphinx (SphinxStyleOptions) –

Sphinx-style options.

google `class-attribute` `instance-attribute` ¤


google: GoogleStyleOptions = field(default_factory=GoogleStyleOptions)

Google-style options.

numpy `class-attribute` `instance-attribute` ¤


numpy: NumpyStyleOptions = field(default_factory=NumpyStyleOptions)

Numpydoc-style options.

sphinx `class-attribute` `instance-attribute` ¤


sphinx: SphinxStyleOptions = field(default_factory=SphinxStyleOptions)

Sphinx-style options.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

PythonConfig `dataclass` ¤


PythonConfig(
    inventories: list[Inventory] = list(),
    paths: list[str] = lambda: ["."](),
    load_external_modules: bool | None = None,
    options: dict[str, Any] = dict(),
    locale: str | None = None,
)

Python handler configuration.

Used by:

python PythonHandler

Methods:

coerce –

Coerce data.
from_data –

Create an instance from a dictionary.

Attributes:

inventories (list[Inventory]) –

The object inventories to load.
load_external_modules (bool | None) –

Whether to always load external modules/packages.
locale (str | None) –

The locale to use when translating template strings.
options (dict[str, Any]) –

Configuration options for collecting and rendering objects.
paths (list[str]) –

The paths in which to search for Python packages.

inventories `class-attribute` `instance-attribute` ¤


inventories: list[Inventory] = field(default_factory=list)

The object inventories to load.

load_external_modules `class-attribute` `instance-attribute` ¤


load_external_modules: bool | None = None

Whether to always load external modules/packages.

locale `class-attribute` `instance-attribute` ¤


locale: str | None = None

The locale to use when translating template strings.

options `class-attribute` `instance-attribute` ¤


options: dict[str, Any] = field(default_factory=dict)

Configuration options for collecting and rendering objects.

paths `class-attribute` `instance-attribute` ¤


paths: list[str] = field(default_factory=lambda: ['.'])

The paths in which to search for Python packages.

coerce `classmethod` ¤


coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

PythonHandler ¤


PythonHandler(config: PythonConfig, base_dir: Path, **kwargs: Any)

The Python handler class.

Parameters:

config ¤
(PythonConfig) –

The handler configuration.
base_dir ¤
(Path) –

The base directory of the project.
**kwargs ¤
(Any, default: {} ) –

Arguments passed to the parent constructor.

Returned by:

python get_handler

Methods:

collect –

Collect the documentation for the given identifier.
do_convert_markdown –

Render Markdown text; for use inside templates.
do_heading –

Render an HTML heading and register it for the table of contents. For use inside templates.
get_aliases –

Get the aliases for the given identifier.
get_extended_templates_dirs –

Load template extensions for the given handler, return their templates directories.
get_headings –

Return and clear the headings gathered so far.
get_inventory_urls –

Return the URLs of the inventory files to download.
get_options –

Get combined default, global and local options.
get_templates_dir –

Return the path to the handler's templates directory.
load_inventory –

Yield items and their URLs from an inventory file streamed from in_file.
normalize_extension_paths –

Resolve extension paths relative to config file.
render –

Render the collected data.
render_backlinks –

Render the backlinks.
teardown –

Teardown the handler.
update_env –

Update the Jinja environment with custom filters and tests.

Attributes:

base_dir –

The base directory of the project.
config –

The handler configuration.
custom_templates –

The path to custom templates.
domain (str) –

The cross-documentation domain/language for this handler.
enable_inventory (bool) –

Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.
env –

The Jinja environment.
extra_css (str) –

Extra CSS.
fallback_config (dict) –

Fallback configuration when searching anchors for identifiers.
fallback_theme (str) –

The fallback theme.
global_options –

The global configuration options (in mkdocs.yml).
md (Markdown) –

The Markdown instance.
mdx –

The Markdown extensions to use.
mdx_config –

The configuration for the Markdown extensions.
name (str) –

The handler's name.
outer_layer (bool) –

Whether we're in the outer Markdown conversion layer.
theme –

The selected theme.

base_dir `instance-attribute` ¤


base_dir = base_dir

The base directory of the project.

config `instance-attribute` ¤


config = config

The handler configuration.

custom_templates `instance-attribute` ¤


custom_templates = custom_templates

The path to custom templates.

Used by:

python PythonHandler custom_templates

domain `class-attribute` ¤


domain: str = 'py'

The cross-documentation domain/language for this handler.

enable_inventory `class-attribute` ¤


enable_inventory: bool = True

Whether this handler is interested in enabling the creation of the objects.inv Sphinx inventory file.

env `instance-attribute` ¤


env = Environment(autoescape=True, loader=FileSystemLoader(paths), auto_reload=False)

The Jinja environment.

extra_css `class-attribute` `instance-attribute` ¤


extra_css: str = ''

Extra CSS.

fallback_config `class-attribute` ¤


fallback_config: dict = {}

Fallback configuration when searching anchors for identifiers.

fallback_theme `class-attribute` ¤


fallback_theme: str = 'material'

The fallback theme.

global_options `instance-attribute` ¤


global_options = global_options

The global configuration options (in mkdocs.yml).

Used by:

python PythonHandler global_options

md `property` ¤


md: Markdown

The Markdown instance.

Raises:

RuntimeError –

When the Markdown instance is not set yet.

mdx `instance-attribute` ¤


mdx = mdx

The Markdown extensions to use.

Used by:

python PythonHandler mdx

mdx_config `instance-attribute` ¤


mdx_config = mdx_config

The configuration for the Markdown extensions.

Used by:

python PythonHandler mdx_config

name `class-attribute` ¤


name: str = 'python'

The handler's name.

outer_layer `property` ¤


outer_layer: bool

Whether we're in the outer Markdown conversion layer.

theme `instance-attribute` ¤


theme = theme

The selected theme.

Used by:

python PythonHandler theme

collect ¤


collect(identifier: str, options: PythonOptions) -> CollectorItem

Collect the documentation for the given identifier.

Parameters:

identifier ¤
(str) –

The identifier of the object to collect.
options ¤
(PythonOptions) –

The options to use for the collection.

Returns:

CollectorItem –

The collected item.

do_convert_markdown ¤


do_convert_markdown(
    text: str,
    heading_level: int,
    html_id: str = "",
    *,
    strip_paragraph: bool = False,
    autoref_hook: AutorefsHookInterface | None = None
) -> Markup

Render Markdown text; for use inside templates.

Parameters:

text ¤
(str) –

The text to convert.
heading_level ¤
(int) –

The base heading level to start all Markdown headings from.
html_id ¤
(str, default: '' ) –

The HTML id of the element that's considered the parent of this element.
strip_paragraph ¤
(bool, default: False ) –

Whether to exclude the <p> tag from around the whole output.

Returns:

Markup –

An HTML string.

do_heading ¤


do_heading(
    content: Markup,
    heading_level: int,
    *,
    role: str | None = None,
    hidden: bool = False,
    toc_label: str | None = None,
    **attributes: str
) -> Markup

Render an HTML heading and register it for the table of contents. For use inside templates.

Parameters:

content ¤
(Markup) –

The HTML within the heading.
heading_level ¤
(int) –

The level of heading (e.g. 3 -> h3).
role ¤
(str | None, default: None ) –

An optional role for the object bound to this heading.
hidden ¤
(bool, default: False ) –

If True, only register it for the table of contents, don't render anything.
toc_label ¤
(str | None, default: None ) –

The title to use in the table of contents ('data-toc-label' attribute).
**attributes ¤
(str, default: {} ) –

Any extra HTML attributes of the heading.

Returns:

Markup –

An HTML string.

get_aliases ¤


get_aliases(identifier: str) -> tuple[str, ...]

Get the aliases for the given identifier.

Parameters:

identifier ¤
(str) –

The identifier to get the aliases for.

Returns:

tuple[str, ...] –

The aliases.

get_extended_templates_dirs ¤


get_extended_templates_dirs(handler: str) -> list[Path]

Load template extensions for the given handler, return their templates directories.

Parameters:

handler ¤
(str) –

The name of the handler to get the extended templates directory of.

Returns:

list[Path] –

The extensions templates directories.

get_headings ¤


get_headings() -> Sequence[Element]

Return and clear the headings gathered so far.

Returns:

Sequence[Element] –

A list of HTML elements.

get_inventory_urls ¤


get_inventory_urls() -> list[tuple[str, dict[str, Any]]]

Return the URLs of the inventory files to download.

get_options ¤


get_options(local_options: Mapping[str, Any]) -> HandlerOptions

Get combined default, global and local options.

Parameters:

local_options ¤
(Mapping[str, Any]) –

The local options.

Returns:

HandlerOptions –

The combined options.

get_templates_dir ¤


get_templates_dir(handler: str | None = None) -> Path

Return the path to the handler's templates directory.

Override to customize how the templates directory is found.

Parameters:

handler ¤
(str | None, default: None ) –

The name of the handler to get the templates directory of.

Raises:

ModuleNotFoundError –

When no such handler is installed.
FileNotFoundError –

When the templates directory cannot be found.

Returns:

Path –

The templates directory path.

load_inventory `staticmethod` ¤


load_inventory(
    in_file: BinaryIO,
    url: str,
    base_url: str | None = None,
    domains: list[str] | None = None,
    **kwargs: Any
) -> Iterator[tuple[str, str]]

Yield items and their URLs from an inventory file streamed from in_file.

This implements mkdocstrings' load_inventory "protocol" (see mkdocstrings.plugin).

Parameters:

in_file ¤
(BinaryIO) –

The binary file-like object to read the inventory from.
url ¤
(str) –

The URL that this file is being streamed from (used to guess base_url).
base_url ¤
(str | None, default: None ) –

The URL that this inventory's sub-paths are relative to.
domains ¤
(list[str] | None, default: None ) –

A list of domain strings to filter the inventory by, when not passed, "py" will be used.
**kwargs ¤
(Any, default: {} ) –

Ignore additional arguments passed from the config.

Yields:

tuple[str, str] –

Tuples of (item identifier, item URL).

normalize_extension_paths ¤


normalize_extension_paths(extensions: Sequence) -> Sequence

Resolve extension paths relative to config file.

Parameters:

extensions ¤
(Sequence) –

The extensions (configuration) to normalize.

Returns:

Sequence –

The normalized extensions.

render ¤


render(data: CollectorItem, options: PythonOptions) -> str

Render the collected data.

Parameters:

data ¤
(CollectorItem) –

The collected data.
options ¤
(PythonOptions) –

The options to use for rendering.

Returns:

str –

The rendered data (HTML).

render_backlinks ¤


render_backlinks(backlinks: Mapping[str, Iterable[Backlink]]) -> str

Render the backlinks.

Parameters:

backlinks ¤
(Mapping[str, Iterable[Backlink]]) –

The backlinks to render.

Returns:

str –

The rendered backlinks (HTML).

teardown ¤


teardown() -> None

Teardown the handler.

This method should be implemented to, for example, terminate a subprocess that was started when creating the handler instance.

update_env ¤


update_env(config: Any) -> None

Update the Jinja environment with custom filters and tests.

Parameters:

config ¤
(Any) –

The SSG configuration.

PythonInputConfig `dataclass` ¤


PythonInputConfig(
    inventories: list[str | Inventory] = list(),
    paths: list[str] = lambda: ["."](),
    load_external_modules: bool | None = None,
    options: PythonInputOptions = PythonInputOptions(),
    locale: str | None = None,
)

Python handler configuration.

Methods:

coerce –

Coerce data.
from_data –

Create an instance from a dictionary.

Attributes:

inventories (list[str | Inventory]) –

The inventories to load.
load_external_modules (bool | None) –

Whether to always load external modules/packages.
locale (str | None) –

The locale to use when translating template strings.
options (PythonInputOptions) –

Configuration options for collecting and rendering objects.
paths (list[str]) –

The paths in which to search for Python packages.

inventories `class-attribute` `instance-attribute` ¤


inventories: list[str | Inventory] = field(default_factory=list)

The inventories to load.

load_external_modules `class-attribute` `instance-attribute` ¤


load_external_modules: bool | None = None

Whether to always load external modules/packages.

locale `class-attribute` `instance-attribute` ¤


locale: str | None = None

The locale to use when translating template strings.

options `class-attribute` `instance-attribute` ¤


options: PythonInputOptions = field(default_factory=PythonInputOptions)

Configuration options for collecting and rendering objects.

paths `class-attribute` `instance-attribute` ¤


paths: list[str] = field(default_factory=lambda: ['.'])

The paths in which to search for Python packages.

coerce `classmethod` ¤


coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

PythonInputOptions `dataclass` ¤


PythonInputOptions(
    allow_inspection: bool = True,
    force_inspection: bool = False,
    annotations_path: Literal["brief", "source", "full"] = "brief",
    backlinks: Literal["flat", "tree", False] = False,
    docstring_options: (
        GoogleStyleOptions
        | NumpyStyleOptions
        | SphinxStyleOptions
        | AutoStyleOptions
        | None
    ) = None,
    docstring_section_style: Literal["table", "list", "spacy"] = "table",
    docstring_style: Literal["auto", "google", "numpy", "sphinx"] | None = "google",
    extensions: list[str | dict[str, Any]] = list(),
    filters: list[str] | Literal["public"] = lambda: copy()(),
    find_stubs_package: bool = False,
    group_by_category: bool = True,
    heading: str = "",
    heading_level: int = 2,
    inherited_members: bool | list[str] = False,
    line_length: int = 60,
    members: list[str] | bool | None = None,
    members_order: Literal["alphabetical", "source"] = "alphabetical",
    merge_init_into_class: bool = False,
    modernize_annotations: bool = False,
    parameter_headings: bool = False,
    preload_modules: list[str] = list(),
    relative_crossrefs: bool = False,
    scoped_crossrefs: bool = False,
    show_overloads: bool = True,
    separate_signature: bool = False,
    show_bases: bool = True,
    show_category_heading: bool = False,
    show_docstring_attributes: bool = True,
    show_docstring_classes: bool = True,
    show_docstring_description: bool = True,
    show_docstring_examples: bool = True,
    show_docstring_functions: bool = True,
    show_docstring_modules: bool = True,
    show_docstring_other_parameters: bool = True,
    show_docstring_parameters: bool = True,
    show_docstring_raises: bool = True,
    show_docstring_receives: bool = True,
    show_docstring_returns: bool = True,
    show_docstring_warns: bool = True,
    show_docstring_yields: bool = True,
    show_if_no_docstring: bool = False,
    show_inheritance_diagram: bool = False,
    show_labels: bool = True,
    show_object_full_path: bool = False,
    show_root_full_path: bool = True,
    show_root_heading: bool = False,
    show_root_members_full_path: bool = False,
    show_root_toc_entry: bool = True,
    show_signature_annotations: bool = False,
    show_signature: bool = True,
    show_source: bool = True,
    show_submodules: bool = False,
    show_symbol_type_heading: bool = False,
    show_symbol_type_toc: bool = False,
    signature_crossrefs: bool = False,
    summary: bool | SummaryOption = SummaryOption(),
    toc_label: str = "",
    unwrap_annotated: bool = False,
    extra: dict[str, Any] = dict(),
)

Accepted input options.

Methods:

coerce –

Coerce data.
from_data –

Create an instance from a dictionary.

Attributes:

allow_inspection (bool) –

Whether to allow inspecting modules when visiting them is not possible.
annotations_path (Literal['brief', 'source', 'full']) –

The verbosity for annotations path: brief (recommended), source (as written in the source), or full.
backlinks (Literal['flat', 'tree', False]) –

Whether to render backlinks, and how.
docstring_options (GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None) –

The options for the docstring parser.
docstring_section_style (Literal['table', 'list', 'spacy']) –

The style used to render docstring sections.
docstring_style (Literal['auto', 'google', 'numpy', 'sphinx'] | None) –

The docstring style to use: auto, google, numpy, sphinx, or None.
extensions (list[str | dict[str, Any]]) –

A list of Griffe extensions to load.
extra (dict[str, Any]) –

Extra options.
filters (list[str] | Literal['public']) –

A list of filters, or "public".
find_stubs_package (bool) –

Whether to load stubs package (package-stubs) when extracting docstrings.
force_inspection (bool) –

Whether to force using dynamic analysis when loading data.
group_by_category (bool) –

Group the object's children by categories: attributes, classes, functions, and modules.
heading (str) –

A custom string to override the autogenerated heading of the root object.
heading_level (int) –

The initial heading level to use.
inherited_members (bool | list[str]) –

A boolean, or an explicit list of inherited members to render.
line_length (int) –

Maximum line length when formatting code/signatures.
members (list[str] | bool | None) –

A boolean, or an explicit list of members to render.
members_order (Literal['alphabetical', 'source']) –

The members ordering to use.
merge_init_into_class (bool) –

Whether to merge the __init__ method into the class' signature and docstring.
modernize_annotations (bool) –

Whether to modernize annotations, for example Optional[str] into str | None.
parameter_headings (bool) –

Whether to render headings for parameters (therefore showing parameters in the ToC).
preload_modules (list[str]) –

Pre-load modules that are not specified directly in autodoc instructions (::: identifier).
relative_crossrefs (bool) –

Whether to enable the relative crossref syntax.
scoped_crossrefs (bool) –

Whether to enable the scoped crossref ability.
separate_signature (bool) –

Whether to put the whole signature in a code block below the heading.
show_bases (bool) –

Show the base classes of a class.
show_category_heading (bool) –

When grouped by categories, show a heading for each category.
show_docstring_attributes (bool) –

Whether to display the 'Attributes' section in the object's docstring.
show_docstring_classes (bool) –

Whether to display the 'Classes' section in the object's docstring.
show_docstring_description (bool) –

Whether to display the textual block (including admonitions) in the object's docstring.
show_docstring_examples (bool) –

Whether to display the 'Examples' section in the object's docstring.
show_docstring_functions (bool) –

Whether to display the 'Functions' or 'Methods' sections in the object's docstring.
show_docstring_modules (bool) –

Whether to display the 'Modules' section in the object's docstring.
show_docstring_other_parameters (bool) –

Whether to display the 'Other Parameters' section in the object's docstring.
show_docstring_parameters (bool) –

Whether to display the 'Parameters' section in the object's docstring.
show_docstring_raises (bool) –

Whether to display the 'Raises' section in the object's docstring.
show_docstring_receives (bool) –

Whether to display the 'Receives' section in the object's docstring.
show_docstring_returns (bool) –

Whether to display the 'Returns' section in the object's docstring.
show_docstring_warns (bool) –

Whether to display the 'Warns' section in the object's docstring.
show_docstring_yields (bool) –

Whether to display the 'Yields' section in the object's docstring.
show_if_no_docstring (bool) –

Show the object heading even if it has no docstring or children with docstrings.
show_inheritance_diagram (bool) –

Show the inheritance diagram of a class using Mermaid.
show_labels (bool) –

Whether to show labels of the members.
show_object_full_path (bool) –

Show the full Python path of every object.
show_overloads (bool) –

Show the overloads of a function or method.
show_root_full_path (bool) –

Show the full Python path for the root object heading.
show_root_heading (bool) –

Show the heading of the object at the root of the documentation tree.
show_root_members_full_path (bool) –

Show the full Python path of the root members.
show_root_toc_entry (bool) –

If the root heading is not shown, at least add a ToC entry for it.
show_signature (bool) –

Show methods and functions signatures.
show_signature_annotations (bool) –

Show the type annotations in methods and functions signatures.
show_source (bool) –

Show the source code of this object.
show_submodules (bool) –

When rendering a module, show its submodules recursively.
show_symbol_type_heading (bool) –

Show the symbol type in headings (e.g. mod, class, meth, func and attr).
show_symbol_type_toc (bool) –

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).
signature_crossrefs (bool) –

Whether to render cross-references for type annotations in signatures.
summary (bool | SummaryOption) –

Whether to render summaries of modules, classes, functions (methods) and attributes.
toc_label (str) –

A custom string to override the autogenerated toc label of the root object.
unwrap_annotated (bool) –

Whether to unwrap Annotated types to show only the type without the annotations.

allow_inspection `class-attribute` `instance-attribute` ¤


allow_inspection: bool = True

Whether to allow inspecting modules when visiting them is not possible.

annotations_path `class-attribute` `instance-attribute` ¤


annotations_path: Literal['brief', 'source', 'full'] = 'brief'

The verbosity for annotations path: brief (recommended), source (as written in the source), or full.

backlinks `class-attribute` `instance-attribute` ¤


backlinks: Literal['flat', 'tree', False] = False

Whether to render backlinks, and how.

docstring_options `class-attribute` `instance-attribute` ¤


docstring_options: (
    GoogleStyleOptions
    | NumpyStyleOptions
    | SphinxStyleOptions
    | AutoStyleOptions
    | None
) = None

The options for the docstring parser.

See docstring parsers and their options in Griffe docs.

docstring_section_style `class-attribute` `instance-attribute` ¤


docstring_section_style: Literal['table', 'list', 'spacy'] = 'table'

The style used to render docstring sections.

docstring_style `class-attribute` `instance-attribute` ¤


docstring_style: Literal['auto', 'google', 'numpy', 'sphinx'] | None = 'google'

The docstring style to use: auto, google, numpy, sphinx, or None.

extensions `class-attribute` `instance-attribute` ¤


extensions: list[str | dict[str, Any]] = field(default_factory=list)

A list of Griffe extensions to load.

extra `class-attribute` `instance-attribute` ¤


extra: dict[str, Any] = field(default_factory=dict)

Extra options.

filters `class-attribute` `instance-attribute` ¤


filters: list[str] | Literal['public'] = field(default_factory=lambda: copy())

A list of filters, or "public".

List of filters

A filter starting with ! will exclude matching objects instead of including them. The members option takes precedence over filters (filters will still be applied recursively to lower members in the hierarchy).

Filtering methods

Sponsors only — Insiders 1.11.0

The public method will include only public objects: those added to __all__ or not starting with an underscore (except for special methods/attributes).

find_stubs_package `class-attribute` `instance-attribute` ¤


find_stubs_package: bool = False

Whether to load stubs package (package-stubs) when extracting docstrings.

force_inspection `class-attribute` `instance-attribute` ¤


force_inspection: bool = False

Whether to force using dynamic analysis when loading data.

group_by_category `class-attribute` `instance-attribute` ¤


group_by_category: bool = True

Group the object's children by categories: attributes, classes, functions, and modules.

heading `class-attribute` `instance-attribute` ¤


heading: str = ''

A custom string to override the autogenerated heading of the root object.

heading_level `class-attribute` `instance-attribute` ¤


heading_level: int = 2

The initial heading level to use.

inherited_members `class-attribute` `instance-attribute` ¤


inherited_members: bool | list[str] = False

A boolean, or an explicit list of inherited members to render.

If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any inherited member.

line_length `class-attribute` `instance-attribute` ¤


line_length: int = 60

Maximum line length when formatting code/signatures.

members `class-attribute` `instance-attribute` ¤


members: list[str] | bool | None = None

A boolean, or an explicit list of members to render.

If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings.

members_order `class-attribute` `instance-attribute` ¤


members_order: Literal['alphabetical', 'source'] = 'alphabetical'

The members ordering to use.

alphabetical: order by the members names,
source: order members as they appear in the source file.

merge_init_into_class `class-attribute` `instance-attribute` ¤


merge_init_into_class: bool = False

Whether to merge the __init__ method into the class' signature and docstring.

modernize_annotations `class-attribute` `instance-attribute` ¤


modernize_annotations: bool = False

Whether to modernize annotations, for example Optional[str] into str | None.

parameter_headings `class-attribute` `instance-attribute` ¤


parameter_headings: bool = False

Whether to render headings for parameters (therefore showing parameters in the ToC).

preload_modules `class-attribute` `instance-attribute` ¤


preload_modules: list[str] = field(default_factory=list)

Pre-load modules that are not specified directly in autodoc instructions (::: identifier).

It is useful when you want to render documentation for a particular member of an object, and this member is imported from another package than its parent.

For an imported member to be rendered, you need to add it to the __all__ attribute of the importing module.

The modules must be listed as an array of strings.

relative_crossrefs `class-attribute` `instance-attribute` ¤


relative_crossrefs: bool = False

Whether to enable the relative crossref syntax.

scoped_crossrefs `class-attribute` `instance-attribute` ¤


scoped_crossrefs: bool = False

Whether to enable the scoped crossref ability.

separate_signature `class-attribute` `instance-attribute` ¤


separate_signature: bool = False

Whether to put the whole signature in a code block below the heading.

If Black or Ruff are installed, the signature is also formatted using them.

show_bases `class-attribute` `instance-attribute` ¤


show_bases: bool = True

Show the base classes of a class.

show_category_heading `class-attribute` `instance-attribute` ¤


show_category_heading: bool = False

When grouped by categories, show a heading for each category.

show_docstring_attributes `class-attribute` `instance-attribute` ¤


show_docstring_attributes: bool = True

Whether to display the 'Attributes' section in the object's docstring.

show_docstring_classes `class-attribute` `instance-attribute` ¤


show_docstring_classes: bool = True

Whether to display the 'Classes' section in the object's docstring.

show_docstring_description `class-attribute` `instance-attribute` ¤


show_docstring_description: bool = True

Whether to display the textual block (including admonitions) in the object's docstring.

show_docstring_examples `class-attribute` `instance-attribute` ¤


show_docstring_examples: bool = True

Whether to display the 'Examples' section in the object's docstring.

show_docstring_functions `class-attribute` `instance-attribute` ¤


show_docstring_functions: bool = True

Whether to display the 'Functions' or 'Methods' sections in the object's docstring.

show_docstring_modules `class-attribute` `instance-attribute` ¤


show_docstring_modules: bool = True

Whether to display the 'Modules' section in the object's docstring.

show_docstring_other_parameters `class-attribute` `instance-attribute` ¤


show_docstring_other_parameters: bool = True

Whether to display the 'Other Parameters' section in the object's docstring.

show_docstring_parameters `class-attribute` `instance-attribute` ¤


show_docstring_parameters: bool = True

Whether to display the 'Parameters' section in the object's docstring.

show_docstring_raises `class-attribute` `instance-attribute` ¤


show_docstring_raises: bool = True

Whether to display the 'Raises' section in the object's docstring.

show_docstring_receives `class-attribute` `instance-attribute` ¤


show_docstring_receives: bool = True

Whether to display the 'Receives' section in the object's docstring.

show_docstring_returns `class-attribute` `instance-attribute` ¤


show_docstring_returns: bool = True

Whether to display the 'Returns' section in the object's docstring.

show_docstring_warns `class-attribute` `instance-attribute` ¤


show_docstring_warns: bool = True

Whether to display the 'Warns' section in the object's docstring.

show_docstring_yields `class-attribute` `instance-attribute` ¤


show_docstring_yields: bool = True

Whether to display the 'Yields' section in the object's docstring.

show_if_no_docstring `class-attribute` `instance-attribute` ¤


show_if_no_docstring: bool = False

Show the object heading even if it has no docstring or children with docstrings.

show_inheritance_diagram `class-attribute` `instance-attribute` ¤


show_inheritance_diagram: bool = False

Show the inheritance diagram of a class using Mermaid.

show_labels `class-attribute` `instance-attribute` ¤


show_labels: bool = True

Whether to show labels of the members.

show_object_full_path `class-attribute` `instance-attribute` ¤


show_object_full_path: bool = False

Show the full Python path of every object.

show_overloads `class-attribute` `instance-attribute` ¤


show_overloads: bool = True

Show the overloads of a function or method.

show_root_full_path `class-attribute` `instance-attribute` ¤


show_root_full_path: bool = True

Show the full Python path for the root object heading.

show_root_heading `class-attribute` `instance-attribute` ¤


show_root_heading: bool = False

Show the heading of the object at the root of the documentation tree.

The root object is the object referenced by the identifier after :::.

show_root_members_full_path `class-attribute` `instance-attribute` ¤


show_root_members_full_path: bool = False

Show the full Python path of the root members.

show_root_toc_entry `class-attribute` `instance-attribute` ¤


show_root_toc_entry: bool = True

If the root heading is not shown, at least add a ToC entry for it.

show_signature `class-attribute` `instance-attribute` ¤


show_signature: bool = True

Show methods and functions signatures.

show_signature_annotations `class-attribute` `instance-attribute` ¤


show_signature_annotations: bool = False

Show the type annotations in methods and functions signatures.

show_source `class-attribute` `instance-attribute` ¤


show_source: bool = True

Show the source code of this object.

show_submodules `class-attribute` `instance-attribute` ¤


show_submodules: bool = False

When rendering a module, show its submodules recursively.

show_symbol_type_heading `class-attribute` `instance-attribute` ¤


show_symbol_type_heading: bool = False

Show the symbol type in headings (e.g. mod, class, meth, func and attr).

show_symbol_type_toc `class-attribute` `instance-attribute` ¤


show_symbol_type_toc: bool = False

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

signature_crossrefs `class-attribute` `instance-attribute` ¤


signature_crossrefs: bool = False

Whether to render cross-references for type annotations in signatures.

summary `class-attribute` `instance-attribute` ¤


summary: bool | SummaryOption = field(default_factory=SummaryOption)

Whether to render summaries of modules, classes, functions (methods) and attributes.

toc_label `class-attribute` `instance-attribute` ¤


toc_label: str = ''

A custom string to override the autogenerated toc label of the root object.

unwrap_annotated `class-attribute` `instance-attribute` ¤


unwrap_annotated: bool = False

Whether to unwrap Annotated types to show only the type without the annotations.

coerce `classmethod` ¤


coerce(**data: Any) -> MutableMapping[str, Any]

Coerce data.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

PythonOptions `dataclass` ¤


PythonOptions(
    allow_inspection: bool = True,
    force_inspection: bool = False,
    annotations_path: Literal["brief", "source", "full"] = "brief",
    backlinks: Literal["flat", "tree", False] = False,
    docstring_options: (
        GoogleStyleOptions
        | NumpyStyleOptions
        | SphinxStyleOptions
        | AutoStyleOptions
        | None
    ) = None,
    docstring_section_style: Literal["table", "list", "spacy"] = "table",
    docstring_style: Literal["auto", "google", "numpy", "sphinx"] | None = "google",
    extensions: list[str | dict[str, Any]] = list(),
    filters: list[tuple[Pattern, bool]] | Literal["public"] = lambda: [
        (compile(removeprefix("!")), startswith("!")) for filtr in _DEFAULT_FILTERS
    ](),
    find_stubs_package: bool = False,
    group_by_category: bool = True,
    heading: str = "",
    heading_level: int = 2,
    inherited_members: bool | list[str] = False,
    line_length: int = 60,
    members: list[str] | bool | None = None,
    members_order: Literal["alphabetical", "source"] = "alphabetical",
    merge_init_into_class: bool = False,
    modernize_annotations: bool = False,
    parameter_headings: bool = False,
    preload_modules: list[str] = list(),
    relative_crossrefs: bool = False,
    scoped_crossrefs: bool = False,
    show_overloads: bool = True,
    separate_signature: bool = False,
    show_bases: bool = True,
    show_category_heading: bool = False,
    show_docstring_attributes: bool = True,
    show_docstring_classes: bool = True,
    show_docstring_description: bool = True,
    show_docstring_examples: bool = True,
    show_docstring_functions: bool = True,
    show_docstring_modules: bool = True,
    show_docstring_other_parameters: bool = True,
    show_docstring_parameters: bool = True,
    show_docstring_raises: bool = True,
    show_docstring_receives: bool = True,
    show_docstring_returns: bool = True,
    show_docstring_warns: bool = True,
    show_docstring_yields: bool = True,
    show_if_no_docstring: bool = False,
    show_inheritance_diagram: bool = False,
    show_labels: bool = True,
    show_object_full_path: bool = False,
    show_root_full_path: bool = True,
    show_root_heading: bool = False,
    show_root_members_full_path: bool = False,
    show_root_toc_entry: bool = True,
    show_signature_annotations: bool = False,
    show_signature: bool = True,
    show_source: bool = True,
    show_submodules: bool = False,
    show_symbol_type_heading: bool = False,
    show_symbol_type_toc: bool = False,
    signature_crossrefs: bool = False,
    summary: SummaryOption = SummaryOption(),
    toc_label: str = "",
    unwrap_annotated: bool = False,
    extra: dict[str, Any] = dict(),
)

Final options passed as template context.

Used by:

python PythonHandler
- collect
- render

Methods:

coerce –

Create an instance from a dictionary.
from_data –

Create an instance from a dictionary.

Attributes:

allow_inspection (bool) –

Whether to allow inspecting modules when visiting them is not possible.
annotations_path (Literal['brief', 'source', 'full']) –

The verbosity for annotations path: brief (recommended), source (as written in the source), or full.
backlinks (Literal['flat', 'tree', False]) –

Whether to render backlinks, and how.
docstring_options (GoogleStyleOptions | NumpyStyleOptions | SphinxStyleOptions | AutoStyleOptions | None) –

The options for the docstring parser.
docstring_section_style (Literal['table', 'list', 'spacy']) –

The style used to render docstring sections.
docstring_style (Literal['auto', 'google', 'numpy', 'sphinx'] | None) –

The docstring style to use: auto, google, numpy, sphinx, or None.
extensions (list[str | dict[str, Any]]) –

A list of Griffe extensions to load.
extra (dict[str, Any]) –

Extra options.
filters (list[tuple[Pattern, bool]] | Literal['public']) –

A list of filters, or "public".
find_stubs_package (bool) –

Whether to load stubs package (package-stubs) when extracting docstrings.
force_inspection (bool) –

Whether to force using dynamic analysis when loading data.
group_by_category (bool) –

Group the object's children by categories: attributes, classes, functions, and modules.
heading (str) –

A custom string to override the autogenerated heading of the root object.
heading_level (int) –

The initial heading level to use.
inherited_members (bool | list[str]) –

A boolean, or an explicit list of inherited members to render.
line_length (int) –

Maximum line length when formatting code/signatures.
members (list[str] | bool | None) –

A boolean, or an explicit list of members to render.
members_order (Literal['alphabetical', 'source']) –

The members ordering to use.
merge_init_into_class (bool) –

Whether to merge the __init__ method into the class' signature and docstring.
modernize_annotations (bool) –

Whether to modernize annotations, for example Optional[str] into str | None.
parameter_headings (bool) –

Whether to render headings for parameters (therefore showing parameters in the ToC).
preload_modules (list[str]) –

Pre-load modules that are not specified directly in autodoc instructions (::: identifier).
relative_crossrefs (bool) –

Whether to enable the relative crossref syntax.
scoped_crossrefs (bool) –

Whether to enable the scoped crossref ability.
separate_signature (bool) –

Whether to put the whole signature in a code block below the heading.
show_bases (bool) –

Show the base classes of a class.
show_category_heading (bool) –

When grouped by categories, show a heading for each category.
show_docstring_attributes (bool) –

Whether to display the 'Attributes' section in the object's docstring.
show_docstring_classes (bool) –

Whether to display the 'Classes' section in the object's docstring.
show_docstring_description (bool) –

Whether to display the textual block (including admonitions) in the object's docstring.
show_docstring_examples (bool) –

Whether to display the 'Examples' section in the object's docstring.
show_docstring_functions (bool) –

Whether to display the 'Functions' or 'Methods' sections in the object's docstring.
show_docstring_modules (bool) –

Whether to display the 'Modules' section in the object's docstring.
show_docstring_other_parameters (bool) –

Whether to display the 'Other Parameters' section in the object's docstring.
show_docstring_parameters (bool) –

Whether to display the 'Parameters' section in the object's docstring.
show_docstring_raises (bool) –

Whether to display the 'Raises' section in the object's docstring.
show_docstring_receives (bool) –

Whether to display the 'Receives' section in the object's docstring.
show_docstring_returns (bool) –

Whether to display the 'Returns' section in the object's docstring.
show_docstring_warns (bool) –

Whether to display the 'Warns' section in the object's docstring.
show_docstring_yields (bool) –

Whether to display the 'Yields' section in the object's docstring.
show_if_no_docstring (bool) –

Show the object heading even if it has no docstring or children with docstrings.
show_inheritance_diagram (bool) –

Show the inheritance diagram of a class using Mermaid.
show_labels (bool) –

Whether to show labels of the members.
show_object_full_path (bool) –

Show the full Python path of every object.
show_overloads (bool) –

Show the overloads of a function or method.
show_root_full_path (bool) –

Show the full Python path for the root object heading.
show_root_heading (bool) –

Show the heading of the object at the root of the documentation tree.
show_root_members_full_path (bool) –

Show the full Python path of the root members.
show_root_toc_entry (bool) –

If the root heading is not shown, at least add a ToC entry for it.
show_signature (bool) –

Show methods and functions signatures.
show_signature_annotations (bool) –

Show the type annotations in methods and functions signatures.
show_source (bool) –

Show the source code of this object.
show_submodules (bool) –

When rendering a module, show its submodules recursively.
show_symbol_type_heading (bool) –

Show the symbol type in headings (e.g. mod, class, meth, func and attr).
show_symbol_type_toc (bool) –

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).
signature_crossrefs (bool) –

Whether to render cross-references for type annotations in signatures.
summary (SummaryOption) –

Whether to render summaries of modules, classes, functions (methods) and attributes.
toc_label (str) –

A custom string to override the autogenerated toc label of the root object.
unwrap_annotated (bool) –

Whether to unwrap Annotated types to show only the type without the annotations.

allow_inspection `class-attribute` `instance-attribute` ¤


allow_inspection: bool = True

Whether to allow inspecting modules when visiting them is not possible.

annotations_path `class-attribute` `instance-attribute` ¤


annotations_path: Literal['brief', 'source', 'full'] = 'brief'

The verbosity for annotations path: brief (recommended), source (as written in the source), or full.

backlinks `class-attribute` `instance-attribute` ¤


backlinks: Literal['flat', 'tree', False] = False

Whether to render backlinks, and how.

docstring_options `class-attribute` `instance-attribute` ¤


docstring_options: (
    GoogleStyleOptions
    | NumpyStyleOptions
    | SphinxStyleOptions
    | AutoStyleOptions
    | None
) = None

The options for the docstring parser.

See docstring parsers and their options in Griffe docs.

docstring_section_style `class-attribute` `instance-attribute` ¤


docstring_section_style: Literal['table', 'list', 'spacy'] = 'table'

The style used to render docstring sections.

docstring_style `class-attribute` `instance-attribute` ¤


docstring_style: Literal['auto', 'google', 'numpy', 'sphinx'] | None = 'google'

The docstring style to use: auto, google, numpy, sphinx, or None.

extensions `class-attribute` `instance-attribute` ¤


extensions: list[str | dict[str, Any]] = field(default_factory=list)

A list of Griffe extensions to load.

extra `class-attribute` `instance-attribute` ¤


extra: dict[str, Any] = field(default_factory=dict)

Extra options.

filters `class-attribute` `instance-attribute` ¤


filters: list[tuple[Pattern, bool]] | Literal["public"] = field(
    default_factory=lambda: [
        (compile(removeprefix("!")), startswith("!")) for filtr in _DEFAULT_FILTERS
    ]
)

A list of filters, or "public".

find_stubs_package `class-attribute` `instance-attribute` ¤


find_stubs_package: bool = False

Whether to load stubs package (package-stubs) when extracting docstrings.

force_inspection `class-attribute` `instance-attribute` ¤


force_inspection: bool = False

Whether to force using dynamic analysis when loading data.

group_by_category `class-attribute` `instance-attribute` ¤


group_by_category: bool = True

Group the object's children by categories: attributes, classes, functions, and modules.

heading `class-attribute` `instance-attribute` ¤


heading: str = ''

A custom string to override the autogenerated heading of the root object.

heading_level `class-attribute` `instance-attribute` ¤


heading_level: int = 2

The initial heading level to use.

inherited_members `class-attribute` `instance-attribute` ¤


inherited_members: bool | list[str] = False

A boolean, or an explicit list of inherited members to render.

If true, select all inherited members, which can then be filtered with members. If false or empty list, do not select any inherited member.

line_length `class-attribute` `instance-attribute` ¤


line_length: int = 60

Maximum line length when formatting code/signatures.

members `class-attribute` `instance-attribute` ¤


members: list[str] | bool | None = None

A boolean, or an explicit list of members to render.

If true, select all members without further filtering. If false or empty list, do not render members. If none, select all members and apply further filtering with filters and docstrings.

members_order `class-attribute` `instance-attribute` ¤


members_order: Literal['alphabetical', 'source'] = 'alphabetical'

The members ordering to use.

alphabetical: order by the members names,
source: order members as they appear in the source file.

merge_init_into_class `class-attribute` `instance-attribute` ¤


merge_init_into_class: bool = False

Whether to merge the __init__ method into the class' signature and docstring.

modernize_annotations `class-attribute` `instance-attribute` ¤


modernize_annotations: bool = False

Whether to modernize annotations, for example Optional[str] into str | None.

parameter_headings `class-attribute` `instance-attribute` ¤


parameter_headings: bool = False

Whether to render headings for parameters (therefore showing parameters in the ToC).

preload_modules `class-attribute` `instance-attribute` ¤


preload_modules: list[str] = field(default_factory=list)

Pre-load modules that are not specified directly in autodoc instructions (::: identifier).

It is useful when you want to render documentation for a particular member of an object, and this member is imported from another package than its parent.

For an imported member to be rendered, you need to add it to the __all__ attribute of the importing module.

The modules must be listed as an array of strings.

relative_crossrefs `class-attribute` `instance-attribute` ¤


relative_crossrefs: bool = False

Whether to enable the relative crossref syntax.

scoped_crossrefs `class-attribute` `instance-attribute` ¤


scoped_crossrefs: bool = False

Whether to enable the scoped crossref ability.

separate_signature `class-attribute` `instance-attribute` ¤


separate_signature: bool = False

Whether to put the whole signature in a code block below the heading.

If Black or Ruff are installed, the signature is also formatted using them.

show_bases `class-attribute` `instance-attribute` ¤


show_bases: bool = True

Show the base classes of a class.

show_category_heading `class-attribute` `instance-attribute` ¤


show_category_heading: bool = False

When grouped by categories, show a heading for each category.

show_docstring_attributes `class-attribute` `instance-attribute` ¤


show_docstring_attributes: bool = True

Whether to display the 'Attributes' section in the object's docstring.

show_docstring_classes `class-attribute` `instance-attribute` ¤


show_docstring_classes: bool = True

Whether to display the 'Classes' section in the object's docstring.

show_docstring_description `class-attribute` `instance-attribute` ¤


show_docstring_description: bool = True

Whether to display the textual block (including admonitions) in the object's docstring.

show_docstring_examples `class-attribute` `instance-attribute` ¤


show_docstring_examples: bool = True

Whether to display the 'Examples' section in the object's docstring.

show_docstring_functions `class-attribute` `instance-attribute` ¤


show_docstring_functions: bool = True

Whether to display the 'Functions' or 'Methods' sections in the object's docstring.

show_docstring_modules `class-attribute` `instance-attribute` ¤


show_docstring_modules: bool = True

Whether to display the 'Modules' section in the object's docstring.

show_docstring_other_parameters `class-attribute` `instance-attribute` ¤


show_docstring_other_parameters: bool = True

Whether to display the 'Other Parameters' section in the object's docstring.

show_docstring_parameters `class-attribute` `instance-attribute` ¤


show_docstring_parameters: bool = True

Whether to display the 'Parameters' section in the object's docstring.

show_docstring_raises `class-attribute` `instance-attribute` ¤


show_docstring_raises: bool = True

Whether to display the 'Raises' section in the object's docstring.

show_docstring_receives `class-attribute` `instance-attribute` ¤


show_docstring_receives: bool = True

Whether to display the 'Receives' section in the object's docstring.

show_docstring_returns `class-attribute` `instance-attribute` ¤


show_docstring_returns: bool = True

Whether to display the 'Returns' section in the object's docstring.

show_docstring_warns `class-attribute` `instance-attribute` ¤


show_docstring_warns: bool = True

Whether to display the 'Warns' section in the object's docstring.

show_docstring_yields `class-attribute` `instance-attribute` ¤


show_docstring_yields: bool = True

Whether to display the 'Yields' section in the object's docstring.

show_if_no_docstring `class-attribute` `instance-attribute` ¤


show_if_no_docstring: bool = False

Show the object heading even if it has no docstring or children with docstrings.

show_inheritance_diagram `class-attribute` `instance-attribute` ¤


show_inheritance_diagram: bool = False

Show the inheritance diagram of a class using Mermaid.

show_labels `class-attribute` `instance-attribute` ¤


show_labels: bool = True

Whether to show labels of the members.

show_object_full_path `class-attribute` `instance-attribute` ¤


show_object_full_path: bool = False

Show the full Python path of every object.

show_overloads `class-attribute` `instance-attribute` ¤


show_overloads: bool = True

Show the overloads of a function or method.

show_root_full_path `class-attribute` `instance-attribute` ¤


show_root_full_path: bool = True

Show the full Python path for the root object heading.

show_root_heading `class-attribute` `instance-attribute` ¤


show_root_heading: bool = False

Show the heading of the object at the root of the documentation tree.

The root object is the object referenced by the identifier after :::.

show_root_members_full_path `class-attribute` `instance-attribute` ¤


show_root_members_full_path: bool = False

Show the full Python path of the root members.

show_root_toc_entry `class-attribute` `instance-attribute` ¤


show_root_toc_entry: bool = True

If the root heading is not shown, at least add a ToC entry for it.

show_signature `class-attribute` `instance-attribute` ¤


show_signature: bool = True

Show methods and functions signatures.

show_signature_annotations `class-attribute` `instance-attribute` ¤


show_signature_annotations: bool = False

Show the type annotations in methods and functions signatures.

show_source `class-attribute` `instance-attribute` ¤


show_source: bool = True

Show the source code of this object.

show_submodules `class-attribute` `instance-attribute` ¤


show_submodules: bool = False

When rendering a module, show its submodules recursively.

show_symbol_type_heading `class-attribute` `instance-attribute` ¤


show_symbol_type_heading: bool = False

Show the symbol type in headings (e.g. mod, class, meth, func and attr).

show_symbol_type_toc `class-attribute` `instance-attribute` ¤


show_symbol_type_toc: bool = False

Show the symbol type in the Table of Contents (e.g. mod, class, methd, func and attr).

signature_crossrefs `class-attribute` `instance-attribute` ¤


signature_crossrefs: bool = False

Whether to render cross-references for type annotations in signatures.

summary `class-attribute` `instance-attribute` ¤


summary: SummaryOption = field(default_factory=SummaryOption)

Whether to render summaries of modules, classes, functions (methods) and attributes.

toc_label `class-attribute` `instance-attribute` ¤


toc_label: str = ''

A custom string to override the autogenerated toc label of the root object.

unwrap_annotated `class-attribute` `instance-attribute` ¤


unwrap_annotated: bool = False

Whether to unwrap Annotated types to show only the type without the annotations.

coerce `classmethod` ¤


coerce(**data: Any) -> MutableMapping[str, Any]

Create an instance from a dictionary.

from_data `classmethod` ¤


from_data(**data: Any) -> Self

Create an instance from a dictionary.

SphinxStyleOptions `dataclass` ¤


SphinxStyleOptions()

Sphinx style docstring options.

SummaryOption `dataclass` ¤


SummaryOption(
    attributes: bool = False,
    functions: bool = False,
    classes: bool = False,
    modules: bool = False,
)

Summary option.

Returned by:

python PythonOptions summary

Used by:

python PythonOptions

Attributes:

attributes (bool) –

Whether to render summaries of attributes.
classes (bool) –

Whether to render summaries of classes.
functions (bool) –

Whether to render summaries of functions (methods).
modules (bool) –

Whether to render summaries of modules.

attributes `class-attribute` `instance-attribute` ¤


attributes: bool = False

Whether to render summaries of attributes.

classes `class-attribute` `instance-attribute` ¤


classes: bool = False

Whether to render summaries of classes.

functions `class-attribute` `instance-attribute` ¤


functions: bool = False

Whether to render summaries of functions (methods).

modules `class-attribute` `instance-attribute` ¤


modules: bool = False

Whether to render summaries of modules.

do_as_attributes_section ¤


do_as_attributes_section(
    context: Context, attributes: Sequence[Attribute], *, check_public: bool = True
) -> DocstringSectionAttributes

Build an attributes section from a list of attributes.

Parameters:

attributes ¤
(Sequence[Attribute]) –

The attributes to build the section from.
check_public ¤
(bool, default: True ) –

Whether to check if the attribute is public.

Returns:

DocstringSectionAttributes –

An attributes docstring section.

do_as_classes_section ¤


do_as_classes_section(
    context: Context, classes: Sequence[Class], *, check_public: bool = True
) -> DocstringSectionClasses

Build a classes section from a list of classes.

Parameters:

classes ¤
(Sequence[Class]) –

The classes to build the section from.
check_public ¤
(bool, default: True ) –

Whether to check if the class is public.

Returns:

DocstringSectionClasses –

A classes docstring section.

do_as_functions_section ¤


do_as_functions_section(
    context: Context, functions: Sequence[Function], *, check_public: bool = True
) -> DocstringSectionFunctions

Build a functions section from a list of functions.

Parameters:

functions ¤
(Sequence[Function]) –

The functions to build the section from.
check_public ¤
(bool, default: True ) –

Whether to check if the function is public.

Returns:

DocstringSectionFunctions –

A functions docstring section.

do_as_modules_section ¤


do_as_modules_section(
    context: Context, modules: Sequence[Module], *, check_public: bool = True
) -> DocstringSectionModules

Build a modules section from a list of modules.

Parameters:

modules ¤
(Sequence[Module]) –

The modules to build the section from.
check_public ¤
(bool, default: True ) –

Whether to check if the module is public.

Returns:

DocstringSectionModules –

A modules docstring section.

do_backlink_tree ¤


do_backlink_tree(backlinks: list[Backlink]) -> Tree[BacklinkCrumb]

Build a tree of backlinks.

Parameters:

backlinks ¤
(list[Backlink]) –

The list of backlinks.

Returns:

Tree[BacklinkCrumb] –

A tree of backlinks.

do_crossref ¤


do_crossref(path: str, *, brief: bool = True) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

path ¤
(str) –

The path to link to.
brief ¤
(bool, default: True ) –

Show only the last part of the path, add full path as hover.

Returns:

Markup –

Markup text.

do_filter_objects ¤


do_filter_objects(
    objects_dictionary: dict[str, Object | Alias],
    *,
    filters: Sequence[tuple[Pattern, bool]] | Literal["public"] | None = None,
    members_list: bool | list[str] | None = None,
    inherited_members: bool | list[str] = False,
    keep_no_docstrings: bool = True
) -> list[Object | Alias]

Filter a dictionary of objects based on their docstrings.

Parameters:

objects_dictionary ¤
(dict[str, Object | Alias]) –

The dictionary of objects.
filters ¤
(Sequence[tuple[Pattern, bool]] | Literal['public'] | None, default: None ) –

Filters to apply, based on members' names, or "public". Each element is a tuple: a pattern, and a boolean indicating whether to reject the object if the pattern matches.
members_list ¤
(bool | list[str] | None, default: None ) –

An optional, explicit list of members to keep. When given and empty, return an empty list. When given and not empty, ignore filters and docstrings presence/absence.
inherited_members ¤
(bool | list[str], default: False ) –

Whether to keep inherited members or exclude them.
keep_no_docstrings ¤
(bool, default: True ) –

Whether to keep objects with no/empty docstrings (recursive check).

Returns:

list[Object | Alias] –

A list of objects.

do_format_attribute ¤


do_format_attribute(
    context: Context,
    attribute_path: Markup,
    attribute: Attribute,
    line_length: int,
    *,
    crossrefs: bool = False
) -> str

Format an attribute.

Parameters:

context ¤
(Context) –

Jinja context, passed automatically.
attribute_path ¤
(Markup) –

The path of the callable we render the signature of.
attribute ¤
(Attribute) –

The attribute we render the signature of.
line_length ¤
(int) –

The line length.
crossrefs ¤
(bool, default: False ) –

Whether to cross-reference types in the signature.

Returns:

str –

The same code, formatted.

do_format_code ¤


do_format_code(code: str, line_length: int) -> str

Format code.

Parameters:

code ¤
(str) –

The code to format.
line_length ¤
(int) –

The line length.

Returns:

str –

The same code, formatted.

do_format_signature ¤


do_format_signature(
    context: Context,
    callable_path: Markup,
    function: Function,
    line_length: int,
    *,
    annotations: bool | None = None,
    crossrefs: bool = False
) -> str

Format a signature.

Parameters:

context ¤
(Context) –

Jinja context, passed automatically.
callable_path ¤
(Markup) –

The path of the callable we render the signature of.
function ¤
(Function) –

The function we render the signature of.
line_length ¤
(int) –

The line length.
annotations ¤
(bool | None, default: None ) –

Whether to show type annotations.
crossrefs ¤
(bool, default: False ) –

Whether to cross-reference types in the signature.

Returns:

str –

The same code, formatted.

Referenced by:

Home Changelog 1.0.0 - 2023-05-11 Breaking changes
Insiders Getting started Changelog mkdocstrings-python Insiders 1.0.0 May 10, 2023

do_get_template ¤


do_get_template(env: Environment, obj: str | Object) -> str

Get the template name used to render an object.

Parameters:

env ¤
(Environment) –

The Jinja environment, passed automatically.
obj ¤
(str | Object) –

A Griffe object, or a template name.

Returns:

str –

A template name.

do_multi_crossref ¤


do_multi_crossref(text: str, *, code: bool = True) -> Markup

Deprecated. Filter to create cross-references.

Parameters:

text ¤
(str) –

The text to scan.
code ¤
(bool, default: True ) –

Whether to wrap the result in a code tag.

Returns:

Markup –

Markup text.

do_order_members ¤


do_order_members(
    members: Sequence[Object | Alias],
    order: Order,
    members_list: bool | list[str] | None,
) -> Sequence[Object | Alias]

Order members given an ordering method.

Parameters:

members ¤
(Sequence[Object | Alias]) –

The members to order.
order ¤
(Order) –

The ordering method.
members_list ¤
(bool | list[str] | None) –

An optional member list (manual ordering).

Returns:

Sequence[Object | Alias] –

The same members, ordered.

do_split_path ¤


do_split_path(path: str, full_path: str) -> Iterator[tuple[str, str, str, str]]

Split object paths for building cross-references.

Parameters:

path ¤
(str) –

The path to split.
full_path ¤
(str) –

The full path, used to compute correct paths for each part of the path.

Yields:

tuple[str, str, str, str] –

4-tuples: prefix, word, full path, suffix.

get_handler ¤


get_handler(
    handler_config: MutableMapping[str, Any], tool_config: MkDocsConfig, **kwargs: Any
) -> PythonHandler

Return an instance of PythonHandler.

Parameters:

handler_config ¤
(MutableMapping[str, Any]) –

The handler configuration.
tool_config ¤
(MkDocsConfig) –

The tool (SSG) configuration.

Returns:

PythonHandler –

An instance of PythonHandler.

config ¤

Deprecated. Import from mkdocstrings_handlers.python directly.

handler ¤

Deprecated. Import from mkdocstrings_handlers.python directly.

rendering ¤

Deprecated. Import from mkdocstrings_handlers.python directly.

python ¤

Order module-attribute ¤

Tree module-attribute ¤

do_stash_crossref module-attribute ¤

AutoStyleOptions dataclass ¤

default class-attribute instance-attribute ¤

method class-attribute instance-attribute ¤

per_style_options class-attribute instance-attribute ¤

style_order class-attribute instance-attribute ¤

from_data classmethod ¤

AutorefsHook ¤

current_object ¤

config ¤

config instance-attribute ¤

current_object instance-attribute ¤

expand_identifier ¤

identifier ¤

get_context ¤

GoogleStyleOptions dataclass ¤

ignore_init_summary class-attribute instance-attribute ¤

receives_multiple_items class-attribute instance-attribute ¤

receives_named_value class-attribute instance-attribute ¤

returns_multiple_items class-attribute instance-attribute ¤

returns_named_value class-attribute instance-attribute ¤

returns_type_in_property_summary class-attribute instance-attribute ¤

trim_doctest_flags class-attribute instance-attribute ¤

warn_unknown_params class-attribute instance-attribute ¤

Inventory dataclass ¤

base class-attribute instance-attribute ¤

domains class-attribute instance-attribute ¤

url instance-attribute ¤

NumpyStyleOptions dataclass ¤

ignore_init_summary class-attribute instance-attribute ¤

trim_doctest_flags class-attribute instance-attribute ¤

warn_unknown_params class-attribute instance-attribute ¤

PerStyleOptions dataclass ¤

google class-attribute instance-attribute ¤

numpy class-attribute instance-attribute ¤

sphinx class-attribute instance-attribute ¤

from_data classmethod ¤

PythonConfig dataclass ¤

inventories class-attribute instance-attribute ¤

load_external_modules class-attribute instance-attribute ¤

locale class-attribute instance-attribute ¤

options class-attribute instance-attribute ¤

paths class-attribute instance-attribute ¤

coerce classmethod ¤

from_data classmethod ¤

PythonHandler ¤

config ¤

base_dir ¤

**kwargs ¤

base_dir instance-attribute ¤

config instance-attribute ¤

custom_templates instance-attribute ¤

domain class-attribute ¤

enable_inventory class-attribute ¤

env instance-attribute ¤

extra_css class-attribute instance-attribute ¤

fallback_config class-attribute ¤

fallback_theme class-attribute ¤

global_options instance-attribute ¤

md property ¤

mdx instance-attribute ¤

mdx_config instance-attribute ¤

name class-attribute ¤

outer_layer property ¤

theme instance-attribute ¤

collect ¤

identifier ¤

options ¤

do_convert_markdown ¤

text ¤

heading_level ¤

html_id ¤

strip_paragraph ¤

do_heading ¤

content ¤

heading_level ¤

role ¤

Order `module-attribute` ¤

Tree `module-attribute` ¤

do_stash_crossref `module-attribute` ¤

AutoStyleOptions `dataclass` ¤

default `class-attribute` `instance-attribute` ¤

method `class-attribute` `instance-attribute` ¤

per_style_options `class-attribute` `instance-attribute` ¤

style_order `class-attribute` `instance-attribute` ¤

from_data `classmethod` ¤

`current_object` ¤

`config` ¤

config `instance-attribute` ¤

current_object `instance-attribute` ¤

`identifier` ¤

GoogleStyleOptions `dataclass` ¤

ignore_init_summary `class-attribute` `instance-attribute` ¤

receives_multiple_items `class-attribute` `instance-attribute` ¤

receives_named_value `class-attribute` `instance-attribute` ¤

returns_multiple_items `class-attribute` `instance-attribute` ¤

returns_named_value `class-attribute` `instance-attribute` ¤

returns_type_in_property_summary `class-attribute` `instance-attribute` ¤

trim_doctest_flags `class-attribute` `instance-attribute` ¤

warn_unknown_params `class-attribute` `instance-attribute` ¤

Inventory `dataclass` ¤

base `class-attribute` `instance-attribute` ¤

domains `class-attribute` `instance-attribute` ¤

url `instance-attribute` ¤

NumpyStyleOptions `dataclass` ¤

ignore_init_summary `class-attribute` `instance-attribute` ¤

trim_doctest_flags `class-attribute` `instance-attribute` ¤

warn_unknown_params `class-attribute` `instance-attribute` ¤

PerStyleOptions `dataclass` ¤

google `class-attribute` `instance-attribute` ¤

numpy `class-attribute` `instance-attribute` ¤

sphinx `class-attribute` `instance-attribute` ¤

from_data `classmethod` ¤

PythonConfig `dataclass` ¤

inventories `class-attribute` `instance-attribute` ¤

load_external_modules `class-attribute` `instance-attribute` ¤

locale `class-attribute` `instance-attribute` ¤

options `class-attribute` `instance-attribute` ¤

paths `class-attribute` `instance-attribute` ¤

coerce `classmethod` ¤

from_data `classmethod` ¤

`config` ¤

`base_dir` ¤

`kwargs`** ¤

base_dir `instance-attribute` ¤

config `instance-attribute` ¤

custom_templates `instance-attribute` ¤

domain `class-attribute` ¤

enable_inventory `class-attribute` ¤

env `instance-attribute` ¤

extra_css `class-attribute` `instance-attribute` ¤

fallback_config `class-attribute` ¤

fallback_theme `class-attribute` ¤

global_options `instance-attribute` ¤

md `property` ¤

mdx `instance-attribute` ¤

mdx_config `instance-attribute` ¤

name `class-attribute` ¤

outer_layer `property` ¤

theme `instance-attribute` ¤

`identifier` ¤

`options` ¤

`text` ¤

`heading_level` ¤

`html_id` ¤

`strip_paragraph` ¤

`content` ¤

`heading_level` ¤

`role` ¤

`hidden` ¤

`toc_label` ¤

`attributes`** ¤

`identifier` ¤

`handler` ¤

`local_options` ¤

`handler` ¤

load_inventory `staticmethod` ¤