base

Base module for handlers.

This module contains the base classes for implementing collectors, renderers, and the combination of the two: handlers.

It also provides two methods:

• get_handler, that will cache handlers into the HANDLERS_CACHE dictionary.
• teardown, that will teardown all the cached handlers, and then clear the cache.

BaseCollector

The base collector class.

Inherit from this class to implement a collector.

You will have to implement the collect method. You can also implement the teardown method.

collect(identifier, config)

Collect data given an identifier and selection configuration.

In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into a Python dictionary for example, though the implementation is completely free.

Parameters:

Name	Type	Description	Default
identifier	str	An identifier for which to collect data. For example, in Python, it would be 'mkdocstrings.handlers' to collect documentation about the handlers module. It can be anything that you can feed to the tool of your choice.	required
config	Mapping[str, Any]	The handler's configuraton options.	required

Returns:

Type	Description
CollectorItem	Anything you want, as long as you can feed it to the renderer's render method.

Source code in mkdocstrings/handlers/base.py

def collect(self, identifier: str, config: Mapping[str, Any]) -> CollectorItem:
    """Collect data given an identifier and selection configuration.

    In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
    a Python dictionary for example, though the implementation is completely free.

    Arguments:
        identifier: An identifier for which to collect data. For example, in Python,
            it would be 'mkdocstrings.handlers' to collect documentation about the handlers module.
            It can be anything that you can feed to the tool of your choice.
        config: The handler's configuraton options.

    Returns:
        Anything you want, as long as you can feed it to the renderer's `render` method.
    """  # noqa: DAR202,DAR401
    raise NotImplementedError

teardown()

Teardown the collector.

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

Source code in mkdocstrings/handlers/base.py

def teardown(self) -> None:
    """Teardown the collector.

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

BaseHandler(*args, **kwargs)

Bases: BaseCollector, BaseRenderer

The base handler class.

Inherit from this class to implement a handler.

It's usually just a combination of a collector and a renderer, but you can make it as complex as you need.

Attributes:

Name	Type	Description
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.
fallback_config	dict	The configuration used to collect item during autorefs fallback.

Parameters:

Name	Type	Description	Default
*args	str | BaseCollector | BaseRenderer	Collector and renderer, or handler name, theme and custom_templates.	()
**kwargs	str | BaseCollector | BaseRenderer	Same thing, but with keyword arguments.	{}

Raises:

Type	Description
ValueError	When the givin parameters are invalid.

Source code in mkdocstrings/handlers/base.py

def __init__(self, *args: str | BaseCollector | BaseRenderer, **kwargs: str | BaseCollector | BaseRenderer) -> None:
    """Initialize the object.

    Arguments:
        *args: Collector and renderer, or handler name, theme and custom_templates.
        **kwargs: Same thing, but with keyword arguments.

    Raises:
        ValueError: When the givin parameters are invalid.
    """
    # The method accepts *args and **kwargs temporarily,
    # to support the transition period where the BaseCollector
    # and BaseRenderer are deprecated, and the BaseHandler
    # can be instantiated with both instances of collector/renderer,
    # or renderer parameters, as positional parameters.
    # Supported:
    #   handler = Handler(collector, renderer)
    #   handler = Handler(collector=collector, renderer=renderer)
    #   handler = Handler("python", "material")
    #   handler = Handler("python", "material", "templates")
    #   handler = Handler(handler="python", theme="material")
    #   handler = Handler(handler="python", theme="material", custom_templates="templates")
    # Invalid:
    #   handler = Handler("python", "material", collector, renderer)
    #   handler = Handler("python", theme="material", collector=collector)
    #   handler = Handler(collector, renderer, "material")
    #   handler = Handler(collector, renderer, theme="material")
    #   handler = Handler(collector)
    #   handler = Handler(renderer)
    #   etc.

    collector = None
    renderer = None

    # parsing positional arguments
    str_args = []
    for arg in args:
        if isinstance(arg, BaseCollector):
            collector = arg
        elif isinstance(arg, BaseRenderer):
            renderer = arg
        elif isinstance(arg, str):
            str_args.append(arg)

    while len(str_args) != 3:
        str_args.append(None)  # type: ignore[arg-type]

    handler, theme, custom_templates = str_args

    # fetching values from keyword arguments
    if "collector" in kwargs:
        collector = kwargs.pop("collector")  # type: ignore[assignment]
    if "renderer" in kwargs:
        renderer = kwargs.pop("renderer")  # type: ignore[assignment]
    if "handler" in kwargs:
        handler = kwargs.pop("handler")  # type: ignore[assignment]
    if "theme" in kwargs:
        theme = kwargs.pop("theme")  # type: ignore[assignment]
    if "custom_templates" in kwargs:
        custom_templates = kwargs.pop("custom_templates")  # type: ignore[assignment]

    if collector is None and renderer is not None or collector is not None and renderer is None:
        raise ValueError("both 'collector' and 'renderer' must be provided")

    if collector is not None:
        warnings.warn(
            DeprecationWarning(
                "The BaseCollector class is deprecated, and passing an instance of it "
                "to your handler is deprecated as well. Instead, define the `collect` and `teardown` "
                "methods directly on your handler class."
            )
        )
        self.collector = collector
        self.collect = collector.collect  # type: ignore[assignment]
        self.teardown = collector.teardown  # type: ignore[assignment]

    if renderer is not None:
        if {handler, theme, custom_templates} != {None}:
            raise ValueError(
                "'handler', 'theme' and 'custom_templates' must all be None when providing a renderer instance"
            )
        warnings.warn(
            DeprecationWarning(
                "The BaseRenderer class is deprecated, and passing an instance of it "
                "to your handler is deprecated as well. Instead, define the `render` method "
                "directly on your handler class (as well as other methods and attributes like "
                "`get_templates_dir`, `get_anchors`, `update_env` and `fallback_theme`, `extra_css`)."
            )
        )
        self.renderer = renderer
        self.render = renderer.render  # type: ignore[assignment]
        self.get_templates_dir = renderer.get_templates_dir  # type: ignore[assignment]
        self.get_anchors = renderer.get_anchors  # type: ignore[assignment]
        self.do_convert_markdown = renderer.do_convert_markdown  # type: ignore[assignment]
        self.do_heading = renderer.do_heading  # type: ignore[assignment]
        self.get_headings = renderer.get_headings  # type: ignore[assignment]
        self.update_env = renderer.update_env  # type: ignore[assignment]
        self._update_env = renderer._update_env  # type: ignore[assignment]  # noqa: WPS437
        self.fallback_theme = renderer.fallback_theme
        self.extra_css = renderer.extra_css
        renderer.__class__.__init__(  # noqa: WPS609
            self,
            renderer._handler,  # noqa: WPS437
            renderer._theme,  # noqa: WPS437
            renderer._custom_templates,  # noqa: WPS437
        )
    else:
        if handler is None or theme is None:
            raise ValueError("'handler' and 'theme' cannot be None")
        BaseRenderer.__init__(self, handler, theme, custom_templates)  # noqa: WPS609

load_inventory(in_file, url, base_url=None, **kwargs) classmethod

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

Parameters:

Name	Type	Description	Default
in_file	BinaryIO	The binary file-like object to read the inventory from.	required
url	str	The URL that this file is being streamed from (used to guess base_url).	required
base_url	Optional[str]	The URL that this inventory's sub-paths are relative to.	None
**kwargs	Any	Ignore additional arguments passed from the config.	{}

Yields:

Type	Description
Iterator[tuple[str, str]]	Tuples of (item identifier, item URL).

Source code in mkdocstrings/handlers/base.py

@classmethod
def load_inventory(
    cls,
    in_file: BinaryIO,
    url: str,
    base_url: Optional[str] = None,
    **kwargs: Any,
) -> Iterator[tuple[str, str]]:
    """Yield items and their URLs from an inventory file streamed from `in_file`.

    Arguments:
        in_file: The binary file-like object to read the inventory from.
        url: The URL that this file is being streamed from (used to guess `base_url`).
        base_url: The URL that this inventory's sub-paths are relative to.
        **kwargs: Ignore additional arguments passed from the config.

    Yields:
        Tuples of (item identifier, item URL).
    """
    yield from ()

BaseRenderer(handler, theme, custom_templates=None)

The base renderer class.

Inherit from this class to implement a renderer.

You will have to implement the render method. You can also override the update_env method, to add more filters to the Jinja environment, making them available in your Jinja templates.

To define a fallback theme, add a fallback_theme class-variable. To add custom CSS, add an extra_css variable or create an 'style.css' file beside the templates.

If the given theme is not supported (it does not exist), it will look for a fallback_theme attribute in self to use as a fallback theme.

Parameters:

Name	Type	Description	Default
handler	str	The name of the handler.	required
theme	str	The name of theme to use.	required
custom_templates	Optional[str]	Directory containing custom templates.	None

Source code in mkdocstrings/handlers/base.py

def __init__(self, handler: str, theme: str, custom_templates: Optional[str] = None) -> None:
    """Initialize the object.

    If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute
    in `self` to use as a fallback theme.

    Arguments:
        handler: The name of the handler.
        theme: The name of theme to use.
        custom_templates: Directory containing custom templates.
    """
    paths = []

    # TODO: remove once BaseRenderer is merged into BaseHandler
    self._handler = handler
    self._theme = theme
    self._custom_templates = custom_templates

    themes_dir = self.get_templates_dir(handler)
    paths.append(themes_dir / theme)

    if self.fallback_theme and self.fallback_theme != theme:
        paths.append(themes_dir / self.fallback_theme)

    for path in paths:
        css_path = path / "style.css"
        if css_path.is_file():
            self.extra_css += "\n" + css_path.read_text(encoding="utf-8")  # noqa: WPS601
            break

    if custom_templates is not None:
        paths.insert(0, Path(custom_templates) / handler / theme)

    self.env = Environment(
        autoescape=True,
        loader=FileSystemLoader(paths),
        auto_reload=False,  # Editing a template in the middle of a build is not useful.
    )
    self.env.filters["any"] = do_any
    self.env.globals["log"] = get_template_logger()

    self._headings: List[Element] = []
    self._md: Markdown = None  # type: ignore  # To be populated in `update_env`.

do_convert_markdown(text, heading_level, html_id='', *, strip_paragraph=False)

Render Markdown text; for use inside templates.

Parameters:

Name	Type	Description	Default
text	str	The text to convert.	required
heading_level	int	The base heading level to start all Markdown headings from.	required
html_id	str	The HTML id of the element that's considered the parent of this element.	''
strip_paragraph	bool	Whether to exclude the tag from around the whole output.	False

Returns:

Type	Description
Markup	An HTML string.

Source code in mkdocstrings/handlers/base.py

def do_convert_markdown(
    self, text: str, heading_level: int, html_id: str = "", *, strip_paragraph: bool = False
) -> Markup:
    """Render Markdown text; for use inside templates.

    Arguments:
        text: The text to convert.
        heading_level: The base heading level to start all Markdown headings from.
        html_id: The HTML id of the element that's considered the parent of this element.
        strip_paragraph: Whether to exclude the <p> tag from around the whole output.

    Returns:
        An HTML string.
    """
    treeprocessors = self._md.treeprocessors
    treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level
    treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"
    treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph
    try:
        return Markup(self._md.convert(text))
    finally:
        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0
        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""
        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False
        self._md.reset()

do_heading(content, heading_level, *, role=None, hidden=False, toc_label=None, **attributes)

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

Parameters:

Name	Type	Description	Default
content	str	The HTML within the heading.	required
heading_level	int	The level of heading (e.g. 3 -> h3).	required
role	Optional[str]	An optional role for the object bound to this heading.	None
hidden	bool	If True, only register it for the table of contents, don't render anything.	False
toc_label	Optional[str]	The title to use in the table of contents ('data-toc-label' attribute).	None
**attributes	str	Any extra HTML attributes of the heading.	{}

Returns:

Type	Description
Markup	An HTML string.

Source code in mkdocstrings/handlers/base.py

def do_heading(
    self,
    content: str,
    heading_level: int,
    *,
    role: Optional[str] = None,
    hidden: bool = False,
    toc_label: Optional[str] = None,
    **attributes: str,
) -> Markup:
    """Render an HTML heading and register it for the table of contents. For use inside templates.

    Arguments:
        content: The HTML within the heading.
        heading_level: The level of heading (e.g. 3 -> `h3`).
        role: An optional role for the object bound to this heading.
        hidden: If True, only register it for the table of contents, don't render anything.
        toc_label: The title to use in the table of contents ('data-toc-label' attribute).
        **attributes: Any extra HTML attributes of the heading.

    Returns:
        An HTML string.
    """
    # First, produce the "fake" heading, for ToC only.
    el = Element(f"h{heading_level}", attributes)
    if toc_label is None:
        toc_label = content.unescape() if isinstance(el, Markup) else content  # type: ignore
    el.set("data-toc-label", toc_label)
    if role:
        el.set("data-role", role)
    self._headings.append(el)

    if hidden:
        return Markup('<a id="{0}"></a>').format(attributes["id"])

    # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
    # Start with a heading that has just attributes (no text), and add a placeholder into it.
    el = Element(f"h{heading_level}", attributes)
    el.append(Element("mkdocstrings-placeholder"))
    # Tell the 'toc' extension to make its additions if configured so.
    toc = self._md.treeprocessors["toc"]
    if toc.use_anchors:
        toc.add_anchor(el, attributes["id"])
    if toc.use_permalinks:
        toc.add_permalink(el, attributes["id"])

    # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
    # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
    # Now this HTML wrapper can be "filled" by replacing the placeholder.
    html_with_placeholder = tostring(el, encoding="unicode")
    assert (
        html_with_placeholder.count("<mkdocstrings-placeholder />") == 1
    ), f"Bug in mkdocstrings: failed to replace in {html_with_placeholder!r}"
    html = html_with_placeholder.replace("<mkdocstrings-placeholder />", content)
    return Markup(html)

get_anchors(data)

Return the possible identifiers (HTML anchors) for a collected item.

Parameters:

Name	Type	Description	Default
data	CollectorItem	The collected data.	required

Returns:

Type	Description
Sequence[str]	The HTML anchors (without '#'), or an empty tuple if this item doesn't have an anchor.

Source code in mkdocstrings/handlers/base.py

def get_anchors(self, data: CollectorItem) -> Sequence[str]:
    """Return the possible identifiers (HTML anchors) for a collected item.

    Arguments:
        data: The collected data.

    Returns:
        The HTML anchors (without '#'), or an empty tuple if this item doesn't have an anchor.
    """
    # TODO: remove this at some point
    try:
        return (self.get_anchor(data),)  # type: ignore
    except AttributeError:
        return ()

get_headings()

Return and clear the headings gathered so far.

Returns:

Type	Description
Sequence[Element]	A list of HTML elements.

Source code in mkdocstrings/handlers/base.py

def get_headings(self) -> Sequence[Element]:
    """Return and clear the headings gathered so far.

    Returns:
        A list of HTML elements.
    """
    result = list(self._headings)
    self._headings.clear()
    return result

get_templates_dir(handler)

Return the path to the handler's templates directory.

Override to customize how the templates directory is found.

Parameters:

Name	Type	Description	Default
handler	str	The name of the handler to get the templates directory of.	required

Raises:

Type	Description
FileNotFoundError	When the templates directory cannot be found.

Returns:

Type	Description
Path	The templates directory path.

Source code in mkdocstrings/handlers/base.py

def get_templates_dir(self, handler: str) -> Path:
    """Return the path to the handler's templates directory.

    Override to customize how the templates directory is found.

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

    Raises:
        FileNotFoundError: When the templates directory cannot be found.

    Returns:
        The templates directory path.
    """
    # Templates can be found in 2 different logical locations:
    # - in mkdocstrings_handlers/HANDLER/templates: our new migration target
    # - in mkdocstrings/templates/HANDLER: current situation, this should be avoided
    # These two other locations are forbidden:
    # - in mkdocstrings_handlers/templates/HANDLER: sub-namespace packages are too annoying to deal with
    # - in mkdocstrings/handlers/HANDLER/templates: not currently supported,
    #   and mkdocstrings will stop being a namespace

    with suppress(ModuleNotFoundError):  # TODO: catch at some point to warn about missing handlers
        import mkdocstrings_handlers

        for path in mkdocstrings_handlers.__path__:  # noqa: WPS609
            theme_path = Path(path, handler, "templates")
            if theme_path.exists():
                return theme_path

    # TODO: remove import and loop at some point,
    # as mkdocstrings will stop being a namespace package
    import mkdocstrings

    for path in mkdocstrings.__path__:  # noqa: WPS609,WPS440
        theme_path = Path(path, "templates", handler)
        if theme_path.exists():
            if handler != "python":
                warnings.warn(
                    "Exposing templates in the mkdocstrings.templates namespace is deprecated. "
                    "Put them in a templates folder inside your handler package instead.",
                    DeprecationWarning,
                )
            return theme_path

    raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")

render(data, config)

Render a template using provided data and configuration options.

Parameters:

Name	Type	Description	Default
data	CollectorItem	The collected data to render.	required
config	Mapping[str, Any]	The handler's configuraton options.	required

Returns:

Type	Description
str	The rendered template as HTML.

Source code in mkdocstrings/handlers/base.py

def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
    """Render a template using provided data and configuration options.

    Arguments:
        data: The collected data to render.
        config: The handler's configuraton options.

    Returns:
        The rendered template as HTML.
    """  # noqa: DAR202,DAR401
    raise NotImplementedError

update_env(md, config)

Update the Jinja environment.

Parameters:

Name	Type	Description	Default
md	Markdown	The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.	required
config	dict	Configuration options for mkdocs and mkdocstrings, read from mkdocs.yml. See the source code of mkdocstrings.plugin.MkdocstringsPlugin.on_config to see what's in this dictionary.	required

Source code in mkdocstrings/handlers/base.py

def update_env(self, md: Markdown, config: dict) -> None:  # noqa: W0613 (unused argument 'config')
    """Update the Jinja environment.

    Arguments:
        md: The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.
        config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
            of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
    """
    self._md = md
    self.env.filters["highlight"] = Highlighter(md).highlight
    self.env.filters["convert_markdown"] = self.do_convert_markdown
    self.env.filters["heading"] = self.do_heading

CollectionError

Bases: Exception

An exception raised when some collection of data failed.

Handlers(config)

A collection of handlers.

Do not instantiate this directly. The plugin will keep one instance of this for the purpose of caching. Use mkdocstrings.plugin.MkdocstringsPlugin.get_handler for convenient access.

Parameters:

Name	Type	Description	Default
config	dict	Configuration options for mkdocs and mkdocstrings, read from mkdocs.yml. See the source code of mkdocstrings.plugin.MkdocstringsPlugin.on_config to see what's in this dictionary.	required

Source code in mkdocstrings/handlers/base.py

def __init__(self, config: dict) -> None:
    """Initialize the object.

    Arguments:
        config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
            of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
    """
    self._config = config
    self._handlers: Dict[str, BaseHandler] = {}
    self.inventory: Inventory = Inventory(project=self._config["site_name"])

seen_handlers: Iterable[BaseHandler] property

Get the handlers that were encountered so far throughout the build.

Returns:

Type	Description
Iterable[BaseHandler]	An iterable of instances of BaseHandler
Iterable[BaseHandler]	(usable only to loop through it).

get_anchors(identifier)

Return the canonical HTML anchor for the identifier, if any of the seen handlers can collect it.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier (one that collect can accept).	required

Returns:

Type	Description
Sequence[str]	A tuple of strings - anchors without '#', or an empty tuple if there isn't any identifier familiar with it.

Source code in mkdocstrings/handlers/base.py

def get_anchors(self, identifier: str) -> Sequence[str]:
    """Return the canonical HTML anchor for the identifier, if any of the seen handlers can collect it.

    Arguments:
        identifier: The identifier (one that [collect][mkdocstrings.handlers.base.BaseCollector.collect] can accept).

    Returns:
        A tuple of strings - anchors without '#', or an empty tuple if there isn't any identifier familiar with it.
    """
    for handler in self._handlers.values():
        fallback_config = getattr(handler, "fallback_config", {})
        try:
            anchors = handler.get_anchors(handler.collect(identifier, fallback_config))
        except CollectionError:
            continue
        if anchors:
            return anchors
    return ()

get_handler(name, handler_config=None)

Get a handler thanks to its name.

This function dynamically imports a module named "mkdocstrings.handlers.NAME", calls its get_handler method to get an instance of a handler, and caches it in dictionary. It means that during one run (for each reload when serving, or once when building), a handler is instantiated only once, and reused for each "autodoc" instruction asking for it.

Parameters:

Name	Type	Description	Default
name	str	The name of the handler. Really, it's the name of the Python module holding it.	required
handler_config	Optional[dict]	Configuration passed to the handler.	None

Returns:

Type	Description
BaseHandler	An instance of a subclass of BaseHandler,
BaseHandler	as instantiated by the get_handler method of the handler's module.

Source code in mkdocstrings/handlers/base.py

def get_handler(self, name: str, handler_config: Optional[dict] = None) -> BaseHandler:
    """Get a handler thanks to its name.

    This function dynamically imports a module named "mkdocstrings.handlers.NAME", calls its
    `get_handler` method to get an instance of a handler, and caches it in dictionary.
    It means that during one run (for each reload when serving, or once when building),
    a handler is instantiated only once, and reused for each "autodoc" instruction asking for it.

    Arguments:
        name: The name of the handler. Really, it's the name of the Python module holding it.
        handler_config: Configuration passed to the handler.

    Returns:
        An instance of a subclass of [`BaseHandler`][mkdocstrings.handlers.base.BaseHandler],
        as instantiated by the `get_handler` method of the handler's module.
    """
    if name not in self._handlers:
        if handler_config is None:
            handler_config = self.get_handler_config(name)
        try:
            module = importlib.import_module(f"mkdocstrings_handlers.{name}")
        except ModuleNotFoundError:
            module = importlib.import_module(f"mkdocstrings.handlers.{name}")
            if name != "python":
                warnings.warn(
                    DeprecationWarning(
                        "Using the mkdocstrings.handlers namespace is deprecated. "
                        "Handlers must now use the mkdocstrings_handlers namespace."
                    )
                )
        self._handlers[name] = module.get_handler(
            theme=self._config["theme_name"],
            custom_templates=self._config["mkdocstrings"]["custom_templates"],
            config_file_path=self._config["config_file_path"],
            **handler_config,
        )
    return self._handlers[name]

get_handler_config(name)

Return the global configuration of the given handler.

Parameters:

Name	Type	Description	Default
name	str	The name of the handler to get the global configuration of.	required

Returns:

Type	Description
dict	The global configuration of the given handler. It can be an empty dictionary.

Source code in mkdocstrings/handlers/base.py

def get_handler_config(self, name: str) -> dict:
    """Return the global configuration of the given handler.

    Arguments:
        name: The name of the handler to get the global configuration of.

    Returns:
        The global configuration of the given handler. It can be an empty dictionary.
    """
    handlers = self._config["mkdocstrings"].get("handlers", {})
    if handlers:
        return handlers.get(name, {})
    return {}

get_handler_name(config)

Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.

Parameters:

Name	Type	Description	Default
config	dict	A configuration dictionary, obtained from YAML below the "autodoc" instruction.	required

Returns:

Type	Description
str	The name of the handler to use.

Source code in mkdocstrings/handlers/base.py

def get_handler_name(self, config: dict) -> str:
    """Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.

    Arguments:
        config: A configuration dictionary, obtained from YAML below the "autodoc" instruction.

    Returns:
        The name of the handler to use.
    """
    global_config = self._config["mkdocstrings"]
    if "handler" in config:
        return config["handler"]
    return global_config["default_handler"]

teardown()

Teardown all cached handlers and clear the cache.

Source code in mkdocstrings/handlers/base.py

def teardown(self) -> None:
    """Teardown all cached handlers and clear the cache."""
    for handler in self.seen_handlers:
        handler.teardown()
    self._handlers.clear()

ThemeNotSupported

Bases: Exception

An exception raised to tell a theme is not supported.

do_any(seq, attribute=None)

Check if at least one of the item in the sequence evaluates to true.

The any builtin as a filter for Jinja templates.

Parameters:

Name	Type	Description	Default
seq	Sequence	An iterable object.	required
attribute	str | None	The attribute name to use on each object of the iterable.	None

Returns:

Type	Description
bool	A boolean telling if any object of the iterable evaluated to True.

Source code in mkdocstrings/handlers/base.py

def do_any(seq: Sequence, attribute: str | None = None) -> bool:
    """Check if at least one of the item in the sequence evaluates to true.

    The `any` builtin as a filter for Jinja templates.

    Arguments:
        seq: An iterable object.
        attribute: The attribute name to use on each object of the iterable.

    Returns:
        A boolean telling if any object of the iterable evaluated to True.
    """
    if attribute is None:
        return any(seq)
    return any(_[attribute] for _ in seq)