markwright 0.1.0__py3-none-any.whl

markwright/_util.py

@@ -0,0 +1,31 @@
+# ABOUTME: Shared utility functions and constants for markwright extensions.
+# Provides fraction reduction and the permissive URL-prefix grammar used by embed extensions.
+
+from __future__ import annotations
+
+import math
+
+URL_SCHEME_WWW_PREFIX = r"(?:(?:https?:)?//)?(?:www\.)?"
+"""Regex fragment matching an optional ``scheme://`` and an optional ``www.``.
+
+Shared by the Twitter and Instagram embed grammars (upstream ``twitter.js``
+and ``instagram.js``), which both accept a URL prefix ranging from nothing
+(a bare path) up to a full ``https://www.<host>``.
+"""
+
+
+def reduce_fraction(numerator: int, denominator: int) -> tuple[int, int]:
+    """Reduce a fraction to its lowest terms.
+
+    A zero operand has no defined greatest common divisor, so the fraction is
+    returned unchanged rather than raising ``ZeroDivisionError``; the caller
+    decides how to treat a degenerate zero numerator or denominator.
+
+    :param numerator: The numerator of the fraction.
+    :param denominator: The denominator of the fraction.
+    :returns: Tuple of (reduced numerator, reduced denominator).
+    """
+    if numerator == 0 or denominator == 0:
+        return numerator, denominator
+    divisor = math.gcd(numerator, denominator)
+    return numerator // divisor, denominator // divisor

markwright/cli.py

@@ -0,0 +1,147 @@
+# ABOUTME: Command-line entry point for the mw markwright pipeline tool.
+# Builds the argparse parser and dispatches list/pre/post/render; --version reports the package version.
+
+from __future__ import annotations
+
+import argparse
+import sys
+from importlib.metadata import version
+
+import markdown
+
+from markwright import registry
+
+
+def _package_version() -> str:
+    """Return the installed markwright distribution version.
+
+    :returns: The version string for the ``markwright`` distribution.
+    """
+    return version("markwright")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the ``mw`` argument parser with its subcommands.
+
+    :returns: A parser exposing ``--version`` and the ``list`` subcommand.
+    """
+    parser = argparse.ArgumentParser(prog="mw", description="markwright Markdown pipeline CLI.")
+    parser.add_argument("--version", action="version", version=f"mw {_package_version()}")
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("list", help="List registered extensions and the stages each provides.")
+    pre_parser = subparsers.add_parser("pre", help="Expand markwright source directives read from stdin.")
+    _add_selection_flags(pre_parser)
+    post_parser = subparsers.add_parser("post", help="Post-process rendered HTML read from stdin.")
+    _add_selection_flags(post_parser)
+    post_parser.add_argument("--warn", action="store_true", help="Report skipped markers to stderr.")
+    render_parser = subparsers.add_parser("render", help="Render Markdown from stdin to final HTML.")
+    _add_selection_flags(render_parser)
+    return parser
+
+
+def _add_selection_flags(subparser: argparse.ArgumentParser) -> None:
+    """Add the shared ``--use`` and ``--exclude`` selection flags to a subparser.
+
+    :param subparser: The subcommand parser to extend.
+    """
+    subparser.add_argument("--use", action="append", default=[], help="Restrict to the named extension (repeatable).")
+    subparser.add_argument("--exclude", action="append", default=[], help="Drop the named extension (repeatable).")
+
+
+def _run_list() -> int:
+    """Print each registered extension and its available stages.
+
+    :returns: Always ``0``.
+    """
+    for name, stages in registry.describe():
+        print(f"{name}: {', '.join(stages)}")
+    return 0
+
+
+def _resolve_selection(args: argparse.Namespace) -> list[str] | None:
+    """Resolve the active extension names, reporting unknown names to stderr.
+
+    :param args: Parsed arguments carrying ``use`` and ``exclude`` lists.
+    :returns: Selected extension names, or ``None`` if a name is unknown (the
+        caller should then return exit code ``2``).
+    """
+    try:
+        return registry.select_extensions(args.use, args.exclude)
+    except ValueError as selection_error:
+        print(selection_error, file=sys.stderr)
+        return None
+
+
+def _run_pre(args: argparse.Namespace) -> int:
+    """Expand source directives from stdin and write the result to stdout.
+
+    :param args: Parsed arguments carrying ``use`` and ``exclude``.
+    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
+    """
+    names = _resolve_selection(args)
+    if names is None:
+        return 2
+    sys.stdout.write(registry.run_pre(sys.stdin.read(), names))
+    return 0
+
+
+def _run_post(args: argparse.Namespace) -> int:
+    """Post-process HTML from stdin and write the result to stdout.
+
+    :param args: Parsed arguments carrying ``use``, ``exclude``, and ``warn``.
+    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
+    """
+    names = _resolve_selection(args)
+    if names is None:
+        return 2
+    warnings: list[str] | None = [] if args.warn else None
+    rendered_html = registry.run_post(sys.stdin.read(), names, warnings)
+    sys.stdout.write(rendered_html)
+    if warnings is not None:
+        for warning in warnings:
+            print(warning, file=sys.stderr)
+    return 0
+
+
+def _run_render(args: argparse.Namespace) -> int:
+    """Render Markdown from stdin to final HTML using the in-process stack.
+
+    Builds a ``markdown.Markdown`` instance configured with ``pymdownx.superfences``
+    and ``pymdownx.highlight`` plus the selected ``markwright.*`` extensions, mirroring
+    the site stack so fence and highlight render correctly.
+
+    :param args: Parsed arguments carrying ``use`` and ``exclude``.
+    :returns: ``0`` on success, ``2`` if a selected extension name is unknown.
+    """
+    names = _resolve_selection(args)
+    if names is None:
+        return 2
+    instance = markdown.Markdown(
+        extensions=["pymdownx.superfences", "pymdownx.highlight", *(f"markwright.{name}" for name in names)],
+        extension_configs={"pymdownx.highlight": {"pygments_lang_class": True}},
+    )
+    sys.stdout.write(instance.convert(sys.stdin.read()))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Parse ``argv`` and dispatch to the selected subcommand.
+
+    :param argv: Argument vector, or ``None`` to read from ``sys.argv``.
+    :returns: Process exit code (``0`` success, ``2`` usage error).
+    """
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exit_error:
+        return exit_error.code if isinstance(exit_error.code, int) else 2
+    if args.command == "list":
+        return _run_list()
+    if args.command == "pre":
+        return _run_pre(args)
+    if args.command == "post":
+        return _run_post(args)
+    if args.command == "render":
+        return _run_render(args)
+    parser.print_usage()
+    return 2

markwright/codepen.py

@@ -0,0 +1,206 @@
+# ABOUTME: CodePen embed extension for Python-Markdown.
+# Converts [codepen USER HASH flags...] syntax to CodePen embed HTML with script injection.
+
+from __future__ import annotations
+
+import html
+import re
+import urllib.parse
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.postprocessors import Postprocessor
+from markdown.preprocessors import Preprocessor
+
+CODEPEN_RE = re.compile(r"^\[codepen\s+(\S+)\s+(\S+)((?:\s+(?:lazy|light|dark|editable|html|css|js|result|\d+))*)\]$")
+
+TAB_PRIORITY = ["html", "css", "js"]
+
+DEFAULT_HEIGHT = 256
+
+CODEPEN_SIGNATURE = 'class="codepen"'
+
+CODEPEN_SCRIPT = (
+    '<script async defer src="https://static.codepen.io/assets/embed/ei.js" type="text/javascript"></script>'
+)
+
+
+def _parse_flags(raw_flags: str) -> dict[str, str | int | bool]:
+    """Parse space-separated CodePen flags into a settings dictionary.
+
+    :param raw_flags: Raw space-separated flags string.
+    :returns: Dictionary with theme, height, tab, lazy, and editable settings.
+    """
+    flags = raw_flags.split()
+
+    # Theme: dark wins if both present
+    theme = "dark" if "dark" in flags else "light"
+
+    # Height: first integer found, or default
+    height = DEFAULT_HEIGHT
+    for flag in flags:
+        if flag.isdigit():
+            height = int(flag)
+            break
+
+    # Lazy and editable
+    lazy = "lazy" in flags
+    editable = "editable" in flags
+
+    # Tab: priority is html > css > js; result can combine with another tab
+    selected_tab = ""
+    for tab_name in TAB_PRIORITY:
+        if tab_name in flags:
+            selected_tab = tab_name
+            break
+
+    has_result = "result" in flags
+
+    if selected_tab and has_result:
+        tab = f"{selected_tab},result"
+    elif selected_tab:
+        tab = selected_tab
+    else:
+        tab = "result"
+
+    return {
+        "theme": theme,
+        "height": height,
+        "tab": tab,
+        "lazy": lazy,
+        "editable": editable,
+    }
+
+
+def _render_match(line: str) -> str | None:
+    """Build the CodePen embed HTML for a standalone embed line.
+
+    :param line: A single source line.
+    :returns: The embed HTML if the line is a CodePen embed, else ``None``.
+    """
+    codepen_match = CODEPEN_RE.match(line.strip())
+    if not codepen_match:
+        return None
+
+    user = codepen_match.group(1)
+    hash_id = codepen_match.group(2)
+    raw_flags = codepen_match.group(3).strip()
+    settings = _parse_flags(raw_flags)
+
+    escaped_user = html.escape(str(user))
+    escaped_hash = html.escape(str(hash_id))
+    encoded_user = urllib.parse.quote(str(user), safe="")
+    encoded_hash = urllib.parse.quote(str(hash_id), safe="")
+    height = settings["height"]
+    theme = settings["theme"]
+    tab = settings["tab"]
+
+    lazy_attr = ' data-preview="true"' if settings["lazy"] else ""
+    editable_attr = ' data-editable="true"' if settings["editable"] else ""
+
+    return (
+        f'<p class="codepen" data-height="{height}"'
+        f' data-theme-id="{theme}" data-default-tab="{tab}"'
+        f' data-user="{escaped_user}" data-slug-hash="{escaped_hash}"'
+        f"{lazy_attr}{editable_attr}"
+        f' style="height: {height}px; box-sizing: border-box;'
+        f" display: flex; align-items: center; justify-content: center;"
+        f' border: 2px solid; margin: 1em 0; padding: 1em;">\n'
+        f"    <span>See the Pen"
+        f' <a href="https://codepen.io/{encoded_user}/pen/{encoded_hash}">'
+        f"{escaped_hash} by {escaped_user}</a>"
+        f' (<a href="https://codepen.io/{encoded_user}">@{escaped_user}</a>)'
+        f" on <a href='https://codepen.io'>CodePen</a>.</span>\n"
+        f"</p>"
+    )
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone CodePen embed lines to embed HTML in raw source.
+
+    Used by the ``mw pre`` CLI stage. Unlike the preprocessor, this emits the
+    HTML inline without any Python-Markdown stash placeholder.
+
+    :param text: The source text.
+    :returns: The text with standalone CodePen embeds replaced by HTML.
+    """
+    return "\n".join(_render_match(line) or line for line in text.split("\n"))
+
+
+def apply_html(rendered_html: str, warnings: list[str] | None = None) -> str:
+    """Inject the CodePen embed script once if a CodePen embed is present.
+
+    Used by the ``mw post`` CLI stage and the in-process postprocessor. The
+    script is appended only when the CodePen class signature is present and the
+    script is not already injected, so the transform is idempotent.
+
+    :param rendered_html: Rendered HTML content.
+    :param warnings: Optional warnings list; unused (signature injection never warns).
+    :returns: HTML with the CodePen script appended if needed.
+    """
+    if CODEPEN_SIGNATURE in rendered_html and CODEPEN_SCRIPT not in rendered_html:
+        return rendered_html + "\n" + CODEPEN_SCRIPT
+    return rendered_html
+
+
+class CodePenPreprocessor(Preprocessor):
+    """Replace [codepen ...] lines with CodePen embed HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing CodePen embed syntax with HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with CodePen embeds replaced by HTML.
+        """
+        output: list[str] = []
+        for line in lines:
+            embed_html = _render_match(line)
+            if embed_html is not None:
+                output.append(self.md.htmlStash.store(embed_html))
+            else:
+                output.append(line)
+        return output
+
+
+class CodePenPostprocessor(Postprocessor):
+    """Append the CodePen embed script tag once if any embeds are present.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, text: str) -> str:
+        """Append the script tag if a CodePen embed signature is present.
+
+        :param text: Rendered HTML content.
+        :returns: HTML with CodePen script appended if needed.
+        """
+        return apply_html(text)
+
+
+class CodePenExtension(Extension):
+    """Python-Markdown extension for CodePen embeds.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the CodePen preprocessor and postprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = CodePenPreprocessor(md)
+        postprocessor = CodePenPostprocessor(md)
+        md.preprocessors.register(preprocessor, "do-codepen", 20)
+        md.postprocessors.register(postprocessor, "do-codepen-script", 15)
+
+
+def makeExtension(**kwargs: object) -> CodePenExtension:
+    """Create and return the CodePenExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured CodePenExtension.
+    """
+    return CodePenExtension(**kwargs)