markwright 0.1.0__py3-none-any.whl

markwright/image_compare.py

@@ -0,0 +1,128 @@
+# ABOUTME: Image compare embed extension for Python-Markdown.
+# Converts [compare URL1 URL2 height width] syntax to side-by-side image comparison with slider.
+
+from __future__ import annotations
+
+import html
+import re
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+
+COMPARE_RE = re.compile(r"^\[compare\s+(\S+)\s+(\S+)(?:\s+(\d+))?(?:\s+(\d+))?\]$")
+
+DEFAULT_HEIGHT = 270
+DEFAULT_WIDTH = 480
+
+SVG_ARROW = (
+    '<svg class="control-arrow" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">'
+    '<path fill="currentColor" d="M504.3 273.6c4.9-4.5 7.7-10.9 7.7-17.6s-2.8-13-7.7-17.6l-112-104c-7-6.5-17.2-8.2'
+    "-25.9-4.4s-14.4 12.5-14.4 22l0 56-192 0 0-56c0-9.5-5.7-18.2-14.4-22s-18.9-2.1-25.9 4.4l-112 104C2.8 243 0 "
+    "249.3 0 256s2.8 13 7.7 17.6l112 104c7 6.5 17.2 8.2 25.9 4.4s14.4-12.5 14.4-22l0-56 192 0 0 56c0 9.5 5.7 18.2 "
+    '14.4 22s18.9 2.1 25.9-4.4l112-104z"/>'
+    "</svg>"
+)
+
+
+def _render_match(line: str) -> str | None:
+    """Build the image compare HTML for a standalone compare embed line.
+
+    :param line: A single source line.
+    :returns: The compare HTML if the line is a compare embed, else ``None``.
+    """
+    compare_match = COMPARE_RE.match(line.strip())
+    if not compare_match:
+        return None
+
+    left_url = compare_match.group(1)
+    right_url = compare_match.group(2)
+    height = int(compare_match.group(3)) if compare_match.group(3) else DEFAULT_HEIGHT
+    width = int(compare_match.group(4)) if compare_match.group(4) else DEFAULT_WIDTH
+
+    return _build_compare_html(left_url, right_url, height, width)
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone compare embed lines to HTML in raw source.
+
+    Used by the ``mw pre`` CLI stage. Emits the HTML inline without any
+    Python-Markdown stash placeholder.
+
+    :param text: The source text.
+    :returns: The text with standalone compare embeds replaced by HTML.
+    """
+    return "\n".join(_render_match(line) or line for line in text.split("\n"))
+
+
+class ImageComparePreprocessor(Preprocessor):
+    """Replace [compare ...] lines with image comparison HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing image compare syntax with HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with image compare embeds replaced by HTML.
+        """
+        output: list[str] = []
+        for line in lines:
+            # Stash the raw HTML so Markdown does not parse its contents. The
+            # oninput handler contains a JS backtick template literal that
+            # would otherwise be turned into an inline <code> span, and the
+            # block-level <div> would be wrapped in an invalid <p>.
+            compare_html = _render_match(line)
+            if compare_html is not None:
+                output.append(self.md.htmlStash.store(compare_html))
+            else:
+                output.append(line)
+        return output
+
+
+def _build_compare_html(left_url: str, right_url: str, height: int, width: int) -> str:
+    """Build the image compare HTML from parsed arguments.
+
+    :param left_url: URL for the left image.
+    :param right_url: URL for the right image.
+    :param height: Compare widget height in pixels.
+    :param width: Compare widget width in pixels.
+    :returns: Complete image compare HTML string.
+    """
+    escaped_left = html.escape(left_url)
+    escaped_right = html.escape(right_url)
+
+    return (
+        f'<div class="image-compare" style="--value:50%; height: {height}px; width: {width}px;">\n'
+        f'    <img class="image-left" src="{escaped_left}" alt="Image left"/>\n'
+        f'    <img class="image-right" src="{escaped_right}" alt="Image right"/>\n'
+        f'    <input type="range" class="control" min="0" max="100" value="50"\n'
+        f"      oninput=\"this.parentNode.style.setProperty('--value', `${{this.value}}%`)\" />\n"
+        f"    {SVG_ARROW}\n"
+        f"</div>"
+    )
+
+
+class ImageCompareExtension(Extension):
+    """Python-Markdown extension for side-by-side image comparison.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the image compare preprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = ImageComparePreprocessor(md)
+        md.preprocessors.register(preprocessor, "do-image-compare", 20)
+
+
+def makeExtension(**kwargs: object) -> ImageCompareExtension:
+    """Create and return the ImageCompareExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured ImageCompareExtension.
+    """
+    return ImageCompareExtension(**kwargs)

markwright/instagram.py

@@ -0,0 +1,193 @@
+# ABOUTME: Instagram embed extension for Python-Markdown.
+# Converts [instagram URL flags...] syntax to Instagram blockquote embeds with script injection.
+
+from __future__ import annotations
+
+import html
+import re
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.postprocessors import Postprocessor
+from markdown.preprocessors import Preprocessor
+
+from markwright._util import URL_SCHEME_WWW_PREFIX
+
+# Scheme, "www.", the instagram.com host, and a "p/"-style path segment are
+# all optional, so inputs from a bare shortcode up to a full
+# "https://www.instagram.com/p/<shortcode>" all match. Ported verbatim from
+# upstream instagram.js's URL-matching grammar.
+INSTAGRAM_RE = re.compile(
+    r"^\[instagram\s+(?:(?:" + URL_SCHEME_WWW_PREFIX + r"instagram\.com)?/)?(?:\w+/)?(\w+)"
+    r"((?:\s+(?:caption|left|center|right|\d+))*)\]$"
+)
+
+INSTAGRAM_PERMALINK_TEMPLATE = "https://www.instagram.com/p/{post_id}"
+INSTAGRAM_HREF_TEMPLATE = "https://instagram.com/p/{post_id}"
+
+INSTAGRAM_MIN_WIDTH = 326
+INSTAGRAM_MAX_WIDTH = 550
+
+INSTAGRAM_SIGNATURE = 'class="instagram-media"'
+
+INSTAGRAM_SCRIPT = (
+    '<script async defer src="https://www.instagram.com/embed.js"'
+    ' onload="window.instgrm && window.instgrm.Embeds.process()"></script>'
+)
+
+
+def _parse_instagram_flags(raw_flags: str) -> dict[str, str | int | bool]:
+    """Parse space-separated Instagram flags into a settings dictionary.
+
+    :param raw_flags: Raw space-separated flags string.
+    :returns: Dictionary with caption, alignment, and width settings.
+    """
+    flags = raw_flags.split()
+
+    caption = "caption" in flags
+
+    alignment = "center"
+    for align_option in ("left", "right", "center"):
+        if align_option in flags:
+            alignment = align_option
+            break
+
+    width = 0
+    for flag in flags:
+        if flag.isdigit():
+            parsed_width = int(flag)
+            width = max(INSTAGRAM_MIN_WIDTH, min(INSTAGRAM_MAX_WIDTH, parsed_width))
+            break
+
+    return {
+        "caption": caption,
+        "alignment": alignment,
+        "width": width,
+    }
+
+
+def _render_match(line: str) -> str | None:
+    """Build the Instagram embed HTML for a standalone embed line.
+
+    :param line: A single source line.
+    :returns: The embed HTML if the line is an Instagram embed, else ``None``.
+    """
+    instagram_match = INSTAGRAM_RE.match(line.strip())
+    if not instagram_match:
+        return None
+
+    post_id = instagram_match.group(1)
+    raw_flags = instagram_match.group(2).strip()
+    settings = _parse_instagram_flags(raw_flags)
+
+    escaped_href = html.escape(INSTAGRAM_HREF_TEMPLATE.format(post_id=post_id))
+    escaped_permalink = html.escape(INSTAGRAM_PERMALINK_TEMPLATE.format(post_id=post_id))
+
+    alignment = settings["alignment"]
+    width = int(settings["width"])
+    caption = settings["caption"]
+
+    align_attr = f' align="{alignment}"' if alignment != "center" else ""
+    caption_attr = " data-instgrm-captioned" if caption else ""
+    width_style = f' style="width: {width}px;"' if width > 0 else ""
+
+    return (
+        f'<div class="instagram"{align_attr}>\n'
+        f'    <blockquote class="instagram-media"'
+        f' data-instgrm-permalink="{escaped_permalink}"'
+        f' data-instgrm-version="14"{caption_attr}{width_style}>\n'
+        f'        <a href="{escaped_href}">View post</a>\n'
+        f"    </blockquote>\n"
+        f"</div>"
+    )
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone Instagram 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 Instagram 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 Instagram embed script once if an Instagram embed is present.
+
+    Used by the ``mw post`` CLI stage and the in-process postprocessor. The
+    script is appended only when the Instagram 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 Instagram script appended if needed.
+    """
+    if INSTAGRAM_SIGNATURE in rendered_html and INSTAGRAM_SCRIPT not in rendered_html:
+        return rendered_html + "\n" + INSTAGRAM_SCRIPT
+    return rendered_html
+
+
+class InstagramPreprocessor(Preprocessor):
+    """Replace [instagram ...] lines with Instagram embed HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing Instagram embed syntax with HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with Instagram 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 InstagramPostprocessor(Postprocessor):
+    """Append the Instagram 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 an Instagram embed signature is present.
+
+        :param text: Rendered HTML content.
+        :returns: HTML with Instagram script appended if needed.
+        """
+        return apply_html(text)
+
+
+class InstagramExtension(Extension):
+    """Python-Markdown extension for Instagram embeds.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the Instagram preprocessor and postprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = InstagramPreprocessor(md)
+        postprocessor = InstagramPostprocessor(md)
+        md.preprocessors.register(preprocessor, "do-instagram", 20)
+        md.postprocessors.register(postprocessor, "do-instagram-script", 15)
+
+
+def makeExtension(**kwargs: object) -> InstagramExtension:
+    """Create and return the InstagramExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured InstagramExtension.
+    """
+    return InstagramExtension(**kwargs)

markwright/registry.py

@@ -0,0 +1,133 @@
+# ABOUTME: Declarative registry mapping each extension to its pre/post stage functions.
+# Drives select_extensions, run_pre, run_post, and describe for the mw CLI pipeline.
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypedDict
+
+from markwright.codepen import apply_html as codepen_post
+from markwright.codepen import expand_source as codepen_pre
+from markwright.fence import apply_html as fence_post
+from markwright.fence import expand_source as fence_pre
+from markwright.highlight import apply_html as highlight_post
+from markwright.highlight import expand_source as highlight_pre
+from markwright.image_compare import expand_source as image_compare_pre
+from markwright.instagram import apply_html as instagram_post
+from markwright.instagram import expand_source as instagram_pre
+from markwright.slideshow import expand_source as slideshow_pre
+from markwright.twitter import apply_html as twitter_post
+from markwright.twitter import expand_source as twitter_pre
+from markwright.youtube import expand_source as youtube_pre
+
+PreFn = Callable[[str], str]
+PostFn = Callable[[str, list[str] | None], str]
+
+
+class StageSpec(TypedDict):
+    """Stage functions and priorities for a single extension.
+
+    :ivar pre: Source-stage transform, or ``None`` if the extension has no pre stage.
+    :ivar post: HTML-stage transform, or ``None`` if the extension has no post stage.
+    :ivar pre_priority: Descending order key for the pre stage (higher runs first).
+    :ivar post_priority: Descending order key for the post stage (higher runs first).
+    """
+
+    pre: PreFn | None
+    post: PostFn | None
+    pre_priority: int
+    post_priority: int
+
+
+REGISTRY: dict[str, StageSpec] = {
+    "youtube": {"pre": youtube_pre, "post": None, "pre_priority": 20, "post_priority": 0},
+    "slideshow": {"pre": slideshow_pre, "post": None, "pre_priority": 20, "post_priority": 0},
+    "image_compare": {"pre": image_compare_pre, "post": None, "pre_priority": 20, "post_priority": 0},
+    "codepen": {"pre": codepen_pre, "post": codepen_post, "pre_priority": 20, "post_priority": 15},
+    "twitter": {"pre": twitter_pre, "post": twitter_post, "pre_priority": 20, "post_priority": 15},
+    "instagram": {"pre": instagram_pre, "post": instagram_post, "pre_priority": 20, "post_priority": 15},
+    "fence": {"pre": fence_pre, "post": fence_post, "pre_priority": 40, "post_priority": 25},
+    "highlight": {"pre": highlight_pre, "post": highlight_post, "pre_priority": 10, "post_priority": 25},
+}
+
+EXTENSION_NAMES: tuple[str, ...] = tuple(REGISTRY)
+
+
+def select_extensions(use: list[str], exclude: list[str]) -> list[str]:
+    """Resolve the active extension set from ``use`` and ``exclude`` filters.
+
+    An empty ``use`` selects every registered extension; a non-empty ``use`` restricts
+    to exactly those names. ``exclude`` then removes names from the result.
+
+    :param use: Names to include, or empty to include all.
+    :param exclude: Names to remove from the included set.
+    :returns: Selected extension names in registry order.
+    :raises ValueError: If any name in ``use`` or ``exclude`` is not registered.
+    """
+    for name in [*use, *exclude]:
+        if name not in REGISTRY:
+            raise ValueError(f"unknown extension: {name!r}")
+    included = use if use else list(EXTENSION_NAMES)
+    return [name for name in EXTENSION_NAMES if name in included and name not in exclude]
+
+
+def _ordered(
+    names: list[str],
+    get_stage: Callable[[StageSpec], PreFn | PostFn | None],
+    get_priority: Callable[[StageSpec], int],
+) -> list[str]:
+    """Return selected names that have the given stage, ordered by descending priority.
+
+    :param names: Selected extension names.
+    :param get_stage: Accessor returning the stage function (or ``None``) for a spec.
+    :param get_priority: Accessor returning the stage priority for a spec.
+    :returns: Names with a non-``None`` stage function, highest priority first.
+    """
+    selected = [name for name in EXTENSION_NAMES if name in names and get_stage(REGISTRY[name]) is not None]
+    return sorted(selected, key=lambda name: get_priority(REGISTRY[name]), reverse=True)
+
+
+def run_pre(text: str, names: list[str]) -> str:
+    """Apply each selected pre-stage transform to ``text`` in descending priority order.
+
+    :param text: Markdown source text.
+    :param names: Selected extension names.
+    :returns: Source text after every selected pre stage has run.
+    """
+    for name in _ordered(names, lambda spec: spec["pre"], lambda spec: spec["pre_priority"]):
+        pre_fn = REGISTRY[name]["pre"]
+        assert pre_fn is not None
+        text = pre_fn(text)
+    return text
+
+
+def run_post(html: str, names: list[str], warnings: list[str] | None = None) -> str:
+    """Apply each selected post-stage transform to ``html`` in descending priority order.
+
+    :param html: Rendered HTML.
+    :param names: Selected extension names.
+    :param warnings: Optional list collecting skip reasons from stages that validate markers.
+    :returns: HTML after every selected post stage has run.
+    """
+    for name in _ordered(names, lambda spec: spec["post"], lambda spec: spec["post_priority"]):
+        post_fn = REGISTRY[name]["post"]
+        assert post_fn is not None
+        html = post_fn(html, warnings)
+    return html
+
+
+def describe() -> list[tuple[str, list[str]]]:
+    """Report each registered extension and the stages it provides.
+
+    :returns: ``(name, stages)`` pairs in registry order, where ``stages`` lists
+        ``"pre"`` and/or ``"post"`` depending on which stage functions exist.
+    """
+    described: list[tuple[str, list[str]]] = []
+    for name in EXTENSION_NAMES:
+        stages: list[str] = []
+        if REGISTRY[name]["pre"] is not None:
+            stages.append("pre")
+        if REGISTRY[name]["post"] is not None:
+            stages.append("post")
+        described.append((name, stages))
+    return described

markwright/slideshow.py

@@ -0,0 +1,150 @@
+# ABOUTME: Slideshow embed extension for Python-Markdown.
+# Converts [slideshow URL1 URL2 ... height width] syntax to image slideshow HTML.
+
+from __future__ import annotations
+
+import html
+import re
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+
+SLIDESHOW_RE = re.compile(r"^\[slideshow\s+(.+)\]$")
+
+DEFAULT_HEIGHT = 270
+DEFAULT_WIDTH = 480
+
+
+def _parse_slideshow_args(raw_args: str) -> tuple[list[str], int, int]:
+    """Parse slideshow arguments into URLs and optional dimensions.
+
+    Separates URLs from trailing integer arguments (height, width).
+    Requires at least 1 URL, matching upstream slideshow.js:82 (which
+    rejects only zero images).
+
+    :param raw_args: The raw argument string after 'slideshow'.
+    :returns: Tuple of (urls, height, width). Returns empty urls list if there are no URLs.
+    """
+    parts = raw_args.split()
+
+    # Separate trailing integers from URLs
+    trailing_ints: list[int] = []
+    while parts and parts[-1].isdigit():
+        trailing_ints.insert(0, int(parts.pop()))
+
+    urls = parts
+
+    if len(urls) < 1:
+        return [], DEFAULT_HEIGHT, DEFAULT_WIDTH
+
+    height = trailing_ints[0] if len(trailing_ints) >= 1 else DEFAULT_HEIGHT
+    width = trailing_ints[1] if len(trailing_ints) >= 2 else DEFAULT_WIDTH
+
+    return urls, height, width
+
+
+def _render_match(line: str) -> str | None:
+    """Build the slideshow HTML for a standalone slideshow embed line.
+
+    Returns ``None`` when the line is not a slideshow embed or has fewer than
+    two URLs.
+
+    :param line: A single source line.
+    :returns: The slideshow HTML if the line is a valid embed, else ``None``.
+    """
+    slideshow_match = SLIDESHOW_RE.match(line.strip())
+    if not slideshow_match:
+        return None
+
+    urls, height, width = _parse_slideshow_args(slideshow_match.group(1))
+    if not urls:
+        return None
+
+    return _build_slideshow_html(urls, height, width)
+
+
+def expand_source(text: str) -> str:
+    """Expand standalone slideshow embed lines to HTML in raw source.
+
+    Used by the ``mw pre`` CLI stage. Emits the HTML inline without any
+    Python-Markdown stash placeholder.
+
+    :param text: The source text.
+    :returns: The text with standalone slideshow embeds replaced by HTML.
+    """
+    return "\n".join(_render_match(line) or line for line in text.split("\n"))
+
+
+class SlideshowPreprocessor(Preprocessor):
+    """Replace [slideshow ...] lines with slideshow HTML.
+
+    :param md: The Markdown instance.
+    """
+
+    def run(self, lines: list[str]) -> list[str]:
+        """Process lines, replacing slideshow embed syntax with HTML.
+
+        :param lines: Source lines to process.
+        :returns: Modified lines with slideshow embeds replaced by HTML.
+        """
+        output: list[str] = []
+        for line in lines:
+            slideshow_html = _render_match(line)
+            if slideshow_html is not None:
+                output.append(self.md.htmlStash.store(slideshow_html))
+            else:
+                output.append(line)
+        return output
+
+
+def _build_slideshow_html(urls: list[str], height: int, width: int) -> str:
+    """Build the slideshow HTML from parsed arguments.
+
+    :param urls: List of image URLs.
+    :param height: Slideshow height in pixels.
+    :param width: Slideshow width in pixels.
+    :returns: Complete slideshow HTML string.
+    """
+    slides = "\n".join(
+        f'    <img src="{html.escape(url)}" alt="Slide #{slide_index}" />'
+        for slide_index, url in enumerate(urls, start=1)
+    )
+
+    scroll_left = "(() => this.parentNode.getElementsByClassName('slides')[0].scrollLeft"
+    left_arrow = f'  <div class="action left" onclick="{scroll_left} -= {width})()">&#8249;</div>\n'
+    right_arrow = f'  <div class="action right" onclick="{scroll_left} += {width})()">&#8250;</div>\n'
+
+    return (
+        f'<div class="slideshow" style="height: {height}px; width: {width}px;">\n'
+        f"{left_arrow}"
+        f"{right_arrow}"
+        f'  <div class="slides">\n'
+        f"{slides}\n"
+        f"  </div>\n"
+        f"</div>"
+    )
+
+
+class SlideshowExtension(Extension):
+    """Python-Markdown extension for image slideshow embeds.
+
+    :param \\*\\*kwargs: Configuration options passed to the extension.
+    """
+
+    def extendMarkdown(self, md: Markdown) -> None:
+        """Register the slideshow preprocessor.
+
+        :param md: The Markdown instance to extend.
+        """
+        preprocessor = SlideshowPreprocessor(md)
+        md.preprocessors.register(preprocessor, "do-slideshow", 20)
+
+
+def makeExtension(**kwargs: object) -> SlideshowExtension:
+    """Create and return the SlideshowExtension instance.
+
+    :param \\*\\*kwargs: Configuration options.
+    :returns: A configured SlideshowExtension.
+    """
+    return SlideshowExtension(**kwargs)