markitup-py 0.3.1__py3-none-any.whl

markitup/__init__.py

@@ -0,0 +1,45 @@
+"""MarkItUp — markdown -> docx/pdf/html, the reverse of Microsoft's MarkItDown.
+
+Quick start:
+
+    from markitup import MarkItUp
+    MarkItUp(theme="report").convert("doc.md", "doc.pdf")
+
+Pipeline:  markdown --parse--> IR --render--> .docx / .pdf / .html
+All visual decisions live in a Theme; the renderers are mechanical.
+"""
+import os
+
+from .api import MarkItUp
+from .theme import Theme, Watermark, Banner, Table, make_watermark
+from .parse import parse
+from .render_docx import render as render_docx
+from .render_html import render_html
+from .render_pdf import render_pdf
+from .stamp import stamp
+from .fonts import list_fonts, available_fonts, is_available, SAFE_FONTS
+
+__version__ = "0.3.1"
+__all__ = [
+    "MarkItUp", "Theme", "Watermark", "Banner", "Table",
+    "parse", "render_docx", "render_html", "render_pdf",
+    "stamp", "convert",
+    "list_fonts", "available_fonts", "is_available", "SAFE_FONTS",
+]
+
+
+def convert(markdown_text: str, out_path: str, theme="report",
+            base_url: str = ".", pdf_engine: str = "weasyprint") -> str:
+    """One-shot helper: markdown string -> file (format from extension)."""
+    doc = parse(markdown_text)
+    th = theme if isinstance(theme, Theme) else Theme.load(theme)
+    ext = os.path.splitext(out_path)[1].lower()
+    if ext == ".docx":
+        return render_docx(doc, th, out_path)
+    if ext == ".pdf":
+        return render_pdf(doc, th, out_path, engine=pdf_engine, base_url=base_url)
+    if ext in (".html", ".htm"):
+        with open(out_path, "w", encoding="utf-8") as fh:
+            fh.write(render_html(doc, th))
+        return out_path
+    raise ValueError(f"unsupported output extension: {ext!r}")

markitup/api.py

@@ -0,0 +1,145 @@
+"""The public, configured entry point: the MarkItUp class.
+
+Mirrors the ergonomics of Microsoft's MarkItDown — construct once with your
+preferences, then convert many files:
+
+    from markitup import MarkItUp, Watermark
+    m = MarkItUp(theme="report", body_font="Georgia", text_color="#222")
+    m.convert("doc.md", "doc.pdf")
+    m.convert("doc.md")            # -> ./doc.docx (current working directory)
+
+Every visual knob is optional and overrides the chosen theme.
+"""
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional, Union
+
+from .theme import Theme, Banner, Watermark, make_watermark, norm_hex
+from .parse import parse
+from .render_docx import render as _render_docx
+from .render_html import render_html as _render_html
+from .render_pdf import render_pdf as _render_pdf
+from . import stamp as _stamp_mod
+
+
+class MarkItUp:
+    def __init__(
+        self,
+        theme: Union[str, Theme] = "report",
+        *,
+        # fonts
+        body_font: Optional[str] = None,
+        heading_font: Optional[str] = None,
+        mono_font: Optional[str] = None,
+        # colors (accept '#RRGGBB' or 'RRGGBB')
+        text_color: Optional[str] = None,
+        heading_color: Optional[str] = None,
+        heading_colors: Optional[Dict[int, str]] = None,
+        accent_color: Optional[str] = None,
+        link_color: Optional[str] = None,
+        # type & page
+        base_size: Optional[float] = None,
+        line_height: Optional[float] = None,
+        scale: Optional[float] = None,
+        page_size: Optional[str] = None,
+        margin_cm: Optional[float] = None,
+        # structure & marks
+        base_docx: Optional[str] = None,
+        watermark: Union[Watermark, str, dict, None] = None,
+        banner: Union[Banner, str, dict, None] = None,
+        # pdf
+        pdf_engine: str = "weasyprint",
+    ):
+        th = theme if isinstance(theme, Theme) else Theme.load(theme)
+
+        if body_font:
+            th.fonts.body = body_font
+        if heading_font:
+            th.fonts.heading = heading_font
+        if mono_font:
+            th.fonts.mono = mono_font
+
+        if text_color:
+            th.colors.text = norm_hex(text_color)
+        if heading_color:
+            th.colors.heading = norm_hex(heading_color)
+        if accent_color:
+            th.colors.accent = norm_hex(accent_color)
+        if link_color:
+            th.colors.link = norm_hex(link_color)
+        if heading_colors:
+            th.colors.headings.update({int(k): norm_hex(v) for k, v in heading_colors.items()})
+
+        if base_size is not None:
+            th.type.base_size = base_size
+        if line_height is not None:
+            th.type.line_height = line_height
+        if scale is not None:
+            th.type.ratio = scale
+        if page_size:
+            th.page.size = page_size
+        if margin_cm is not None:
+            th.page.margin_cm = margin_cm
+
+        if base_docx:
+            th.base_docx = base_docx
+        if watermark is not None:
+            th.watermark = make_watermark(watermark)
+        if banner is not None:
+            th.banner = _coerce_banner(banner)
+
+        self.theme = th
+        self.pdf_engine = pdf_engine
+
+    # ---- conversion -------------------------------------------------------
+    def convert(self, input_path: str, output_path: Optional[str] = None,
+                *, to: str = "docx") -> str:
+        """Convert a markdown file. If `output_path` is omitted, the output is
+        written to the current working directory as <input-stem>.<to>."""
+        with open(input_path, "r", encoding="utf-8") as fh:
+            md = fh.read()
+        if output_path is None:
+            stem = os.path.splitext(os.path.basename(input_path))[0]
+            output_path = os.path.join(os.getcwd(), f"{stem}.{to.lstrip('.')}")
+        base_url = os.path.dirname(os.path.abspath(input_path)) or "."
+        return self.convert_text(md, output_path, base_url=base_url)
+
+    def convert_text(self, markdown_text: str, output_path: str,
+                     *, base_url: str = ".") -> str:
+        """Convert a markdown string to the file at output_path (format from ext)."""
+        doc = parse(markdown_text)
+        ext = os.path.splitext(output_path)[1].lower()
+        if ext == ".docx":
+            return _render_docx(doc, self.theme, output_path)
+        if ext == ".pdf":
+            return _render_pdf(doc, self.theme, output_path,
+                               engine=self.pdf_engine, base_url=base_url)
+        if ext in (".html", ".htm"):
+            with open(output_path, "w", encoding="utf-8") as fh:
+                fh.write(_render_html(doc, self.theme))
+            return output_path
+        raise ValueError(f"unsupported output extension: {ext!r}")
+
+    # ---- existing-file watermarking --------------------------------------
+    @staticmethod
+    def stamp(input_path: str, output_path: str, watermark, **kwargs) -> str:
+        """Watermark an existing .pdf/.docx. See markitup.stamp for options."""
+        return _stamp_mod.stamp(input_path, output_path, watermark, **kwargs)
+
+
+def _coerce_banner(value) -> Optional[Banner]:
+    if value is None:
+        return None
+    if isinstance(value, Banner):
+        b = value
+    elif isinstance(value, str):
+        b = Banner(text=value)
+    elif isinstance(value, dict):
+        b = Banner(**value)
+    else:
+        raise TypeError(f"banner must be Banner | str | dict | None, got {type(value)!r}")
+    b.color = norm_hex(b.color)
+    if b.bg:
+        b.bg = norm_hex(b.bg)
+    return b

markitup/cli.py

@@ -0,0 +1,131 @@
+"""Command-line interface: `markitup <command>`.
+
+    markitup convert in.md -o out.pdf --theme report --font Georgia
+    markitup convert in.md --banner "CONFIDENTIAL" --watermark DRAFT
+    markitup fonts
+    markitup stamp report.pdf -o stamped.pdf --watermark CONFIDENTIAL --position top
+    markitup stamp report.docx -o stamped.docx --watermark-image logo.png
+
+If the first argument is a file path (not a command), `convert` is assumed.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .api import MarkItUp
+from .stamp import stamp as stamp_file
+from .fonts import list_fonts
+
+_COMMANDS = {"convert", "fonts", "stamp"}
+
+
+def _add_style_args(p):
+    p.add_argument("--theme", default="report", help="theme name or path to a theme .yaml")
+    p.add_argument("--font", help="body font for the whole document")
+    p.add_argument("--heading-font", help="font for headings")
+    p.add_argument("--mono-font", help="font for code")
+    p.add_argument("--text-color", help="body text color (#RRGGBB)")
+    p.add_argument("--heading-color", help="heading color (#RRGGBB)")
+    p.add_argument("--accent-color", help="accent color (#RRGGBB)")
+    p.add_argument("--base-docx", help="reference .docx whose styles define the design")
+    p.add_argument("--banner", help="top-of-document notice, e.g. CONFIDENTIAL")
+    p.add_argument("--watermark", help="text watermark")
+    p.add_argument("--watermark-image", help="image watermark (path)")
+    p.add_argument("--position", default="center", choices=["center", "top", "bottom"])
+    p.add_argument("--pdf-engine", default="weasyprint", choices=["weasyprint", "chromium"])
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] not in _COMMANDS and not argv[0].startswith("-"):
+        argv = ["convert"] + argv  # default command
+
+    ap = argparse.ArgumentParser(prog="markitup", description="Markdown -> docx/pdf/html")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    c = sub.add_parser("convert", help="convert a markdown file")
+    c.add_argument("input", help="path to a .md file")
+    c.add_argument("-o", "--output", help="output path (.docx/.pdf/.html); default: ./<name>.docx")
+    c.add_argument("--to", default="docx", help="format when no -o given (docx/pdf/html)")
+    _add_style_args(c)
+
+    sub.add_parser("fonts", help="list fonts available for rendering")
+
+    s = sub.add_parser("stamp", help="watermark an existing .pdf/.docx")
+    s.add_argument("input", help="existing .pdf or .docx")
+    s.add_argument("-o", "--output", required=True, help="output path")
+    s.add_argument("--watermark", help="text watermark")
+    s.add_argument("--watermark-image", help="image watermark (path)")
+    s.add_argument("--position", default="center", choices=["center", "top", "bottom"])
+    s.add_argument("--opacity", type=float, default=0.10)
+    s.add_argument("--rotation", type=int, default=-45)
+    s.add_argument("--pages", default="all", help="e.g. all | 1,3 | 2-5 (PDF only)")
+    s.add_argument("--password", help="password for an encrypted PDF")
+    s.add_argument("--in-front", action="store_true", help="draw over content instead of behind")
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "fonts":
+        return _cmd_fonts()
+    if args.cmd == "stamp":
+        return _cmd_stamp(args)
+    return _cmd_convert(args)
+
+
+def _cmd_fonts():
+    info = list_fonts()
+    installed = info["installed"]
+    print(f"Installed fonts available for PDF rendering ({len(installed)}):")
+    for f in installed:
+        print(f"  {f}")
+    if not installed:
+        print("  (fontconfig not available on this machine)")
+    print("\nCross-platform-safe families recommended for .docx:")
+    for group, fams in info["safe"].items():
+        print(f"  {group:5}: {', '.join(fams)}")
+    return 0
+
+
+def _cmd_convert(args):
+    if not os.path.isfile(args.input):
+        print(f"input file not found: {args.input}", file=sys.stderr)
+        return 2
+    wm = None
+    if args.watermark_image:
+        wm = {"image": args.watermark_image, "position": args.position}
+    elif args.watermark:
+        wm = {"text": args.watermark, "position": args.position}
+    m = MarkItUp(
+        theme=args.theme,
+        body_font=args.font, heading_font=args.heading_font, mono_font=args.mono_font,
+        text_color=args.text_color, heading_color=args.heading_color, accent_color=args.accent_color,
+        base_docx=args.base_docx, watermark=wm, banner=args.banner,
+        pdf_engine=args.pdf_engine,
+    )
+    out = m.convert(args.input, args.output, to=args.to)
+    print(f"Wrote {out}")
+    return 0
+
+
+def _cmd_stamp(args):
+    if not os.path.isfile(args.input):
+        print(f"input file not found: {args.input}", file=sys.stderr)
+        return 2
+    if args.watermark_image:
+        wm = {"image": args.watermark_image}
+    elif args.watermark:
+        wm = {"text": args.watermark}
+    else:
+        print("provide --watermark or --watermark-image", file=sys.stderr)
+        return 2
+    wm.update({"position": args.position, "opacity": args.opacity, "rotation": args.rotation})
+    out = stamp_file(args.input, args.output, wm,
+                     password=args.password, behind=not args.in_front, pages=args.pages)
+    print(f"Wrote {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

markitup/fonts.py

@@ -0,0 +1,61 @@
+"""Font discovery.
+
+Two different realities to be honest about:
+
+* **PDF** is rendered *here* (WeasyPrint/Chromium), so a font only works if it is
+  installed on this machine. `available_fonts()` queries the system via
+  fontconfig and tells you what will actually render.
+* **DOCX** does not embed fonts by default — it stores a font *name* and Word
+  substitutes whatever the reader has installed. So for docx, prefer widely
+  available families. `SAFE_FONTS` lists cross-platform-safe choices.
+
+`list_fonts()` returns both so callers can make an informed choice.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Dict, List
+
+# Families that ship on virtually all Windows/macOS systems (safe for docx).
+SAFE_FONTS: Dict[str, List[str]] = {
+    "serif": ["Times New Roman", "Georgia", "Cambria", "Garamond", "Book Antiqua"],
+    "sans": ["Calibri", "Arial", "Helvetica", "Verdana", "Tahoma", "Trebuchet MS", "Segoe UI"],
+    "mono": ["Consolas", "Courier New", "Lucida Console"],
+}
+
+
+def available_fonts() -> List[str]:
+    """Font families installed on THIS machine (what PDF rendering can use).
+    Returns a sorted, de-duplicated list. Empty if fontconfig is unavailable."""
+    if not shutil.which("fc-list"):
+        return []
+    try:
+        out = subprocess.run(
+            ["fc-list", ":", "family"], capture_output=True, text=True, timeout=10
+        ).stdout
+    except Exception:
+        return []
+    fams = set()
+    for line in out.splitlines():
+        # a line may list comma-separated localized aliases; take the first
+        name = line.split(",")[0].strip()
+        if name:
+            fams.add(name)
+    return sorted(fams, key=str.lower)
+
+
+def list_fonts() -> Dict[str, object]:
+    """Everything a caller needs to choose a font.
+
+    Returns: {"installed": [...], "safe": {...}}
+      - installed: families available for PDF rendering on this machine
+      - safe: curated cross-platform families recommended for .docx
+    """
+    return {"installed": available_fonts(), "safe": SAFE_FONTS}
+
+
+def is_available(family: str) -> bool:
+    """True if `family` is installed locally (relevant for PDF)."""
+    family_l = family.lower()
+    return any(f.lower() == family_l for f in available_fonts())

markitup/ir.py

@@ -0,0 +1,122 @@
+"""Intermediate Representation (IR) for MarkItUp.
+
+The IR is the contract between parsing and rendering. The parser produces a tree
+of these nodes from markdown; every renderer (docx, pdf, ...) consumes the same
+tree. Nodes carry *structure and intent only* — never visual styling. All visual
+decisions live in the Theme.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+# --- base -------------------------------------------------------------------
+class Node:
+    """Marker base class for all IR nodes."""
+
+
+# --- inline nodes -----------------------------------------------------------
+@dataclass
+class Text(Node):
+    content: str
+
+
+@dataclass
+class Strong(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class Emphasis(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class Strike(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class InlineCode(Node):
+    content: str
+
+
+@dataclass
+class Link(Node):
+    href: str
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class Image(Node):
+    src: str
+    alt: str = ""
+
+
+@dataclass
+class LineBreak(Node):
+    pass
+
+
+# --- block nodes ------------------------------------------------------------
+@dataclass
+class Heading(Node):
+    level: int                      # 1..6
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class Paragraph(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class CodeBlock(Node):
+    content: str
+    lang: Optional[str] = None
+
+
+@dataclass
+class BlockQuote(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class ListItem(Node):
+    children: List[Node] = field(default_factory=list)
+
+
+@dataclass
+class ListNode(Node):
+    ordered: bool = False
+    start: int = 1
+    items: List[ListItem] = field(default_factory=list)
+
+
+@dataclass
+class TableCell(Node):
+    children: List[Node] = field(default_factory=list)
+    align: str = "left"            # left | center | right
+
+
+@dataclass
+class TableRow(Node):
+    cells: List[TableCell] = field(default_factory=list)
+
+
+@dataclass
+class Table(Node):
+    header: Optional[TableRow] = None
+    rows: List[TableRow] = field(default_factory=list)
+
+
+@dataclass
+class ThematicBreak(Node):
+    pass
+
+
+@dataclass
+class Document(Node):
+    children: List[Node] = field(default_factory=list)
+    title: Optional[str] = None     # populated from first H1 if present