zensical 0.0.3__cp310-abi3-musllinux_1_2_i686.whl → 0.0.12__cp310-abi3-musllinux_1_2_i686.whl

zensical/extensions/__init__.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under 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) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under 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) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under 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,11 +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 xml.etree.ElementTree import Element
-from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from xml.etree.ElementTree import Element
+
 
 # -----------------------------------------------------------------------------
 # Classes
@@ -35,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.
@@ -49,10 +54,10 @@ 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 = self.path.endswith(("index.md", "README.md"))
+        current_is_index = get_name(self.path) in ("index.md", "README.md")
         for el in root.iter():
             # In case the element has a `href` or `src` attribute, we parse it
             # as an URL, so we can analyze and alter its path
@@ -63,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
 
@@ -81,10 +86,9 @@ class LinksProcessor(Treeprocessor):
             if path.endswith(".md"):
                 path = path.removesuffix(".md") + ".html"
                 if self.use_directory_urls:
-                    if path.endswith("index.html"):
-                        path = path[: -len("index.html")]
-                    elif path.endswith("README.html"):
-                        path = path[: -len("README.html")]
+                    name = get_name(path)
+                    if name in ("index.html", "README.html"):
+                        path = path[: -len(name)]
                     elif path.endswith(".html"):
                         path = path[: -len(".html")] + "/"
 
@@ -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,4 +121,15 @@ 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)
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+
+def get_name(path: str) -> str:
+    """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) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under 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)