Skip to content

handler ¤

This module implements a handler for the Python language.

Classes:

Functions:

  • get_handler –

    Simply return an instance of PythonHandler.

PythonHandler ¤

PythonHandler(
    *args: Any,
    config_file_path: str | None = None,
    paths: list[str] | None = None,
    locale: str = "en",
    load_external_modules: bool = False,
    **kwargs: Any,
)


          flowchart TD
          mkdocstrings_handlers.python.handler.PythonHandler[PythonHandler]
          mkdocstrings.handlers.base.BaseHandler[BaseHandler]

                        mkdocstrings.handlers.base.BaseHandler --> mkdocstrings_handlers.python.handler.PythonHandler
              


          click mkdocstrings_handlers.python.handler.PythonHandler href "" "mkdocstrings_handlers.python.handler.PythonHandler"
          click mkdocstrings.handlers.base.BaseHandler href "" "mkdocstrings.handlers.base.BaseHandler"

The Python handler class.

Parameters:

  • *args ¤

    (Any, default: () ) –

    Handler name, theme and custom templates.

  • config_file_path ¤

    (str | None, default: None ) –

    The MkDocs configuration file path.

  • paths ¤

    (list[str] | None, default: None ) –

    A list of paths to use as Griffe search paths.

  • locale ¤

    (str, default: 'en' ) –

    The locale to use when rendering content.

  • load_external_modules ¤

    (bool, default: False ) –

    Load external modules when resolving aliases.

  • **kwargs ¤

    (Any, default: {} ) –

    Same thing, but with keyword arguments.

Methods:

Attributes:

default_config class-attribute ¤

default_config: dict = {
    "find_stubs_package": False,
    "docstring_style": "google",
    "docstring_options": {},
    "show_symbol_type_heading": False,
    "show_symbol_type_toc": False,
    "show_root_heading": False,
    "show_root_toc_entry": True,
    "show_root_full_path": True,
    "show_root_members_full_path": False,
    "show_object_full_path": False,
    "show_category_heading": False,
    "show_if_no_docstring": False,
    "show_signature": True,
    "show_signature_annotations": False,
    "signature_crossrefs": False,
    "separate_signature": False,
    "line_length": 60,
    "merge_init_into_class": False,
    "show_docstring_attributes": True,
    "show_docstring_functions": True,
    "show_docstring_classes": True,
    "show_docstring_modules": True,
    "show_docstring_description": True,
    "show_docstring_examples": True,
    "show_docstring_other_parameters": True,
    "show_docstring_parameters": True,
    "show_docstring_raises": True,
    "show_docstring_receives": True,
    "show_docstring_returns": True,
    "show_docstring_warns": True,
    "show_docstring_yields": True,
    "show_source": True,
    "show_bases": True,
    "show_inheritance_diagram": False,
    "show_submodules": False,
    "group_by_category": True,
    "heading_level": 2,
    "members_order": alphabetical.value,
    "docstring_section_style": "table",
    "members": None,
    "inherited_members": False,
    "filters": ["!^_[^_]"],
    "annotations_path": "brief",
    "preload_modules": None,
    "allow_inspection": True,
    "summary": False,
    "show_labels": True,
    "unwrap_annotated": False,
    "parameter_headings": False,
    "modernize_annotations": False,
}

Default handler configuration.

General options:

  • find_stubs_package (bool) –

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

  • allow_inspection (bool) –

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

  • show_bases (bool) –

    Show the base classes of a class. Default: True.

  • show_inheritance_diagram (bool) –

    Show the inheritance diagram of a class using Mermaid. Default: False.

  • show_source (bool) –

    Show the source code of this object. Default: True.

  • preload_modules (list[str] | None) –

    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. Default: None.

Headings options:

  • heading_level (int) –

    The initial heading level to use. Default: 2.

  • parameter_headings (bool) –

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

  • show_root_heading (bool) –

    Show the heading of the object at the root of the documentation tree (i.e. the object referenced by the identifier after :::). Default: False.

  • show_root_toc_entry (bool) –

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

  • show_root_full_path (bool) –

    Show the full Python path for the root object heading. Default: True.

  • show_root_members_full_path (bool) –

    Show the full Python path of the root members. Default: False.

  • show_object_full_path (bool) –

    Show the full Python path of every object. Default: False.

  • show_category_heading (bool) –

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

  • show_symbol_type_heading (bool) –

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

  • show_symbol_type_toc (bool) –

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

Members options:

  • inherited_members (list[str] | bool | None) –

    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. Default: False.

  • members (list[str] | bool | 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. Default: None.

  • members_order (str) –

    The members ordering to use. Options: alphabetical - order by the members names, source - order members as they appear in the source file. Default: "alphabetical".

  • filters (list[str] | None) –

    A list of filters applied to filter objects based on their name. 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). Default: ["!^_[^_]"].

  • group_by_category (bool) –

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

  • show_submodules (bool) –

    When rendering a module, show its submodules recursively. Default: False.

  • summary (bool | dict[str, bool]) –

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

  • show_labels (bool) –

    Whether to show labels of the members. Default: True.

Docstrings options:

  • docstring_style (str) –

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

  • docstring_options (dict) –

    The options for the docstring parser. See parsers under griffe.docstrings.

  • docstring_section_style (str) –

    The style used to render docstring sections. Options: table, list, spacy. Default: "table".

  • merge_init_into_class (bool) –

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

  • show_if_no_docstring (bool) –

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

  • show_docstring_attributes (bool) –

    Whether to display the "Attributes" section in the object's docstring. Default: True.

  • show_docstring_functions (bool) –

    Whether to display the "Functions" or "Methods" sections in the object's docstring. Default: True.

  • show_docstring_classes (bool) –

    Whether to display the "Classes" section in the object's docstring. Default: True.

  • show_docstring_modules (bool) –

    Whether to display the "Modules" section in the object's docstring. Default: True.

  • show_docstring_description (bool) –

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

  • show_docstring_examples (bool) –

    Whether to display the "Examples" section in the object's docstring. Default: True.

  • show_docstring_other_parameters (bool) –

    Whether to display the "Other Parameters" section in the object's docstring. Default: True.

  • show_docstring_parameters (bool) –

    Whether to display the "Parameters" section in the object's docstring. Default: True.

  • show_docstring_raises (bool) –

    Whether to display the "Raises" section in the object's docstring. Default: True.

  • show_docstring_receives (bool) –

    Whether to display the "Receives" section in the object's docstring. Default: True.

  • show_docstring_returns (bool) –

    Whether to display the "Returns" section in the object's docstring. Default: True.

  • show_docstring_warns (bool) –

    Whether to display the "Warns" section in the object's docstring. Default: True.

  • show_docstring_yields (bool) –

    Whether to display the "Yields" section in the object's docstring. Default: True.

Signatures/annotations options:

  • annotations_path (str) –

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

  • line_length (int) –

    Maximum line length when formatting code/signatures. Default: 60.

  • show_signature (bool) –

    Show methods and functions signatures. Default: True.

  • show_signature_annotations (bool) –

    Show the type annotations in methods and functions signatures. Default: False.

  • signature_crossrefs (bool) –

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

  • separate_signature (bool) –

    Whether to put the whole signature in a code block below the heading. If Black is installed, the signature is also formatted using it. Default: False.

  • unwrap_annotated (bool) –

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

  • modernize_annotations (bool) –

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

domain class-attribute instance-attribute ¤

domain: str = 'py'

The cross-documentation domain/language for this handler.

enable_inventory class-attribute instance-attribute ¤

enable_inventory: bool = True

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

extra_css class-attribute instance-attribute ¤

extra_css = ''

Extra CSS.

fallback_config class-attribute ¤

fallback_config: dict = {'fallback': True}

The configuration used to collect item during autorefs fallback.

fallback_theme class-attribute instance-attribute ¤

fallback_theme = 'material'

The fallback theme.

name class-attribute instance-attribute ¤

name: str = ''

The handler's name, for example "python".

do_convert_markdown ¤

do_convert_markdown(
    text: str,
    heading_level: int,
    html_id: str = "",
    *,
    strip_paragraph: bool = False
) -> 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

    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_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:

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:

Returns:

  • Path –

    The templates directory path.

load_inventory classmethod ¤

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:

  • str –

    Tuples of (item identifier, item URL).

normalize_extension_paths ¤

normalize_extension_paths(extensions: Sequence) -> Sequence

Resolve extension paths relative to config file.

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.

get_handler ¤

get_handler(
    *,
    theme: str,
    custom_templates: str | None = None,
    config_file_path: str | None = None,
    paths: list[str] | None = None,
    locale: str = "en",
    load_external_modules: bool = False,
    **config: Any
) -> PythonHandler

Simply return an instance of PythonHandler.

Parameters:

  • theme ¤

    (str) –

    The theme to use when rendering contents.

  • custom_templates ¤

    (str | None, default: None ) –

    Directory containing custom templates.

  • config_file_path ¤

    (str | None, default: None ) –

    The MkDocs configuration file path.

  • paths ¤

    (list[str] | None, default: None ) –

    A list of paths to use as Griffe search paths.

  • locale ¤

    (str, default: 'en' ) –

    The locale to use when rendering content.

  • load_external_modules ¤

    (bool, default: False ) –

    Load external modules when resolving aliases.

  • **config ¤

    (Any, default: {} ) –

    Configuration passed to the handler.

Returns: