markstitch 0.1.0__py3-none-any.whl

markstitch/__init__.py

@@ -0,0 +1,153 @@
+"""Compose, parse, and edit YFM documents in Python."""
+
+from markstitch.attributes import Attributes
+from markstitch.blocks import (
+    BulletList,
+    Checklist,
+    CodeBlock,
+    Comment,
+    Cut,
+    Header1,
+    Header2,
+    Header3,
+    Header4,
+    Header5,
+    Header6,
+    Heading,
+    ListItem,
+    MathBlock,
+    Note,
+    Paragraph,
+    Quote,
+    Rule,
+    Tab,
+    Tabs,
+    Task,
+)
+from markstitch.core import YFM, Element, Inline, Link, NumberedList, Profile, UnsupportedFeatureError
+from markstitch.extensions import (
+    File,
+    Footnote,
+    FootnoteDefinition,
+    Grid,
+    Iframe,
+    Include,
+    Layout,
+    LinkDefinition,
+    PageTree,
+    RawHTML,
+    ReferenceImage,
+    ReferenceLink,
+    StyledBlock,
+    Term,
+    TermDefinition,
+    Toc,
+    Video,
+    Visibility,
+    WikiInclude,
+)
+from markstitch.inline import (
+    Bold,
+    Code,
+    Color,
+    Emoji,
+    Highlight,
+    Image,
+    Italic,
+    LineBreak,
+    Math,
+    Mention,
+    Monospace,
+    Raw,
+    RawInline,
+    Strike,
+    Subscript,
+    Superscript,
+    Text,
+    Underline,
+)
+from markstitch.parser import ParseError, parse
+from markstitch.tables import Cell, Row, Span, Table, YFMTable
+from markstitch.templates import For, If, InlineFor, InlineIf, Slice, Variable
+
+__all__ = [
+    "YFM",
+    "Attributes",
+    "Bold",
+    "BulletList",
+    "Cell",
+    "Checklist",
+    "Code",
+    "CodeBlock",
+    "Color",
+    "Comment",
+    "Cut",
+    "Element",
+    "Emoji",
+    "File",
+    "Footnote",
+    "FootnoteDefinition",
+    "For",
+    "Grid",
+    "Header1",
+    "Header2",
+    "Header3",
+    "Header4",
+    "Header5",
+    "Header6",
+    "Heading",
+    "Highlight",
+    "If",
+    "Iframe",
+    "Image",
+    "Include",
+    "Inline",
+    "InlineFor",
+    "InlineIf",
+    "Italic",
+    "Layout",
+    "LineBreak",
+    "Link",
+    "LinkDefinition",
+    "ListItem",
+    "Math",
+    "MathBlock",
+    "Mention",
+    "Monospace",
+    "Note",
+    "NumberedList",
+    "PageTree",
+    "Paragraph",
+    "ParseError",
+    "Profile",
+    "Quote",
+    "Raw",
+    "RawHTML",
+    "RawInline",
+    "ReferenceImage",
+    "ReferenceLink",
+    "Row",
+    "Rule",
+    "Slice",
+    "Span",
+    "Strike",
+    "StyledBlock",
+    "Subscript",
+    "Superscript",
+    "Tab",
+    "Table",
+    "Tabs",
+    "Task",
+    "Term",
+    "TermDefinition",
+    "Text",
+    "Toc",
+    "Underline",
+    "UnsupportedFeatureError",
+    "Variable",
+    "Video",
+    "Visibility",
+    "WikiInclude",
+    "YFMTable",
+    "parse",
+]

markstitch/attributes.py

@@ -0,0 +1,56 @@
+"""Typed presentation attributes for Diplodoc tables."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from markstitch.core import identifier, one_line
+
+
+@dataclass(frozen=True)
+class Attributes:
+    """Presentation chosen by the document author; classes/style must be trusted, not user input."""
+
+    id: str | None = None
+    classes: tuple[str, ...] = ()
+    style: Mapping[str, str] = field(default_factory=dict)
+    extra: Mapping[str, str] = field(default_factory=dict)
+
+    def to_yfm(self) -> str:
+        values: dict[str, str] = {}
+
+        if self.id is not None:
+            values["id"] = identifier(self.id)
+
+        if self.classes:
+            values["class"] = " ".join(identifier(name) for name in self.classes)
+
+        if self.style:
+            values["style"] = "; ".join(self._declaration(name, value) for name, value in self.style.items())
+
+        for name, value in self.extra.items():
+            if not re.fullmatch(r"(?:data-|aria-)[a-z][a-z0-9-]*|title", name):
+                raise ValueError("Extra attributes must be data-*, aria-* or title")
+
+            values[name] = self._value(value)
+
+        return " ".join(f'{name}="{value}"' for name, value in values.items())
+
+    @staticmethod
+    def _value(value: str) -> str:
+        one_line(value)
+
+        if any(character in value for character in "\\\"'{}|<>&"):
+            raise ValueError("Attribute value contains a markup delimiter")
+
+        return value
+
+    @classmethod
+    def _declaration(cls, name: str, value: str) -> str:
+        if not re.fullmatch(r"[a-z][a-z-]*|--[a-z][a-z0-9-]*", name):
+            raise ValueError("Invalid CSS property name")
+
+        if not value or not re.fullmatch(r"[\w\s#.,%+/-]+", value) or "/*" in value or "*/" in value:
+            raise ValueError("Expected a CSS keyword, color or dimension without functions or delimiters")
+
+        return f"{name}: {cls._value(value)}"

markstitch/blocks.py

@@ -0,0 +1,236 @@
+"""Block-level YFM constructs."""
+
+from dataclasses import dataclass
+
+from markstitch.core import (
+    MAX_HEADING_LEVEL,
+    Container,
+    Element,
+    Profile,
+    blocks,
+    choice,
+    directive,
+    escape,
+    fence,
+    identifier,
+    indent,
+    inline,
+    one_line,
+    positive,
+    prefix_lines,
+    quoted,
+    render,
+    require,
+)
+from markstitch.inline import render_text
+
+CODE_FLAGS = {"showLineNumbers": "line_numbers", "wrap": "wrap"}
+CODE_PROMPT = "prompt"
+
+
+class Paragraph(Container):
+    def _render(self, profile: Profile) -> str:
+        return render_text(self.children, profile)
+
+
+@dataclass
+class Heading(Element):
+    _child_fields = ("text",)
+
+    text: Element | str
+    level: int = 1
+    anchor: str | None = None
+    collapsible: bool = False
+
+    def _render(self, profile: Profile) -> str:
+        if positive(self.level, "level") > MAX_HEADING_LEVEL:
+            raise ValueError(f"Heading level must be between 1 and {MAX_HEADING_LEVEL}")
+
+        if self.collapsible:
+            require(profile, "Collapsible heading", Profile.TRACKER, Profile.WIKI)
+
+        anchor = f" {{#{identifier(self.anchor)}}}" if self.anchor else ""
+        collapse = "+" if self.collapsible else ""
+        return f"{'#' * self.level}{collapse} {one_line(inline(self.text, profile))}{anchor}"
+
+
+class FixedHeading(Heading):
+    LEVEL = 1
+
+    def __init__(self, text: Element | str, *, anchor: str | None = None, collapsible: bool = False) -> None:
+        super().__init__(text=text, level=self.LEVEL, anchor=anchor, collapsible=collapsible)
+
+
+class Header1(FixedHeading):
+    LEVEL = 1
+
+
+class Header2(FixedHeading):
+    LEVEL = 2
+
+
+class Header3(FixedHeading):
+    LEVEL = 3
+
+
+class Header4(FixedHeading):
+    LEVEL = 4
+
+
+class Header5(FixedHeading):
+    LEVEL = 5
+
+
+class Header6(FixedHeading):
+    LEVEL = 6
+
+
+class BulletList(Container):
+    def __init__(self, *children: Element | str, loose: bool = False) -> None:
+        super().__init__(*children)
+        self.loose = loose
+
+    def _render(self, profile: Profile) -> str:
+        separator = "\n\n" if self.loose else "\n"
+        return separator.join(prefix_lines(render(child, profile), "- ") for child in self.children)
+
+
+class ListItem(Container):
+    def _render(self, profile: Profile) -> str:
+        return blocks(self.children, profile)
+
+
+class Quote(Container):
+    def _render(self, profile: Profile) -> str:
+        return "\n".join(f"> {line}" if line else ">" for line in blocks(self.children, profile).split("\n"))
+
+
+@dataclass
+class CodeBlock(Element):
+    text: str
+    language: str = ""
+    line_numbers: bool = False
+    wrap: bool = False
+    prompt: str | None = None
+
+    def _render(self, profile: Profile) -> str:
+        if self.language:
+            identifier(self.language)
+
+        delimiter = fence(self.text)
+        flags = "".join(f" {name}" for name, field in CODE_FLAGS.items() if getattr(self, field))
+        prompt = ""
+
+        if self.prompt is not None:
+            require(profile, "Code prompt", Profile.DIPLODOC)
+            prompt = f" {CODE_PROMPT}={quoted(self.prompt)}"
+
+        newline = "" if self.text.endswith("\n") else "\n"
+        return f"{delimiter}{self.language}{flags}{prompt}\n{self.text}{newline}{delimiter}"
+
+
+@dataclass
+class MathBlock(Element):
+    text: str
+
+    def _render(self, profile: Profile) -> str:
+        if "$$" in self.text:
+            raise ValueError("Math block must not contain a closing delimiter")
+
+        return f"$$\n{self.text}\n$$"
+
+
+class Rule(Element):
+    def _render(self, profile: Profile) -> str:
+        return "---"
+
+
+@dataclass
+class Comment(Element):
+    text: str
+
+    def _render(self, profile: Profile) -> str:
+        return f"[//]: # ({escape(one_line(self.text))})"
+
+
+class Cut(Container):
+    def __init__(self, title: str, *children: Element | str) -> None:
+        super().__init__(*children)
+        self.title = title
+
+    def _render(self, profile: Profile) -> str:
+        return directive("cut", blocks(self.children, profile), arguments=quoted(self.title))
+
+
+class Note(Container):
+    def __init__(self, *children: Element | str, kind: str = "info", title: str | None = None) -> None:
+        super().__init__(*children)
+        self.kind = kind
+        self.title = title
+
+    def _render(self, profile: Profile) -> str:
+        choice(self.kind, {"info", "tip", "warning", "alert"}, "note kind")
+        title = f" {quoted(self.title)}" if self.title is not None else ""
+        return directive("note", blocks(self.children, profile), arguments=f"{self.kind}{title}")
+
+
+class Tab(Container):
+    def __init__(self, title: str, *children: Element | str, selected: bool = False) -> None:
+        super().__init__(*children)
+        self.title = title
+        self.selected = selected
+
+    def _render(self, profile: Profile) -> str:
+        selected = ""
+
+        if self.selected:
+            require(profile, "Selected tab", Profile.DIPLODOC)
+            selected = " {selected}"
+
+        return f"- {escape(one_line(self.title))}{selected}\n\n{indent(blocks(self.children, profile), 2)}"
+
+
+class Tabs(Container):
+    def __init__(self, *children: Tab, mode: str = "tabs", group: str | None = None) -> None:
+        super().__init__(*children)
+        self.mode, self.group = mode, group
+
+    def _render(self, profile: Profile) -> str:
+        if not self.children or any(not isinstance(child, Tab) for child in self.children):
+            raise TypeError("Tabs requires one or more Tab elements")
+
+        choice(self.mode, {"tabs", "radio", "dropdown", "accordion"}, "tabs mode")
+        mode = ""
+        group = ""
+
+        if self.mode != "tabs":
+            require(profile, "Interactive tabs mode", Profile.DIPLODOC)
+            mode = f" {self.mode}"
+
+        if self.group is not None:
+            require(profile, "Tabs synchronization", Profile.DIPLODOC)
+            group = f" group={identifier(self.group)}"
+
+        return directive("list", blocks(self.children, profile), arguments=f"tabs{mode}{group}", end="endlist")
+
+
+@dataclass
+class Task(Element):
+    _child_fields = ("text",)
+
+    text: Element | str
+    checked: bool = False
+
+    def _render(self, profile: Profile) -> str:
+        prefix = "- " if profile == Profile.DIPLODOC else ""
+        check = "x" if self.checked else " "
+        return f"{prefix}[{check}] {one_line(inline(self.text, profile))}"
+
+
+class Checklist(Container):
+    def _render(self, profile: Profile) -> str:
+        if any(not isinstance(child, Task) for child in self.children):
+            raise TypeError("Checklist requires Task elements")
+
+        separator = "\n" if profile == Profile.DIPLODOC else "\n\n"
+        return separator.join(render(child, profile) for child in self.children)

markstitch/core.py

@@ -0,0 +1,245 @@
+"""Document nodes and rendering contract."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Collection, Iterator
+from enum import StrEnum
+from html import escape as html_escape
+from typing import ClassVar
+from urllib.parse import quote, urlsplit
+
+MAX_HEADING_LEVEL = 6
+
+
+class Profile(StrEnum):
+    TRACKER = "tracker"
+    WIKI = "wiki"
+    DIPLODOC = "diplodoc"
+
+
+class UnsupportedFeatureError(ValueError):
+    """The selected target does not document support for this feature."""
+
+
+class Element:
+    _child_fields: ClassVar[tuple[str, ...]] = ()
+
+    def __iter__(self) -> Iterator[Element]:
+        return self.iter_children()
+
+    def __str__(self) -> str:
+        return self.to_yfm()
+
+    def to_yfm(self, *, profile: Profile | str = Profile.TRACKER) -> str:
+        return self._render(Profile(profile))
+
+    def iter_children(self) -> Iterator[Element]:
+        """Yield direct element children; scalar text and metadata remain on their owner."""
+        pending = [getattr(self, name) for name in reversed(self._child_fields)]
+
+        while pending:
+            child = pending.pop()
+
+            if isinstance(child, Element):
+                yield child
+            elif isinstance(child, (tuple, list)):
+                pending.extend(reversed(child))
+
+    def walk(self) -> Iterator[Element]:
+        """Depth-first preorder, including self. Shared nodes are visited per occurrence."""
+        pending: list[tuple[Element, bool]] = [(self, False)]
+        ancestors: set[int] = set()
+
+        while pending:
+            node, leaving = pending.pop()
+
+            if leaving:
+                ancestors.remove(id(node))
+                continue
+
+            if id(node) in ancestors:
+                raise ValueError("Cycle in document tree")
+
+            ancestors.add(id(node))
+            yield node
+            pending.append((node, True))
+            pending.extend((child, False) for child in reversed(tuple(node)))
+
+    def _render(self, profile: Profile) -> str:
+        raise NotImplementedError(f"{type(self).__name__} must implement _render")
+
+
+class Inline(Element):
+    """An element that can appear inside a paragraph or a link label."""
+
+
+class Container(Element):
+    _child_fields: ClassVar[tuple[str, ...]] = ("children",)
+
+    def __init__(self, *children: Element | str) -> None:
+        self.children = tuple(children)
+
+
+class YFM(Container):
+    def __init__(self, *children: Element | str, profile: Profile | str = Profile.TRACKER) -> None:
+        super().__init__(*children)
+        self.profile = Profile(profile)
+
+    @classmethod
+    def from_yfm(cls, source: str, *, profile: Profile | str = Profile.TRACKER, strict: bool = False) -> YFM:
+        # Lazy import breaks the parser <-> document node dependency.
+        from markstitch.parser import parse  # noqa: PLC0415 — parser imports the document model.
+
+        return parse(source, profile=profile, strict=strict)
+
+    def to_yfm(self, *, profile: Profile | str | None = None) -> str:
+        return self._render(self.profile if profile is None else Profile(profile))
+
+    def _render(self, profile: Profile) -> str:
+        return blocks(self.children, profile)
+
+
+class NumberedList(Container):
+    def __init__(self, *children: Element | str, start: int = 1, loose: bool = False) -> None:
+        super().__init__(*children)
+        self.start = start
+        self.loose = loose
+
+    def _render(self, profile: Profile) -> str:
+        positive(self.start, "start")
+        separator = "\n\n" if self.loose else "\n"
+        return separator.join(
+            prefix_lines(render(child, profile), f"{number}. ")
+            for number, child in enumerate(self.children, start=self.start)
+        )
+
+
+class Link(Inline):
+    _child_fields = ("text",)
+
+    def __init__(self, text: Inline | str, href: str, *, title: str | None = None, target: str | None = None) -> None:
+        self.text = text
+        self.href = href
+        self.title = title
+        self.target = target
+
+    def _render(self, profile: Profile) -> str:
+        title = f" {quoted(self.title)}" if self.title is not None else ""
+        target = ""
+
+        if self.target is not None:
+            require(profile, "Link target", Profile.DIPLODOC)
+            choice(self.target, {"_blank", "_self"}, "target")
+            target = f"{{target={self.target}}}"
+
+        return f"[{inline(self.text, profile)}]({destination(self.href)}{title}){target}"
+
+
+def render(value: Element | str, profile: Profile) -> str:
+    if isinstance(value, Element):
+        return value._render(profile)
+
+    if isinstance(value, str):
+        return escape(value)
+
+    raise TypeError(f"Expected an Element or str, got {type(value).__name__}")
+
+
+def blocks(values: tuple[Element | str, ...], profile: Profile) -> str:
+    return "\n\n".join(render(value, profile) for value in values)
+
+
+def inline(value: Element | str, profile: Profile) -> str:
+    if not isinstance(value, (Inline, str)):
+        raise TypeError("Block content cannot be used inline")
+
+    return render(value, profile)
+
+
+def require(profile: Profile, feature: str, *supported: Profile) -> None:
+    if profile not in supported:
+        raise UnsupportedFeatureError(f"{feature} is not supported by the {profile.value} profile")
+
+
+def one_line(text: str) -> str:
+    if any(ord(character) < 32 or ord(character) == 127 for character in text):
+        raise ValueError("Expected single-line text without control characters")
+
+    return text
+
+
+def identifier(text: str) -> str:
+    if not re.fullmatch(r"[\w.-]+", text):
+        raise ValueError(f"Invalid identifier: {text!r}")
+
+    return text
+
+
+def reference_label(text: str) -> str:
+    if not text.strip() or len(text) > 999:
+        raise ValueError("Reference label must contain 1 to 999 characters")
+
+    normalized = one_line(" ".join(text.split()))
+
+    if not re.fullmatch(r"(?:\\.|[^\[\]\\])+", normalized):
+        raise ValueError("Reference label must escape brackets and backslashes")
+
+    return normalized
+
+
+def positive(value: int, name: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer")
+
+    return value
+
+
+def choice(value: str, options: Collection[str], name: str) -> str:
+    if value not in options:
+        raise ValueError(f"Invalid {name}: {value!r}; expected one of {sorted(options)}")
+
+    return value
+
+
+def quoted(text: str) -> str:
+    value = html_escape(one_line(text), quote=True).replace("\\", "&#92;").replace("%", "&#37;").replace("{", "&#123;")
+    return f'"{value}"'
+
+
+def directive(name: str, body: str, *, arguments: str = "", end: str | None = None) -> str:
+    suffix = f" {arguments}" if arguments else ""
+    return f"{{% {name}{suffix} %}}\n\n{body}\n\n{{% {end or f'end{name}'} %}}"
+
+
+def indent(text: str, width: int) -> str:
+    return "\n".join(f"{' ' * width}{line}" if line else "" for line in text.split("\n"))
+
+
+def prefix_lines(text: str, prefix: str) -> str:
+    first, separator, rest = text.partition("\n")
+    return f"{prefix}{first}" + (f"\n{indent(rest, len(prefix))}" if separator else "")
+
+
+def fence(text: str, minimum: int = 3) -> str:
+    return "`" * max(minimum, max((len(run) + 1 for run in re.findall(r"`+", text)), default=0))
+
+
+def escape(text: str) -> str:
+    special = frozenset("\\`*_[](){}#|~^+=<>!$@:")
+    escaped = "".join(
+        f"\\{character}" if character in special else character for character in text.replace("&", "&amp;")
+    )
+    escaped = re.sub(r"(?m)^([ \t]*\d+)\.", r"\1\\.", escaped)
+    return re.sub(r"(?m)^([ \t]*)-", r"\1\\-", escaped)
+
+
+def destination(href: str) -> str:
+    if any(ord(character) < 32 or ord(character) == 127 for character in href):
+        raise ValueError("URL must not contain control characters")
+
+    if urlsplit(href).scheme.lower() not in {"", "http", "https", "mailto"}:
+        raise ValueError("Unsupported URL scheme")
+
+    encoded = quote(href, safe="/:?#@!$&'*+,;=%~._-")
+    return re.sub(r"&(?=(?:#\d+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]+);)", "%26", encoded)