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(
    config: PythonConfig, base_dir: Path, **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:

  • config ¤

    (PythonConfig) –

    The handler configuration.

  • base_dir ¤

    (Path) –

    The base directory of the project.

  • **kwargs ¤

    (Any, default: {} ) –

    Arguments passed to the parent constructor.

Methods:

  • 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_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.

  • teardown

    Teardown the handler.

  • update_env

    Update the Jinja environment with custom filters and tests.

Attributes:

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.

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.

md property ¤

The Markdown instance.

Raises:

  • RuntimeError

    When the Markdown instance is not set yet.

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.

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

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

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:

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.

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.

get_handler ¤

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

Simply return an instance of PythonHandler.

Parameters:

  • handler_config ¤

    (MutableMapping[str, Any]) –

    The handler configuration.

  • tool_config ¤

    (MkDocsConfig) –

    The tool (SSG) configuration.

Returns: