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

zensical/extensions/search.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,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 that extracts 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",
+}

zensical/extensions/utilities/__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/utilities/filter.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
@@ -31,13 +31,10 @@ from fnmatch import fnmatch
 
 
 class Filter:
-    """
-    A filter.
-    """
+    """A filter."""
 
     def __init__(self, config: dict):
-        """
-        Initialize the filter.
+        """Initialize the filter.
 
         Arguments:
             config: The filter configuration.
@@ -45,8 +42,7 @@ class Filter:
         self.config = config
 
     def __call__(self, value: str) -> bool:
-        """
-        Filter a value.
+        """Filter a value.
 
         First, the inclusion patterns are checked. Regardless of whether they
         are present, the exclusion patterns are checked afterwards. This allows
@@ -59,7 +55,6 @@ class Filter:
         Returns:
             Whether the value should be included.
         """
-
         # Check if value matches one of the inclusion patterns
         if "include" in self.config:
             for pattern in self.config["include"]:

zensical/main.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,12 +23,14 @@
 
 from __future__ import annotations
 
-import click
 import os
 import shutil
-import webbrowser
+from pathlib import Path
+from typing import Any
 
+import click
 from click import ClickException
+
 from zensical import build, serve, version
 
 # ----------------------------------------------------------------------------
@@ -38,8 +40,8 @@ from zensical import build, serve, version
 
 @click.version_option(version=version(), message="%(version)s")
 @click.group()
-def cli():
-    """Zensical - A modern static site generator"""
+def cli() -> None:
+    """Zensical - A modern static site generator."""
 
 
 @cli.command(name="build")
@@ -64,10 +66,8 @@ def cli():
     is_flag=True,
     help="Strict mode (currently unsupported).",
 )
-def execute_build(config_file: str | None, **kwargs):
-    """
-    Build a project.
-    """
+def execute_build(config_file: str | None, **kwargs: Any) -> None:
+    """Build a project."""
     if config_file is None:
         for file in ["zensical.toml", "mkdocs.yml", "mkdocs.yaml"]:
             if os.path.exists(file):
@@ -80,7 +80,7 @@ def execute_build(config_file: str | None, **kwargs):
 
     # Build project in Rust runtime, calling back into Python when necessary,
     # e.g., to parse MkDocs configuration format or render Markdown
-    build(os.path.abspath(config_file), kwargs.get("clean"))
+    build(os.path.abspath(config_file), kwargs.get("clean", False))
 
 
 @cli.command(name="serve")
@@ -111,10 +111,8 @@ def execute_build(config_file: str | None, **kwargs):
     is_flag=True,
     help="Strict mode (currently unsupported).",
 )
-def execute_serve(config_file: str | None, **kwargs):
-    """
-    Build and serve a project.
-    """
+def execute_serve(config_file: str | None, **kwargs: Any) -> None:
+    """Build and serve a project."""
     if config_file is None:
         for file in ["zensical.toml", "mkdocs.yml", "mkdocs.yaml"]:
             if os.path.exists(file):
@@ -122,17 +120,12 @@ def execute_serve(config_file: str | None, **kwargs):
                 break
         else:
             raise ClickException("No config file found in the current folder.")
-
-    # Obtain development server address and open in browser, if desired
-    dev_addr = kwargs.get("dev_addr") or "localhost:8000"
-    if kwargs.get("open", False):
-        webbrowser.open(f"http://{dev_addr}")
     if kwargs.get("strict", False):
         print("Warning: Strict mode is currently unsupported.")
 
     # Build project in Rust runtime, calling back into Python when necessary,
     # e.g., to parse MkDocs configuration format or render Markdown
-    serve(os.path.abspath(config_file), dev_addr)
+    serve(os.path.abspath(config_file), kwargs)
 
 
 @cli.command(name="new")
@@ -141,38 +134,34 @@ def execute_serve(config_file: str | None, **kwargs):
     type=click.Path(file_okay=False, dir_okay=True, writable=True),
     required=False,
 )
-def new_project(directory: str | None, **kwargs):
-    """
-    Create a new template project in the current directory or in the given
-    directory.
+def new_project(directory: str | None, **kwargs: Any) -> None:  # noqa: ARG001
+    """Create a new template project in the current directory or in the given directory.
 
     Raises:
         ClickException: if the directory already contains a zensical.toml or a
             docs directory that is not empty, as well as when the path provided
             points to something that is not a directory.
     """
-
-    if directory is None:
-        directory = "."
-    docs_dir = os.path.join(directory, "docs")
-    config_file = os.path.join(directory, "zensical.toml")
-
-    if os.path.exists(directory):
-        if not os.path.isdir(directory):
-            raise (ClickException("Path provided is not a directory."))
-        if os.path.exists(config_file):
-            raise (ClickException(f"{config_file} already exists."))
-        if os.path.exists(docs_dir):
-            raise (ClickException(f"{docs_dir} already exists."))
-    else:
-        os.makedirs(directory)
-
-    package_dir = os.path.dirname(os.path.abspath(__file__))
-    shutil.copy(os.path.join(package_dir, "bootstrap/zensical.toml"), directory)
-    shutil.copytree(
-        os.path.join(package_dir, "bootstrap/docs"),
-        os.path.join(directory, "docs"),
-    )
+    working_dir = Path.cwd() if directory is None else Path(directory).resolve()
+    if working_dir.is_file():
+        raise ClickException(f"{working_dir} must be a directory, not a file.")
+
+    config_file = working_dir / "zensical.toml"
+    if config_file.exists():
+        raise ClickException(f"{config_file} already exists.")
+
+    working_dir.mkdir(parents=True, exist_ok=True)
+
+    package_dir = Path(__file__).resolve().parent
+    bootstrap = package_dir / "bootstrap"
+
+    for src_file in bootstrap.rglob("*"):
+        if src_file.is_file():
+            rel_path = src_file.relative_to(bootstrap)
+            dest_file = working_dir / rel_path
+            if not dest_file.exists():
+                dest_file.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copyfile(src_file, dest_file)
 
 
 # ----------------------------------------------------------------------------

zensical/markdown.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,15 +24,19 @@
 from __future__ import annotations
 
 import re
-import yaml
-
 from datetime import date, datetime
+from typing import TYPE_CHECKING, Any
+
+import yaml
 from markdown import Markdown
 from yaml import SafeLoader
 
-from .config import _CONFIG
-from .extensions.links import LinksExtension
-from .extensions.search import SearchExtension
+from zensical.config import get_config
+from zensical.extensions.links import LinksExtension
+from zensical.extensions.search import SearchExtension
+
+if TYPE_CHECKING:
+    from zensical.extensions.search import SearchProcessor
 
 # ----------------------------------------------------------------------------
 # Constants
@@ -53,15 +57,14 @@ Regex pattern to extract front matter.
 
 
 def render(content: str, path: str) -> dict:
-    """
-    Render Markdown and return HTML.
+    """Render Markdown and return HTML.
 
     This function returns rendered HTML as well as the table of contents and
     metadata. Now, this is the part where Zensical needs to call into Python,
     in order to support the specific syntax of Python Markdown. We're working
     on moving the entire rendering chain to Rust.
     """
-    config = _CONFIG
+    config = get_config()
 
     # Initialize Markdown parser
     md = Markdown(
@@ -77,8 +80,8 @@ def render(content: str, path: str) -> dict:
     links.extendMarkdown(md)
 
     # Register search extension, which extracts text for search indexing
-    search = SearchExtension()
-    search.extendMarkdown(md)
+    search_extension = SearchExtension()
+    search_extension.extendMarkdown(md)
 
     # First, extract metadata - the Python Markdown parser brings a metadata
     # extension, but the implementation is broken, as it does not support full
@@ -91,7 +94,7 @@ def render(content: str, path: str) -> dict:
                 content = content[match.end() :].lstrip("\n")
             else:
                 meta = {}
-        except Exception:
+        except Exception:  # noqa: BLE001
             pass
 
     # Convert Markdown and set nullish metadata to empty string, since we
@@ -106,24 +109,22 @@ def render(content: str, path: str) -> dict:
             meta[key] = value.isoformat()
 
     # Obtain search index data, unless page is excluded
-    search = md.postprocessors["search"]
+    search_processor: SearchProcessor = md.postprocessors["search"]  # type: ignore[assignment]
     if meta.get("search", {}).get("exclude", False):
-        search.data = []
+        search_processor.data = []
 
     # Return Markdown with metadata
     return {
         "meta": meta,
         "content": content,
-        "search": search.data,
+        "search": search_processor.data,
         "title": "",
         "toc": [_convert_toc(item) for item in getattr(md, "toc_tokens", [])],
     }
 
 
-def _convert_toc(item: any):
-    """
-    Convert a table of contents item to navigation item format.
-    """
+def _convert_toc(item: Any) -> dict:
+    """Convert a table of contents item to navigation item format."""
     toc_item = {
         "title": item["data-toc-label"] or item["name"],
         "id": item["id"],