Skip to content

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
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
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
339
340
341
342
343
344
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
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
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
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
@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
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
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
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
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
278
279
280
281
282
283
284
285
286
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
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
122
123
124
125
126
127
128
129
130
131
132
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
288
289
290
291
292
293
294
295
296
297
298
299
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
508
509
510
511
512
513
514
515
516
517
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
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
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
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
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
552
553
554
555
556
557
558
559
560
561
562
563
564
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
538
539
540
541
542
543
544
545
546
547
548
549
550
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
614
615
616
617
618
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
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
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)