python ¤

@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    if "per_style_options" in data:
        data["per_style_options"] = PerStyleOptions.from_data(**data["per_style_options"])
    return cls(**data)

def expand_identifier(self, identifier: str) -> str:
    """Expand an identifier.

    Parameters:
        identifier: The identifier to expand.

    Returns:
        The expanded identifier.
    """
    # Handle leading dots in the identifier:
    # - `.name` is a reference to the current object's `name` member.
    # - `..name` is a reference to the parent object's `name` member.
    # - etc.
    # TODO: We should update the protocol to allow modifying the title too.
    # In this case it would likely be better to strip dots from the title,
    # when it's not explicitly specified.
    if self.config.relative_crossrefs and identifier.startswith("."):  # type: ignore[attr-defined]
        identifier = identifier[1:]
        obj = self.current_object
        while identifier and identifier[0] == ".":
            identifier = identifier[1:]
            obj = obj.parent  # type: ignore[assignment]
        identifier = f"{obj.path}.{identifier}" if identifier else obj.path

    # We resolve the identifier to its full path.
    # For this we take out the first name, resolve it, and then append the rest.
    if self.config.scoped_crossrefs:  # type: ignore[attr-defined]
        if "." in identifier:
            identifier, remaining = identifier.split(".", 1)
        else:
            remaining = ""
        with suppress(Exception):
            identifier = self.current_object.resolve(identifier)
        if remaining:
            identifier = f"{identifier}.{remaining}"

    return identifier

def get_context(self) -> AutorefsHookInterface.Context:
    """Get the context for the current object.

    Returns:
        The context.
    """
    role = {
        "attribute": "data" if self.current_object.parent and self.current_object.parent.is_module else "attr",
        "class": "class",
        "function": "meth" if self.current_object.parent and self.current_object.parent.is_class else "func",
        "module": "mod",
    }.get(self.current_object.kind.value.lower(), "obj")
    origin = self.current_object.path
    try:
        filepath = self.current_object.docstring.parent.filepath  # type: ignore[union-attr]
        lineno = self.current_object.docstring.lineno or 0  # type: ignore[union-attr]
    except AttributeError:
        filepath = self.current_object.filepath
        lineno = 0

    return AutorefsHookInterface.Context(
        domain="py",
        role=role,
        origin=origin,
        filepath=str(filepath),
        lineno=lineno,
    )

@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    if "google" in data:
        data["google"] = GoogleStyleOptions(**data["google"])
    if "numpy" in data:
        data["numpy"] = NumpyStyleOptions(**data["numpy"])
    if "sphinx" in data:
        data["sphinx"] = SphinxStyleOptions(**data["sphinx"])
    return cls(**data)

@classmethod
def coerce(cls, **data: Any) -> MutableMapping[str, Any]:
    """Coerce data."""
    if "inventories" in data:
        data["inventories"] = [
            Inventory(url=inv) if isinstance(inv, str) else Inventory(**inv) for inv in data["inventories"]
        ]
    return data

@classmethod
def from_data(cls, **data: Any) -> Self:
    """Create an instance from a dictionary."""
    return cls(**cls.coerce(**data))

def collect(self, identifier: str, options: PythonOptions) -> CollectorItem:
    """Collect the documentation for the given identifier.

    Parameters:
        identifier: The identifier of the object to collect.
        options: The options to use for the collection.

    Returns:
        The collected item.
    """
    module_name = identifier.split(".", 1)[0]
    unknown_module = module_name not in self._modules_collection
    reapply = True
    if options == {}:
        if unknown_module:
            raise CollectionError("Not loading additional modules during fallback")
        options = self.get_options({})
        reapply = False

    parser_name = options.docstring_style
    parser = parser_name and Parser(parser_name)
    parser_options = options.docstring_options and asdict(options.docstring_options)

    if unknown_module:
        extensions = self.normalize_extension_paths(options.extensions)
        loader = GriffeLoader(
            extensions=load_extensions(*extensions),
            search_paths=self._paths,
            docstring_parser=parser,
            docstring_options=parser_options,  # type: ignore[arg-type]
            modules_collection=self._modules_collection,
            lines_collection=self._lines_collection,
            allow_inspection=options.allow_inspection,
            force_inspection=options.force_inspection,
        )
        try:
            for pre_loaded_module in options.preload_modules:
                if pre_loaded_module not in self._modules_collection:
                    loader.load(
                        pre_loaded_module,
                        try_relative_path=False,
                        find_stubs_package=options.find_stubs_package,
                    )
            loader.load(
                module_name,
                try_relative_path=False,
                find_stubs_package=options.find_stubs_package,
            )
        except ImportError as error:
            raise CollectionError(str(error)) from error
        unresolved, iterations = loader.resolve_aliases(
            implicit=False,
            external=self.config.load_external_modules,
        )
        if unresolved:
            _logger.debug(f"{len(unresolved)} aliases were still unresolved after {iterations} iterations")
            _logger.debug(f"Unresolved aliases: {', '.join(sorted(unresolved))}")

    try:
        doc_object = self._modules_collection[identifier]
    except KeyError as error:
        raise CollectionError(f"{identifier} could not be found") from error
    except AliasResolutionError as error:
        raise CollectionError(str(error)) from error

    if not unknown_module and reapply:
        with suppress(AliasResolutionError):
            if doc_object.docstring is not None:
                doc_object.docstring.parser = parser
                doc_object.docstring.parser_options = parser_options or {}

    return doc_object

def do_convert_markdown(
    self,
    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.

    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.
    """
    global _markdown_conversion_layer  # noqa: PLW0603
    _markdown_conversion_layer += 1
    treeprocessors = self.md.treeprocessors
    treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = heading_level  # type: ignore[attr-defined]
    treeprocessors[IdPrependingTreeprocessor.name].id_prefix = html_id and html_id + "--"  # type: ignore[attr-defined]
    treeprocessors[ParagraphStrippingTreeprocessor.name].strip = strip_paragraph  # type: ignore[attr-defined]
    if BacklinksTreeProcessor.name in treeprocessors:
        treeprocessors[BacklinksTreeProcessor.name].initial_id = html_id  # type: ignore[attr-defined]

    if autoref_hook:
        self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = autoref_hook  # type: ignore[attr-defined]

    try:
        return Markup(self.md.convert(text))
    finally:
        treeprocessors[HeadingShiftingTreeprocessor.name].shift_by = 0  # type: ignore[attr-defined]
        treeprocessors[IdPrependingTreeprocessor.name].id_prefix = ""  # type: ignore[attr-defined]
        treeprocessors[ParagraphStrippingTreeprocessor.name].strip = False  # type: ignore[attr-defined]
        if BacklinksTreeProcessor.name in treeprocessors:
            treeprocessors[BacklinksTreeProcessor.name].initial_id = None  # type: ignore[attr-defined]
        self.md.inlinePatterns[AutorefsInlineProcessor.name].hook = None  # type: ignore[attr-defined]
        self.md.reset()
        _markdown_conversion_layer -= 1

def do_heading(
    self,
    content: Markup,
    heading_level: int,
    *,
    role: str | None = None,
    hidden: bool = False,
    toc_label: str | None = None,
    skip_inventory: bool = False,
    **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).
        skip_inventory: Flag element to not be registered in the inventory (by setting a `data-skip-inventory` attribute).
        **attributes: Any extra HTML attributes of the heading.

    Returns:
        An HTML string.
    """
    # Produce a heading element that will be used later, in `AutoDocProcessor.run`, to:
    # - register it in the ToC: right now we're in the inner Markdown conversion layer,
    #   so we have to bubble up the information to the outer Markdown conversion layer,
    #   for the ToC extension to pick it up.
    # - register it in autorefs: right now we don't know what page is being rendered,
    #   so we bubble up the information again to where autorefs knows the page,
    #   and can correctly register the heading anchor (id) to its full URL.
    # - register it in the objects inventory: same as for autorefs,
    #   we don't know the page here, or the handler (and its domain),
    #   so we bubble up the information to where the mkdocstrings extension knows that.
    el = Element(f"h{heading_level}", attributes)
    if toc_label is None:
        toc_label = content.unescape() if isinstance(content, Markup) else content
    el.set("data-toc-label", toc_label)
    if skip_inventory:
        el.set("data-skip-inventory", "true")
    if role:
        el.set("data-role", role)
    if content:
        el.text = str(content).strip()
    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 inner 'toc' extension to make its additions if configured so.
    toc = cast("TocTreeprocessor", 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 (  # noqa: S101
        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)

def get_aliases(self, identifier: str) -> tuple[str, ...]:
    """Get the aliases for the given identifier.

    Parameters:
        identifier: The identifier to get the aliases for.

    Returns:
        The aliases.
    """
    if "(" in identifier:
        identifier, parameter = identifier.split("(", 1)
        parameter.removesuffix(")")
    else:
        parameter = ""
    try:
        data = self._modules_collection[identifier]
    except (KeyError, AliasResolutionError):
        return ()
    aliases = [data.path]
    try:
        for alias in [data.canonical_path, *data.aliases]:
            if alias not in aliases:
                aliases.append(alias)
    except AliasResolutionError:
        pass
    if parameter:
        return tuple(f"{alias}({parameter})" for alias in aliases)
    return tuple(aliases)

def get_extended_templates_dirs(self, handler: str) -> list[Path]:
    """Load template extensions for the given handler, return their templates directories.

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

    Returns:
        The extensions templates directories.
    """
    discovered_extensions = entry_points(group=f"mkdocstrings.{handler}.templates")
    return [extension.load()() for extension in discovered_extensions]

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

def get_inventory_urls(self) -> list[tuple[str, dict[str, Any]]]:
    """Return the URLs of the inventory files to download."""
    return [(inv.url, inv._config) for inv in self.config.inventories]

def get_options(self, local_options: Mapping[str, Any]) -> HandlerOptions:
    """Get combined default, global and local options.

    Arguments:
        local_options: The local options.

    Returns:
        The combined options.
    """
    # YORE: Bump 2: Remove block.
    local_extra, local_options = PythonOptions._extract_extra(local_options)  # type: ignore[arg-type]
    if local_extra:
        _warn_extra_options(local_extra.keys())  # type: ignore[arg-type]
    unknown_extra = self._global_extra | local_extra

    extra = {**self.global_options.get("extra", {}), **local_options.get("extra", {})}
    options = {**self.global_options, **local_options, "extra": extra}
    try:
        # YORE: Bump 2: Replace `opts =` with `return` within line.
        opts = PythonOptions.from_data(**options)
    except Exception as error:
        raise PluginError(f"Invalid options: {error}") from error

    # YORE: Bump 2: Remove block.
    for key, value in unknown_extra.items():
        object.__setattr__(opts, key, value)
    return opts

def get_templates_dir(self, handler: str | None = None) -> 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:
        ModuleNotFoundError: When no such handler is installed.
        FileNotFoundError: When the templates directory cannot be found.

    Returns:
        The templates directory path.
    """
    handler = handler or self.name
    try:
        import mkdocstrings_handlers  # noqa: PLC0415
    except ModuleNotFoundError as error:
        raise ModuleNotFoundError(f"Handler '{handler}' not found, is it installed?") from error

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

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

@staticmethod
def load_inventory(
    in_file: BinaryIO,
    url: str,
    base_url: str | None = None,
    domains: list[str] | None = None,
    **kwargs: Any,  # noqa: ARG004
) -> 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`][]).

    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.
        domains: A list of domain strings to filter the inventory by, when not passed, "py" will be used.
        **kwargs: Ignore additional arguments passed from the config.

    Yields:
        Tuples of (item identifier, item URL).
    """
    domains = domains or ["py"]
    if base_url is None:
        base_url = posixpath.dirname(url)

    for item in Inventory.parse_sphinx(in_file, domain_filter=domains).values():
        yield item.name, posixpath.join(base_url, item.uri)

def normalize_extension_paths(self, extensions: Sequence) -> list[str | dict[str, Any]]:
    """Resolve extension paths relative to config file.

    Parameters:
        extensions: The extensions (configuration) to normalize.

    Returns:
        The normalized extensions.
    """
    normalized: list[str | dict[str, Any]] = []

    for ext in extensions:
        if isinstance(ext, dict):
            pth, options = next(iter(ext.items()))
            pth = str(pth)
        else:
            pth = str(ext)
            options = None

        if pth.endswith(".py") or ".py:" in pth or "/" in pth or "\\" in pth:
            # This is a system path. Normalize it, make it absolute relative to config file path.
            pth = os.path.abspath(self.base_dir / pth)

        if options is not None:
            normalized.append({pth: options})
        else:
            normalized.append(pth)

    return normalized

def render(self, data: CollectorItem, options: PythonOptions, locale: str | None = None) -> str:
    """Render the collected data.

    Parameters:
        data: The collected data.
        options: The options to use for rendering.
        locale: The locale to use for rendering (default is "en").

    Returns:
        The rendered data (HTML).
    """
    template_name = rendering.do_get_template(self.env, data)
    template = self.env.get_template(template_name)

    return template.render(
        **{
            "config": options,
            data.kind.value.replace(" ", "_"): data,
            # Heading level is a "state" variable, that will change at each step
            # of the rendering recursion. Therefore, it's easier to use it as a plain value
            # than as an item in a dictionary.
            "heading_level": options.heading_level,
            "root": True,
            # YORE: Bump 2: Regex-replace ` or .+` with ` or "en",` within line.
            "locale": locale or self.config.locale,
        },
    )

def render_backlinks(self, backlinks: Mapping[str, Iterable[Backlink]], *, locale: str | None = None) -> str:  # noqa: ARG002
    """Render the backlinks.

    Parameters:
        backlinks: The backlinks to render.

    Returns:
        The rendered backlinks (HTML).
    """
    template = self.env.get_template("backlinks.html.jinja")
    verbose_type = {key: key.capitalize().replace("-by", " by") for key in backlinks.keys()}  # noqa: SIM118
    return template.render(
        backlinks=backlinks,
        config=self.get_options({}),
        verbose_type=verbose_type,
        default_crumb=BacklinkCrumb(title="", url=""),
    )

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

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

def update_env(self, config: Any) -> None:  # noqa: ARG002
    """Update the Jinja environment with custom filters and tests.

    Parameters:
        config: The SSG configuration.
    """
    self.env.trim_blocks = True
    self.env.lstrip_blocks = True
    self.env.keep_trailing_newline = False
    self.env.filters["split_path"] = rendering.do_split_path
    self.env.filters["crossref"] = rendering.do_crossref
    self.env.filters["multi_crossref"] = rendering.do_multi_crossref
    self.env.filters["order_members"] = rendering.do_order_members
    self.env.filters["format_code"] = rendering.do_format_code
    self.env.filters["format_signature"] = rendering.do_format_signature
    self.env.filters["format_attribute"] = rendering.do_format_attribute
    self.env.filters["format_type_alias"] = rendering.do_format_type_alias
    self.env.filters["filter_objects"] = rendering.do_filter_objects
    self.env.filters["stash_crossref"] = rendering.do_stash_crossref
    self.env.filters["get_template"] = rendering.do_get_template
    self.env.filters["as_attributes_section"] = rendering.do_as_attributes_section
    self.env.filters["as_functions_section"] = rendering.do_as_functions_section
    self.env.filters["as_classes_section"] = rendering.do_as_classes_section
    self.env.filters["as_type_aliases_section"] = rendering.do_as_type_aliases_section
    self.env.filters["as_modules_section"] = rendering.do_as_modules_section
    self.env.filters["backlink_tree"] = rendering.do_backlink_tree
    self.env.globals["AutorefsHook"] = rendering.AutorefsHook
    self.env.tests["existing_template"] = lambda template_name: template_name in self.env.list_templates()