handler ¤
This module implements a handler for the Python language.
Classes:
-
PythonHandler
–The Python handler class.
Functions:
-
get_handler
–Simply return an instance of
PythonHandler
.
PythonHandler ¤
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
(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. -
extra_css
(str
) –Extra CSS.
-
fallback_config
(dict
) –Fallback configuration when searching anchors for identifiers.
-
fallback_theme
(str
) –The fallback theme.
-
md
(Markdown
) –The Markdown instance.
-
name
(str
) –The handler's name.
-
outer_layer
(bool
) –Whether we're in the outer Markdown conversion layer.
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.
fallback_config class-attribute
¤
fallback_config: dict = {}
Fallback configuration when searching anchors for identifiers.
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_headings ¤
get_inventory_urls ¤
Return the URLs of the inventory files to download.
get_options ¤
get_options(
local_options: Mapping[str, Any],
) -> HandlerOptions
get_templates_dir ¤
Return the path to the handler's templates directory.
Override to customize how the templates directory is found.
Parameters:
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:
normalize_extension_paths ¤
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(
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:
-
PythonHandler
–An instance of
PythonHandler
.