zensical 0.0.9__cp310-abi3-musllinux_1_2_i686.whl → 0.0.17__cp310-abi3-musllinux_1_2_i686.whl

zensical/extensions/__init__.py

@@ -1,7 +1,7 @@
-# Copyright (c) 2025 Zensical and contributors
+# Copyright (c) 2025-2026 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under DCO
+# All contributions are certified under the DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/emoji.py

@@ -1,7 +1,7 @@
-# Copyright (c) 2025 Zensical and contributors
+# Copyright (c) 2025-2026 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under DCO
+# All contributions are certified under the DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -26,21 +26,22 @@ from __future__ import annotations
 import codecs
 import functools
 import os
-
 from glob import iglob
-from markdown import Markdown
-from pymdownx import emoji, twemoji_db
+from typing import TYPE_CHECKING
 from xml.etree.ElementTree import Element
 
+from pymdownx import emoji, twemoji_db
+
+if TYPE_CHECKING:
+    from markdown import Markdown
+
 # -----------------------------------------------------------------------------
 # Functions
 # -----------------------------------------------------------------------------
 
 
-def twemoji(options: object, md: Markdown):
-    """
-    Create twemoji index.
-    """
+def twemoji(options: dict, md: Markdown) -> dict:  # noqa: ARG001
+    """Create twemoji index."""
     paths = options.get("custom_icons", [])[:]
     return _load_twemoji_index(tuple(paths))
 
@@ -53,14 +54,12 @@ def to_svg(
     alt: str,
     title: str,
     category: str,
-    options: object,
+    options: dict,
     md: Markdown,
-):
-    """
-    Load icon.
-    """
+) -> Element[str]:
+    """Load icon."""
     if not uc:
-        icons = md.inlinePatterns["emoji"].emoji_index["emoji"]
+        icons = md.inlinePatterns["emoji"].emoji_index["emoji"]  # type: ignore[attr-defined]
 
         # Create and return element to host icon
         el = Element("span", {"class": options.get("classes", index)})
@@ -78,20 +77,16 @@ def to_svg(
 # -----------------------------------------------------------------------------
 
 
-@functools.lru_cache(maxsize=None)
-def _load(file: str):
-    """
-    Load icon from file.
-    """
+@functools.cache
+def _load(file: str) -> str:
+    """Load icon from file."""
     with codecs.open(file, encoding="utf-8") as f:
         return f.read()
 
 
-@functools.lru_cache(maxsize=None)
-def _load_twemoji_index(paths):
-    """
-    Load twemoji index and add icons.
-    """
+@functools.cache
+def _load_twemoji_index(paths: tuple[str, ...]) -> dict:
+    """Load twemoji index and add icons."""
     index = {
         "name": "twemoji",
         "emoji": twemoji_db.emoji,
@@ -106,8 +101,8 @@ def _load_twemoji_index(paths):
 
         # Index icons provided by the theme and via custom icons
         glob = os.path.join(base, "**", "*.svg")
-        glob = iglob(os.path.normpath(glob), recursive=True)
-        for file in glob:
+        svgs = iglob(os.path.normpath(glob), recursive=True)
+        for file in svgs:
             icon = file[len(base) + 1 : -4].replace(os.path.sep, "-")
 
             # Add icon to index

zensical/extensions/links.py

@@ -1,7 +1,7 @@
-# Copyright (c) 2025 Zensical and contributors
+# Copyright (c) 2025-2026 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under DCO
+# All contributions are certified under the DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -23,12 +23,17 @@
 
 from __future__ import annotations
 
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
 from markdown import Extension, Markdown
 from markdown.treeprocessors import Treeprocessor
 from markdown.util import AMP_SUBSTITUTE
-from pathlib import PurePosixPath
-from xml.etree.ElementTree import Element
-from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from xml.etree.ElementTree import Element
+
 
 # -----------------------------------------------------------------------------
 # Classes
@@ -36,8 +41,7 @@ from urllib.parse import urlparse
 
 
 class LinksProcessor(Treeprocessor):
-    """
-    Tree processor to replace links in Markdown with URLs.
+    """Tree processor to replace links in Markdown with URLs.
 
     Note that we view this as a bandaid until we can do processing on proper
     HTML ASTs in Rust. In the meantime, we just replace them as we find them.
@@ -50,7 +54,7 @@ class LinksProcessor(Treeprocessor):
         self.path = path  # Current page
         self.use_directory_urls = use_directory_urls
 
-    def run(self, root: Element):
+    def run(self, root: Element) -> None:
         # Now, we determine whether the current page is an index page, as we
         # must apply slightly different handling in case of directory URLs
         current_is_index = get_name(self.path) in ("index.md", "README.md")
@@ -64,7 +68,7 @@ class LinksProcessor(Treeprocessor):
             # Extract value - Python Markdown does some weird stuff where it
             # replaces mailto: links with double encoded entities. MkDocs just
             # skips if it detects that, so we do the same.
-            value = el.get(key)
+            value = el.get(key, "")
             if AMP_SUBSTITUTE in value:
                 continue
 
@@ -101,21 +105,15 @@ class LinksProcessor(Treeprocessor):
 
 
 class LinksExtension(Extension):
-    """
-    A Markdown extension to resolve links to other Markdown files.
-    """
+    """A Markdown extension to resolve links to other Markdown files."""
 
     def __init__(self, path: str, use_directory_urls: bool):
-        """
-        Initialize the extension.
-        """
+        """Initialize the extension."""
         self.path = path  # Current page
         self.use_directory_urls = use_directory_urls
 
-    def extendMarkdown(self, md: Markdown):
-        """
-        Register Markdown extension.
-        """
+    def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802
+        """Register Markdown extension."""
         md.registerExtension(self)
 
         # Create and register treeprocessor - we use the same priority as the
@@ -123,7 +121,7 @@ class LinksExtension(Extension):
         # after our treeprocessor, so we can check the original Markdown URIs
         # before they are resolved to URLs.
         processor = LinksProcessor(md, self.path, self.use_directory_urls)
-        md.treeprocessors.register(processor, "relpath", 0)
+        md.treeprocessors.register(processor, "zrelpath", 0)
 
 
 # -----------------------------------------------------------------------------
@@ -132,8 +130,6 @@ class LinksExtension(Extension):
 
 
 def get_name(path: str) -> str:
-    """
-    Get the name of a file from a given path.
-    """
-    path = PurePosixPath(path)
-    return path.name
+    """Get the name of a file from a given path."""
+    pure_path = PurePosixPath(path)
+    return pure_path.name

zensical/extensions/preview.py

@@ -1,7 +1,7 @@
-# Copyright (c) 2025 Zensical and contributors
+# Copyright (c) 2025-2026 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under DCO
+# All contributions are certified under the DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -24,14 +24,17 @@
 from __future__ import annotations
 
 import posixpath
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
 
 from markdown import Extension, Markdown
 from markdown.treeprocessors import Treeprocessor
-from urllib.parse import urlparse
-from xml.etree.ElementTree import Element
 
-from .links import LinksProcessor
-from .utilities.filter import Filter
+from zensical.extensions.links import LinksProcessor
+from zensical.extensions.utilities.filter import Filter
+
+if TYPE_CHECKING:
+    from xml.etree.ElementTree import Element
 
 # -----------------------------------------------------------------------------
 # Classes
@@ -39,25 +42,20 @@ from .utilities.filter import Filter
 
 
 class PreviewProcessor(Treeprocessor):
-    """
-    A Markdown treeprocessor to enable instant previews on links.
+    """A Markdown treeprocessor to enable instant previews on links.
 
     Note that this treeprocessor is dependent on the `links` treeprocessor
     registered programmatically before rendering a page.
     """
 
     def __init__(self, md: Markdown, config: dict):
-        """
-        Initialize the treeprocessor.
-        """
+        """Initialize the treeprocessor."""
         super().__init__(md)
         self.config = config
 
-    def run(self, root: Element):
-        """
-        Run the treeprocessor.
-        """
-        at = self.md.treeprocessors.get_index_for_name("relpath")
+    def run(self, root: Element) -> None:
+        """Run the treeprocessor."""
+        at = self.md.treeprocessors.get_index_for_name("zrelpath")
 
         # Hack: Python Markdown has no notion of where it is, i.e., which file
         # is being processed. This seems to be a deliberate design decision, as
@@ -84,9 +82,10 @@ class PreviewProcessor(Treeprocessor):
         # Walk through all configurations - @todo refactor so that we don't
         # iterate multiple times over the same elements
         for configuration in configurations:
-            if not configuration.get("sources"):
-                if not configuration.get("targets"):
-                    continue
+            if not configuration.get("sources") and not configuration.get(
+                "targets"
+            ):
+                continue
 
             # Skip if page should not be considered
             filter = get_filter(configuration, "sources")
@@ -123,8 +122,7 @@ class PreviewProcessor(Treeprocessor):
 
 
 class PreviewExtension(Extension):
-    """
-    A Markdown extension to enable instant previews on links.
+    """A Markdown extension to enable instant previews on links.
 
     This extensions allows to automatically add the `data-preview` attribute to
     internal links matching specific criteria, so Material for MkDocs renders a
@@ -132,10 +130,8 @@ class PreviewExtension(Extension):
     add previews to links in a programmatic way.
     """
 
-    def __init__(self, *args, **kwargs):
-        """
-        Initialize the extension.
-        """
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the extension."""
         self.config = {
             "configurations": [[], "Filter configurations"],
             "sources": [{}, "Link sources"],
@@ -143,10 +139,8 @@ class PreviewExtension(Extension):
         }
         super().__init__(*args, **kwargs)
 
-    def extendMarkdown(self, md: Markdown):
-        """
-        Register Markdown extension.
-        """
+    def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802
+        """Register Markdown extension."""
         md.registerExtension(self)
 
         # Create and register treeprocessor - we use the same priority as the
@@ -162,17 +156,13 @@ class PreviewExtension(Extension):
 # -----------------------------------------------------------------------------
 
 
-def get_filter(settings: dict, key: str):
-    """
-    Get file filter from settings.
-    """
-    return Filter(config=settings.get(key))  # type: ignore
+def get_filter(settings: dict, key: str) -> Filter:
+    """Get file filter from settings."""
+    return Filter(config=settings.get(key, {}))
 
 
 def resolve(processor_path: str, url_path: str) -> str:
-    """
-    Resolve a relative URL path against the processor path.
-    """
+    """Resolve a relative URL path against the processor path."""
     # Remove the file name from the processor path to get the directory
     base_path = posixpath.dirname(processor_path)
 
@@ -194,8 +184,6 @@ def resolve(processor_path: str, url_path: str) -> str:
     return posixpath.join(*base_segments)
 
 
-def makeExtension(**kwargs):
-    """
-    Register Markdown extension.
-    """
+def makeExtension(**kwargs: Any) -> PreviewExtension:  # noqa: N802
+    """Register Markdown extension."""
     return PreviewExtension(**kwargs)

zensical/extensions/search.py

@@ -1,7 +1,7 @@
-# Copyright (c) 2025 Zensical and contributors
+# Copyright (c) 2025-2026 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under DCO
+# All contributions are certified under the DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -23,8 +23,9 @@
 
 from html import escape
 from html.parser import HTMLParser
+from typing import Any
 
-from markdown import Extension
+from markdown import Extension, Markdown
 from markdown.postprocessors import Postprocessor
 
 # -----------------------------------------------------------------------------
@@ -33,17 +34,14 @@ from markdown.postprocessors import Postprocessor
 
 
 class SearchProcessor(Postprocessor):
-    """
-    Post processor that extracts searchable content from the rendered HTML.
-    """
+    """Post processor to extract searchable content from the rendered HTML."""
 
-    def __init__(self, md):
+    def __init__(self, md: Markdown) -> None:
         super().__init__(md)
-        self.data = []
+        self.data: list[dict[str, Any]] = []
 
-    def run(self, html):
+    def run(self, html: str) -> str:
         """Process the rendered HTML and extract text length."""
-
         # Divide page content into sections
         parser = Parser()
         parser.feed(html)
@@ -76,17 +74,17 @@ class SearchProcessor(Postprocessor):
 class SearchExtension(Extension):
     """Markdown extension for search indexing."""
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any) -> None:
         self.config = {"keep": [set(), "Set of HTML tags to keep in output"]}
         super().__init__(**kwargs)
 
-    def extendMarkdown(self, md):
+    def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802
         """Register the PostProcessor with Markdown."""
         processor = SearchProcessor(md)
         md.postprocessors.register(processor, "search", 0)
 
 
-def makeExtension(**kwargs):
+def makeExtension(**kwargs: Any) -> SearchExtension:  # noqa: N802
     """Factory function for creating the extension."""
     return SearchExtension(**kwargs)
 
@@ -96,13 +94,16 @@ def makeExtension(**kwargs):
 
 # HTML element
 class Element:
-    """
+    """HTML element.
+
     An element with attributes, essentially a small wrapper object for the
     parser to access attributes in other callbacks than handle_starttag.
     """
 
     # Initialize HTML element
-    def __init__(self, tag, attrs=None):
+    def __init__(
+        self, tag: str, attrs: dict[str, str | None] | None = None
+    ) -> None:
         self.tag = tag
         self.attrs = attrs or {}
 
@@ -111,18 +112,17 @@ class Element:
         return self.tag
 
     # Support comparison (compare by tag only)
-    def __eq__(self, other):
-        if other is Element:
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Element):
             return self.tag == other.tag
-        else:
-            return self.tag == other
+        return self.tag == other
 
     # Support set operations
     def __hash__(self):
         return hash(self.tag)
 
     # Check whether the element should be excluded
-    def is_excluded(self):
+    def is_excluded(self) -> bool:
         return "data-search-exclude" in self.attrs
 
 
@@ -131,31 +131,31 @@ class Element:
 
 # HTML section
 class Section:
-    """
+    """HTML section.
+
     A block of text with markup, preceded by a title (with markup), i.e., a
     headline with a certain level (h1-h6). Internally used by the parser.
     """
 
     # Initialize HTML section
-    def __init__(self, el, level, depth=0):
+    def __init__(self, el: Element, level: int, depth: int = 0) -> None:
         self.el = el
-        self.depth = depth
+        self.depth: int | float = depth
         self.level = level
 
         # Initialize section data
-        self.text = []
-        self.title = []
-        self.id = None
+        self.text: list[str] = []
+        self.title: list[str] = []
+        self.id: str | None = None
 
     # String representation
     def __repr__(self):
         if self.id:
-            return "#".join([self.el.tag, self.id])
-        else:
-            return self.el.tag
+            return f"{self.el.tag}#{self.id}"
+        return self.el.tag
 
     # Check whether the section should be excluded
-    def is_excluded(self):
+    def is_excluded(self) -> bool:
         return self.el.is_excluded()
 
 
@@ -164,7 +164,8 @@ class Section:
 
 # HTML parser
 class Parser(HTMLParser):
-    """
+    """Section divider.
+
     This parser divides the given string of HTML into a list of sections, each
     of which are preceded by a h1-h6 level heading. A white- and blacklist of
     tags dictates which tags should be preserved as part of the index, and
@@ -172,31 +173,31 @@ class Parser(HTMLParser):
     """
 
     # Initialize HTML parser
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
         # Tags to skip
-        self.skip = set(
-            [
-                "object",  # Objects
-                "script",  # Scripts
-                "style",  # Styles
-            ]
-        )
+        self.skip: set[str | Element] = {
+            "object",  # Objects
+            "script",  # Scripts
+            "style",  # Styles
+        }
 
         # Current context and section
-        self.context = []
-        self.section = None
+        self.context: list[Element] = []
+        self.section: Section | None = None
 
         # All parsed sections
-        self.data = []
+        self.data: list[Section] = []
 
     # Called at the start of every HTML tag
-    def handle_starttag(self, tag, attrs):
-        attrs = dict(attrs)
+    def handle_starttag(
+        self, tag: str, attrs: list[tuple[str, str | None]]
+    ) -> None:
+        attrs_dict = dict(attrs)
 
         # Ignore self-closing tags
-        el = Element(tag, attrs)
+        el = Element(tag, attrs_dict)
         if tag not in void:
             self.context.append(el)
         else:
@@ -205,7 +206,7 @@ class Parser(HTMLParser):
         # Handle heading
         if tag in ([f"h{x}" for x in range(1, 7)]):
             depth = len(self.context)
-            if "id" in attrs:
+            if "id" in attrs_dict:
                 # Ensure top-level section
                 if tag != "h1" and not self.data:
                     self.section = Section(Element("hx"), 1, depth)
@@ -214,7 +215,7 @@ class Parser(HTMLParser):
                 # Set identifier, if not first section
                 self.section = Section(el, int(tag[1:2]), depth)
                 if self.data:
-                    self.section.id = attrs["id"]
+                    self.section.id = attrs_dict["id"]
 
                 # Append section to list
                 self.data.append(self.section)
@@ -225,7 +226,7 @@ class Parser(HTMLParser):
             self.data.append(self.section)
 
         # Handle special cases to skip
-        for key, value in attrs.items():
+        for key, value in attrs_dict.items():
             # Skip block if explicitly excluded from search
             if key == "data-search-exclude":
                 self.skip.add(el)
@@ -247,7 +248,7 @@ class Parser(HTMLParser):
             data.append(f"<{tag}>")
 
     # Called at the end of every HTML tag
-    def handle_endtag(self, tag):
+    def handle_endtag(self, tag: str) -> None:
         if not self.context or self.context[-1] != tag:
             return
 
@@ -255,6 +256,7 @@ class Parser(HTMLParser):
         # a headline is nested in another element. In that case, we close the
         # current section, continuing to append data to the previous section,
         # which could also be a nested section – see https://bit.ly/3IxxIJZ
+        assert self.section is not None  # noqa: S101
         if self.section.depth > len(self.context):
             for section in reversed(self.data):
                 if section.depth <= len(self.context):
@@ -295,7 +297,7 @@ class Parser(HTMLParser):
                 data.append(f"</{tag}>")
 
     # Called for the text contents of each tag
-    def handle_data(self, data):
+    def handle_data(self, data: str) -> None:
         if self.skip.intersection(self.context):
             return
 
@@ -324,9 +326,11 @@ class Parser(HTMLParser):
 
         # Collapse adjacent whitespace
         elif data.isspace():
-            if not self.section.text or not self.section.text[-1].isspace():
-                self.section.text.append(data)
-            elif "pre" in self.context:
+            if (
+                not self.section.text
+                or not self.section.text[-1].isspace()
+                or "pre" in self.context
+            ):
                 self.section.text.append(data)
 
         # Handle everything else
@@ -339,35 +343,31 @@ class Parser(HTMLParser):
 # -----------------------------------------------------------------------------
 
 # Tags to keep
-keep = set(
-    [
-        "p",
-        "code",
-        "pre",
-        "li",
-        "ol",
-        "ul",
-        "sub",
-        "sup",
-    ]
-)
+keep = {
+    "p",
+    "code",
+    "pre",
+    "li",
+    "ol",
+    "ul",
+    "sub",
+    "sup",
+}
 
 # Tags that are self-closing
-void = set(
-    [
-        "area",
-        "base",
-        "br",
-        "col",
-        "embed",
-        "hr",
-        "img",
-        "input",
-        "link",
-        "meta",
-        "param",
-        "source",
-        "track",
-        "wbr",
-    ]
-)
+void = {
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+}