Coverage for src/mkdocstrings/handlers/base.py: 78.83%
174 statements
« prev ^ index » next coverage.py v7.6.2, created at 2024-10-12 18:59 +0200
1"""Base module for handlers.
3This module contains the base classes for implementing handlers.
4"""
6from __future__ import annotations
8import importlib
9import sys
10from pathlib import Path
11from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, cast
12from xml.etree.ElementTree import Element, tostring
14from jinja2 import Environment, FileSystemLoader
15from markdown import Markdown
16from markdown.extensions.toc import TocTreeprocessor
17from markupsafe import Markup
18from mkdocs_autorefs.references import AutorefsInlineProcessor
20from mkdocstrings.handlers.rendering import (
21 HeadingShiftingTreeprocessor,
22 Highlighter,
23 IdPrependingTreeprocessor,
24 MkdocstringsInnerExtension,
25 ParagraphStrippingTreeprocessor,
26)
27from mkdocstrings.inventory import Inventory
28from mkdocstrings.loggers import get_template_logger
30# TODO: remove once support for Python 3.9 is dropped
31if sys.version_info < (3, 10):
32 from importlib_metadata import entry_points
33else:
34 from importlib.metadata import entry_points
36if TYPE_CHECKING:
37 from collections.abc import Iterable, Iterator, Mapping, MutableMapping, Sequence
39 from mkdocs_autorefs.references import AutorefsHookInterface
41CollectorItem = Any
44class CollectionError(Exception):
45 """An exception raised when some collection of data failed."""
48class ThemeNotSupported(Exception): # noqa: N818
49 """An exception raised to tell a theme is not supported."""
52def do_any(seq: Sequence, attribute: str | None = None) -> bool:
53 """Check if at least one of the item in the sequence evaluates to true.
55 The `any` builtin as a filter for Jinja templates.
57 Arguments:
58 seq: An iterable object.
59 attribute: The attribute name to use on each object of the iterable.
61 Returns:
62 A boolean telling if any object of the iterable evaluated to True.
63 """
64 if attribute is None:
65 return any(seq)
66 return any(_[attribute] for _ in seq)
69class BaseHandler:
70 """The base handler class.
72 Inherit from this class to implement a handler.
74 You will have to implement the `collect` and `render` methods.
75 You can also implement the `teardown` method,
76 and override the `update_env` method, to add more filters to the Jinja environment,
77 making them available in your Jinja templates.
79 To define a fallback theme, add a `fallback_theme` class-variable.
80 To add custom CSS, add an `extra_css` variable or create an 'style.css' file beside the templates.
81 """
83 # TODO: Make name mandatory?
84 name: str = ""
85 """The handler's name, for example "python"."""
86 domain: str = "default"
87 """The handler's domain, used to register objects in the inventory, for example "py"."""
88 enable_inventory: bool = False
89 """Whether the inventory creation is enabled."""
90 fallback_config: ClassVar[dict] = {}
91 """Fallback configuration when searching anchors for identifiers."""
92 fallback_theme: str = ""
93 """Fallback theme to use when a template isn't found in the configured theme."""
94 extra_css = ""
95 """Extra CSS."""
97 def __init__(self, handler: str, theme: str, custom_templates: str | None = None) -> None:
98 """Initialize the object.
100 If the given theme is not supported (it does not exist), it will look for a `fallback_theme` attribute
101 in `self` to use as a fallback theme.
103 Arguments:
104 handler: The name of the handler.
105 theme: The name of theme to use.
106 custom_templates: Directory containing custom templates.
107 """
108 paths = []
110 # add selected theme templates
111 themes_dir = self.get_templates_dir(handler)
112 paths.append(themes_dir / theme)
114 # add extended theme templates
115 extended_templates_dirs = self.get_extended_templates_dirs(handler)
116 for templates_dir in extended_templates_dirs: 116 ↛ 117line 116 didn't jump to line 117 because the loop on line 116 never started
117 paths.append(templates_dir / theme)
119 # add fallback theme templates
120 if self.fallback_theme and self.fallback_theme != theme: 120 ↛ 127line 120 didn't jump to line 127 because the condition on line 120 was always true
121 paths.append(themes_dir / self.fallback_theme)
123 # add fallback theme of extended templates
124 for templates_dir in extended_templates_dirs: 124 ↛ 125line 124 didn't jump to line 125 because the loop on line 124 never started
125 paths.append(templates_dir / self.fallback_theme)
127 for path in paths: 127 ↛ 133line 127 didn't jump to line 133 because the loop on line 127 didn't complete
128 css_path = path / "style.css"
129 if css_path.is_file():
130 self.extra_css += "\n" + css_path.read_text(encoding="utf-8")
131 break
133 if custom_templates is not None: 133 ↛ 134line 133 didn't jump to line 134 because the condition on line 133 was never true
134 paths.insert(0, Path(custom_templates) / handler / theme)
136 self.env = Environment(
137 autoescape=True,
138 loader=FileSystemLoader(paths),
139 auto_reload=False, # Editing a template in the middle of a build is not useful.
140 )
141 self.env.filters["any"] = do_any
142 self.env.globals["log"] = get_template_logger(self.name)
144 self._headings: list[Element] = []
145 self._md: Markdown = None # type: ignore[assignment] # To be populated in `update_env`.
147 @classmethod
148 def load_inventory(
149 cls,
150 in_file: BinaryIO, # noqa: ARG003
151 url: str, # noqa: ARG003
152 base_url: str | None = None, # noqa: ARG003
153 **kwargs: Any, # noqa: ARG003
154 ) -> Iterator[tuple[str, str]]:
155 """Yield items and their URLs from an inventory file streamed from `in_file`.
157 Arguments:
158 in_file: The binary file-like object to read the inventory from.
159 url: The URL that this file is being streamed from (used to guess `base_url`).
160 base_url: The URL that this inventory's sub-paths are relative to.
161 **kwargs: Ignore additional arguments passed from the config.
163 Yields:
164 Tuples of (item identifier, item URL).
165 """
166 yield from ()
168 def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:
169 """Collect data given an identifier and user configuration.
171 In the implementation, you typically call a subprocess that returns JSON, and load that JSON again into
172 a Python dictionary for example, though the implementation is completely free.
174 Arguments:
175 identifier: An identifier for which to collect data. For example, in Python,
176 it would be 'mkdocstrings.handlers' to collect documentation about the handlers module.
177 It can be anything that you can feed to the tool of your choice.
178 config: The handler's configuration options.
180 Returns:
181 Anything you want, as long as you can feed it to the handler's `render` method.
182 """
183 raise NotImplementedError
185 def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:
186 """Render a template using provided data and configuration options.
188 Arguments:
189 data: The collected data to render.
190 config: The handler's configuration options.
192 Returns:
193 The rendered template as HTML.
194 """
195 raise NotImplementedError
197 def teardown(self) -> None:
198 """Teardown the handler.
200 This method should be implemented to, for example, terminate a subprocess
201 that was started when creating the handler instance.
202 """
204 def get_templates_dir(self, handler: str | None = None) -> Path:
205 """Return the path to the handler's templates directory.
207 Override to customize how the templates directory is found.
209 Arguments:
210 handler: The name of the handler to get the templates directory of.
212 Raises:
213 ModuleNotFoundError: When no such handler is installed.
214 FileNotFoundError: When the templates directory cannot be found.
216 Returns:
217 The templates directory path.
218 """
219 handler = handler or self.name
220 try:
221 import mkdocstrings_handlers
222 except ModuleNotFoundError as error:
223 raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error
225 for path in mkdocstrings_handlers.__path__: 225 ↛ 230line 225 didn't jump to line 230 because the loop on line 225 didn't complete
226 theme_path = Path(path, handler, "templates")
227 if theme_path.exists(): 227 ↛ 225line 227 didn't jump to line 225 because the condition on line 227 was always true
228 return theme_path
230 raise FileNotFoundError(f"Can't find 'templates' folder for handler '{handler}'")
232 def get_extended_templates_dirs(self, handler: str) -> list[Path]:
233 """Load template extensions for the given handler, return their templates directories.
235 Arguments:
236 handler: The name of the handler to get the extended templates directory of.
238 Returns:
239 The extensions templates directories.
240 """
241 discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
242 return [extension.load()() for extension in discovered_extensions]
244 def get_anchors(self, data: CollectorItem) -> tuple[str, ...]: # noqa: ARG002
245 """Return the possible identifiers (HTML anchors) for a collected item.
247 Arguments:
248 data: The collected data.
250 Returns:
251 The HTML anchors (without '#'), or an empty tuple if this item doesn't have an anchor.
252 """
253 return ()
255 def do_convert_markdown(
256 self,
257 text: str,
258 heading_level: int,
259 html_id: str = "",
260 *,
261 strip_paragraph: bool = False,
262 autoref_hook: AutorefsHookInterface | None = None,
263 ) -> Markup:
264 """Render Markdown text; for use inside templates.
266 Arguments:
267 text: The text to convert.
268 heading_level: The base heading level to start all Markdown headings from.
269 html_id: The HTML id of the element that's considered the parent of this element.
270 strip_paragraph: Whether to exclude the <p> tag from around the whole output.
272 Returns:
273 An HTML string.
274 """
275 treeprocessors = self._md.treeprocessors
276 treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level # type: ignore[attr-defined]
277 treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--" # type: ignore[attr-defined]
278 treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph # type: ignore[attr-defined]
280 if autoref_hook: 280 ↛ 283line 280 didn't jump to line 283 because the condition on line 280 was always true
281 self._md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook # type: ignore[attr-defined]
283 try:
284 return Markup(self._md.convert(text))
285 finally:
286 treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0 # type: ignore[attr-defined]
287 treeprocessors[IdPrependingTreeprocessor.name].id_prefix = "" # type: ignore[attr-defined]
288 treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False # type: ignore[attr-defined]
289 self._md.inlinePatterns[AutorefsInlineProcessor.name].hook = None # type: ignore[attr-defined]
290 self._md.reset()
292 def do_heading(
293 self,
294 content: Markup,
295 heading_level: int,
296 *,
297 role: str | None = None,
298 hidden: bool = False,
299 toc_label: str | None = None,
300 **attributes: str,
301 ) -> Markup:
302 """Render an HTML heading and register it for the table of contents. For use inside templates.
304 Arguments:
305 content: The HTML within the heading.
306 heading_level: The level of heading (e.g. 3 -> `h3`).
307 role: An optional role for the object bound to this heading.
308 hidden: If True, only register it for the table of contents, don't render anything.
309 toc_label: The title to use in the table of contents ('data-toc-label' attribute).
310 **attributes: Any extra HTML attributes of the heading.
312 Returns:
313 An HTML string.
314 """
315 # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
316 # - register it in the ToC: right now we're in the inner Markdown conversion layer,
317 # so we have to bubble up the information to the outer Markdown conversion layer,
318 # for the ToC extension to pick it up.
319 # - register it in autorefs: right now we don't know what page is being rendered,
320 # so we bubble up the information again to where autorefs knows the page,
321 # and can correctly register the heading anchor (id) to its full URL.
322 # - register it in the objects inventory: same as for autorefs,
323 # we don't know the page here, or the handler (and its domain),
324 # so we bubble up the information to where the mkdocstrings extension knows that.
325 el = Element(f"h{heading_level}", attributes)
326 if toc_label is None: 326 ↛ 327line 326 didn't jump to line 327 because the condition on line 326 was never true
327 toc_label = content.unescape() if isinstance(content, Markup) else content
328 el.set("data-toc-label", toc_label)
329 if role: 329 ↛ 331line 329 didn't jump to line 331 because the condition on line 329 was always true
330 el.set("data-role", role)
331 self._headings.append(el)
333 if hidden:
334 return Markup('<a id="{0}"></a>').format(attributes["id"])
336 # Now produce the actual HTML to be rendered. The goal is to wrap the HTML content into a heading.
337 # Start with a heading that has just attributes (no text), and add a placeholder into it.
338 el = Element(f"h{heading_level}", attributes)
339 el.append(Element("mkdocstrings-placeholder"))
340 # Tell the inner 'toc' extension to make its additions if configured so.
341 toc = cast(TocTreeprocessor, self._md.treeprocessors["toc"])
342 if toc.use_anchors: 342 ↛ 343line 342 didn't jump to line 343 because the condition on line 342 was never true
343 toc.add_anchor(el, attributes["id"])
344 if toc.use_permalinks: 344 ↛ 345line 344 didn't jump to line 345 because the condition on line 344 was never true
345 toc.add_permalink(el, attributes["id"])
347 # The content we received is HTML, so it can't just be inserted into the tree. We had marked the middle
348 # of the heading with a placeholder that can never occur (text can't directly contain angle brackets).
349 # Now this HTML wrapper can be "filled" by replacing the placeholder.
350 html_with_placeholder = tostring(el, encoding="unicode")
351 assert ( # noqa: S101
352 html_with_placeholder.count("<mkdocstrings-placeholder />") == 1
353 ), f"Bug in mkdocstrings: failed to replace in {html_with_placeholder!r}"
354 html = html_with_placeholder.replace("<mkdocstrings-placeholder />", content)
355 return Markup(html)
357 def get_headings(self) -> Sequence[Element]:
358 """Return and clear the headings gathered so far.
360 Returns:
361 A list of HTML elements.
362 """
363 result = list(self._headings)
364 self._headings.clear()
365 return result
367 def update_env(self, md: Markdown, config: dict) -> None: # noqa: ARG002
368 """Update the Jinja environment.
370 Arguments:
371 md: The Markdown instance. Useful to add functions able to convert Markdown into the environment filters.
372 config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
373 of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
374 """
375 self._md = md
376 self.env.filters["highlight"] = Highlighter(md).highlight
377 self.env.filters["convert_markdown"] = self.do_convert_markdown
378 self.env.filters["heading"] = self.do_heading
380 def _update_env(self, md: Markdown, config: dict) -> None:
381 """Update our handler to point to our configured Markdown instance, grabbing some of the config from `md`."""
382 extensions = config["mdx"] + [MkdocstringsInnerExtension(self._headings)]
384 new_md = Markdown(extensions=extensions, extension_configs=config["mdx_configs"])
385 # MkDocs adds its own (required) extension that's not part of the config. Propagate it.
386 if "relpath" in md.treeprocessors: 386 ↛ 387line 386 didn't jump to line 387 because the condition on line 386 was never true
387 new_md.treeprocessors.register(md.treeprocessors["relpath"], "relpath", priority=0)
389 self.update_env(new_md, config)
392class Handlers:
393 """A collection of handlers.
395 Do not instantiate this directly. [The plugin][mkdocstrings.plugin.MkdocstringsPlugin] will keep one instance of
396 this for the purpose of caching. Use [mkdocstrings.plugin.MkdocstringsPlugin.get_handler][] for convenient access.
397 """
399 def __init__(self, config: dict) -> None:
400 """Initialize the object.
402 Arguments:
403 config: Configuration options for `mkdocs` and `mkdocstrings`, read from `mkdocs.yml`. See the source code
404 of [mkdocstrings.plugin.MkdocstringsPlugin.on_config][] to see what's in this dictionary.
405 """
406 self._config = config
407 self._handlers: dict[str, BaseHandler] = {}
408 self.inventory: Inventory = Inventory(project=self._config["mkdocs"]["site_name"])
410 def get_anchors(self, identifier: str) -> tuple[str, ...]:
411 """Return the canonical HTML anchor for the identifier, if any of the seen handlers can collect it.
413 Arguments:
414 identifier: The identifier (one that [collect][mkdocstrings.handlers.base.BaseHandler.collect] can accept).
416 Returns:
417 A tuple of strings - anchors without '#', or an empty tuple if there isn't any identifier familiar with it.
418 """
419 for handler in self._handlers.values():
420 fallback_config = getattr(handler, "fallback_config", {})
421 try:
422 anchors = handler.get_anchors(handler.collect(identifier, fallback_config))
423 except CollectionError:
424 continue
425 if anchors:
426 return anchors
427 return ()
429 def get_handler_name(self, config: dict) -> str:
430 """Return the handler name defined in an "autodoc" instruction YAML configuration, or the global default handler.
432 Arguments:
433 config: A configuration dictionary, obtained from YAML below the "autodoc" instruction.
435 Returns:
436 The name of the handler to use.
437 """
438 global_config = self._config["mkdocstrings"]
439 if "handler" in config:
440 return config["handler"]
441 return global_config["default_handler"]
443 def get_handler_config(self, name: str) -> dict:
444 """Return the global configuration of the given handler.
446 Arguments:
447 name: The name of the handler to get the global configuration of.
449 Returns:
450 The global configuration of the given handler. It can be an empty dictionary.
451 """
452 handlers = self._config["mkdocstrings"].get("handlers", {})
453 if handlers: 453 ↛ 454line 453 didn't jump to line 454 because the condition on line 453 was never true
454 return handlers.get(name, {})
455 return {}
457 def get_handler(self, name: str, handler_config: dict | None = None) -> BaseHandler:
458 """Get a handler thanks to its name.
460 This function dynamically imports a module named "mkdocstrings.handlers.NAME", calls its
461 `get_handler` method to get an instance of a handler, and caches it in dictionary.
462 It means that during one run (for each reload when serving, or once when building),
463 a handler is instantiated only once, and reused for each "autodoc" instruction asking for it.
465 Arguments:
466 name: The name of the handler. Really, it's the name of the Python module holding it.
467 handler_config: Configuration passed to the handler.
469 Returns:
470 An instance of a subclass of [`BaseHandler`][mkdocstrings.handlers.base.BaseHandler],
471 as instantiated by the `get_handler` method of the handler's module.
472 """
473 if name not in self._handlers:
474 if handler_config is None:
475 handler_config = self.get_handler_config(name)
476 handler_config.update(self._config)
477 module = importlib.import_module(f"mkdocstrings_handlers.{name}")
478 self._handlers[name] = module.get_handler(
479 theme=self._config["theme_name"],
480 custom_templates=self._config["mkdocstrings"]["custom_templates"],
481 config_file_path=self._config["mkdocs"]["config_file_path"],
482 **handler_config,
483 )
484 return self._handlers[name]
486 @property
487 def seen_handlers(self) -> Iterable[BaseHandler]:
488 """Get the handlers that were encountered so far throughout the build.
490 Returns:
491 An iterable of instances of [`BaseHandler`][mkdocstrings.handlers.base.BaseHandler]
492 (usable only to loop through it).
493 """
494 return self._handlers.values()
496 def teardown(self) -> None:
497 """Teardown all cached handlers and clear the cache."""
498 for handler in self.seen_handlers:
499 handler.teardown()
500 self._handlers.clear()