mddoco 2.0.1__tar.gz → 2.0.3__tar.gz

{mddoco-2.0.1/src/mddoco.egg-info → mddoco-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mddoco
-Version: 2.0.1
+Version: 2.0.3
 Summary: Markdown to HTML/PDF document converter
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -10,6 +10,10 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: jinja2>=3.1
 Requires-Dist: playwright>=1.40
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # mddoco
@@ -20,17 +24,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 

{mddoco-2.0.1 → mddoco-2.0.3}/README.md

@@ -6,17 +6,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 

{mddoco-2.0.1 → mddoco-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mddoco"
-version = "2.0.1"
+version = "2.0.3"
 description = "Markdown to HTML/PDF document converter"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,6 +16,13 @@ dependencies = [
     "matplotlib>=3.7",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "black>=24.0",
+    "ruff>=0.16,<0.17",
+]
+
 [project.scripts]
 mddoco = "mddoco.cli:main"
 
@@ -25,9 +32,16 @@ where = ["src"]
 [tool.setuptools.package-data]
 mddoco = ["themes/*.html"]
 
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
 [tool.ruff]
 src = ["src"]
 line-length = 88
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mddoco-2.0.3/src/mddoco/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.3"

{mddoco-2.0.1 → mddoco-2.0.3}/src/mddoco/cli.py

@@ -15,31 +15,40 @@ from mddoco.writer import write_output
 @click.command()
 @click.argument("input_path", type=click.Path(exists=True, path_type=Path))
 @click.option(
-    "--output", "-o", "output_path",
-    default=".", show_default=True,
+    "--output",
+    "-o",
+    "output_path",
+    default=".",
+    show_default=True,
     type=click.Path(path_type=Path),
     help="Output directory, or explicit output file path.",
 )
 @click.option(
-    "--format", "-f", "fmt",
-    default="html", show_default=True,
+    "--format",
+    "-f",
+    "fmt",
+    default="html",
+    show_default=True,
     type=click.Choice(["html", "pdf"], case_sensitive=False),
     help="Output format.",
 )
 @click.option("--title", "-t", default=None, help="Document title.")
 @click.option(
     "--theme",
-    default="default", show_default=True,
+    default="default",
+    show_default=True,
     help="Theme name to use for rendering.",
 )
 @click.option(
     "--toc/--no-toc",
-    default=False, show_default=True,
+    default=False,
+    show_default=True,
     help="Generate a table of contents.",
 )
 @click.option(
     "--toc-depth",
-    default=3, show_default=True,
+    default=3,
+    show_default=True,
     type=click.IntRange(1, 6),
     help="Maximum heading depth included in the TOC.",
 )

{mddoco-2.0.1 → mddoco-2.0.3}/src/mddoco/graph.py

@@ -6,84 +6,105 @@ import re
 from html import unescape
 
 import matplotlib
-matplotlib.use('Agg')  # non-interactive backend — must be set before importing pyplot
+
+matplotlib.use("Agg")  # non-interactive backend — must be set before importing pyplot
 import matplotlib.pyplot as plt
 
 log = logging.getLogger(__name__)
 
-_JSON_TO_PY = re.compile(r'\b(true|false|null)\b')
-_JSON_TO_PY_MAP = {'true': 'True', 'false': 'False', 'null': 'None'}
+_JSON_TO_PY = re.compile(r"\b(true|false|null)\b")
+_JSON_TO_PY_MAP = {"true": "True", "false": "False", "null": "None"}
 
 _DEFAULT_COLOURS = [
-    '#2d6cbe', '#e74c3c', '#27ae60', '#e67e22',
-    '#8e44ad', '#16a085', '#2c3e50', '#d35400',
+    "#2d6cbe",
+    "#e74c3c",
+    "#27ae60",
+    "#e67e22",
+    "#8e44ad",
+    "#16a085",
+    "#2c3e50",
+    "#d35400",
 ]
 
 
 def graph_it(data, output=None):
     dpi = 100
-    width_px = data.get('width_px', 640)
-    height_px = data.get('height_px', 480)
+    width_px = data.get("width_px", 640)
+    height_px = data.get("height_px", 480)
     fig, ax = plt.subplots(figsize=(width_px / dpi, height_px / dpi), dpi=dpi)
 
-    orientation = data.get('orientation', 'vertical').lower()
-    if orientation not in ('horizontal', 'vertical'):
+    orientation = data.get("orientation", "vertical").lower()
+    if orientation not in ("horizontal", "vertical"):
         raise ValueError(
             f"Invalid orientation '{orientation}' — must be 'horizontal' or 'vertical'"
         )
-    horizontal = orientation == 'horizontal'
+    horizontal = orientation == "horizontal"
 
-    x = data['data']['x']
+    x = data["data"]["x"]
 
     # Auto-generate series from data keys (everything except 'x') if not provided
-    series_list = data.get('series') or [
-        {'label': k} for k in data['data'] if k != 'x'
-    ]
+    series_list = data.get("series") or [{"label": k} for k in data["data"] if k != "x"]
 
     for i, series in enumerate(series_list):
-        label = series['label']
-        values = data['data'][label]
-        series_type = series.get('type', 'line')
-        colour = series.get('colour', _DEFAULT_COLOURS[i % len(_DEFAULT_COLOURS)])
+        label = series["label"]
+        values = data["data"][label]
+        series_type = series.get("type", "line")
+        colour = series.get("colour", _DEFAULT_COLOURS[i % len(_DEFAULT_COLOURS)])
 
-        if series_type == 'bar':
+        if series_type == "bar":
             colour_val = colour if isinstance(colour, list) else [colour] * len(values)
             if horizontal:
                 ax.barh(x, values, color=colour_val, label=label)
             else:
                 ax.bar(x, values, color=colour_val, label=label)
-        elif series_type in ('line', 'line2'):
-            marker = 'o' if series.get('marker', False) else 'None'
-            linestyle = ':' if series_type == 'line2' else '-'
+        elif series_type in ("line", "line2"):
+            marker = "o" if series.get("marker", False) else "None"
+            linestyle = ":" if series_type == "line2" else "-"
             if horizontal:
-                ax.plot(values, x, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
+                ax.plot(
+                    values,
+                    x,
+                    color=colour,
+                    marker=marker,
+                    linewidth=2,
+                    linestyle=linestyle,
+                    label=label,
+                )
             else:
-                ax.plot(x, values, color=colour, marker=marker, linewidth=2, linestyle=linestyle, label=label)
-
-    if 'min' in data or 'max' in data:
-        lo = data.get('min', None)
-        hi = data.get('max', None)
+                ax.plot(
+                    x,
+                    values,
+                    color=colour,
+                    marker=marker,
+                    linewidth=2,
+                    linestyle=linestyle,
+                    label=label,
+                )
+
+    if "min" in data or "max" in data:
+        lo = data.get("min", None)
+        hi = data.get("max", None)
         if horizontal:
             ax.set_xlim(lo, hi)
         else:
             ax.set_ylim(lo, hi)
 
-    title = data.get('title', '')
+    title = data.get("title", "")
     if title:
         ax.set_title(title)
 
-    if data.get('show_legend', True):
-        ax.legend(loc='upper left')
+    if data.get("show_legend", True):
+        ax.legend(loc="upper left")
 
-    ax.spines['top'].set_visible(False)
-    ax.spines['right'].set_visible(False)
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
 
     if output:
-        plt.savefig(output, format="svg", bbox_inches='tight')
+        plt.savefig(output, format="svg", bbox_inches="tight")
         plt.close(fig)
     else:
         buf = io.StringIO()
-        plt.savefig(buf, format="svg", bbox_inches='tight')
+        plt.savefig(buf, format="svg", bbox_inches="tight")
         plt.close(fig)
         return buf.getvalue()
 
@@ -93,7 +114,7 @@ _GRAPH_BLOCK = re.compile(
     re.DOTALL,
 )
 
-_SVG_HEADER = re.compile(r'^.*?(?=<svg)', re.DOTALL)
+_SVG_HEADER = re.compile(r"^.*?(?=<svg)", re.DOTALL)
 
 
 def _parse_source(source: str) -> dict:
@@ -113,7 +134,7 @@ def _render_graph(source: str) -> str:
     """Parse source, render via graph_it, and return an inline SVG element."""
     data = _parse_source(source)
     svg = graph_it(data)
-    svg = _SVG_HEADER.sub('', svg)  # strip XML declaration and DOCTYPE
+    svg = _SVG_HEADER.sub("", svg)  # strip XML declaration and DOCTYPE
     return f'<div class="graph">{svg}</div>'
 
 

mddoco-2.0.3/src/mddoco/pdf.py

@@ -0,0 +1,78 @@
+import logging
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_INSTALL_HINT = (
+    "Chromium is required for PDF output and could not be installed "
+    "automatically. Run: playwright install chromium"
+)
+
+
+def html_to_pdf(html_content: str, dest: Path) -> None:
+    """Render an HTML string to a PDF file using a headless Chromium browser.
+
+    Navigates via a temporary file:// URL so that external resources (CDN
+    scripts, Mermaid.js, etc.) load correctly before the page is printed.
+
+    The Chromium binary that Playwright drives is not shipped with the Python
+    package. The first time a PDF is rendered on a fresh machine it is
+    downloaded automatically; if that download fails the user is told how to
+    install it by hand.
+    """
+    try:
+        from playwright.sync_api import Error as PlaywrightError
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        raise RuntimeError(
+            "Playwright is required for PDF output. "
+            "Run: pip install playwright && playwright install chromium"
+        )
+
+    with tempfile.NamedTemporaryFile(
+        suffix=".html", delete=False, mode="w", encoding="utf-8"
+    ) as f:
+        f.write(html_content)
+        tmp_path = Path(f.name)
+
+    try:
+        try:
+            _render(sync_playwright, tmp_path, dest)
+        except PlaywrightError as exc:
+            if "Executable doesn't exist" not in str(exc):
+                raise
+            _install_chromium()
+            _render(sync_playwright, tmp_path, dest)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def _render(sync_playwright, source: Path, dest: Path) -> None:
+    """Drive headless Chromium to print ``source`` to ``dest`` as A4 PDF."""
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page()
+        page.goto(source.as_uri(), wait_until="networkidle")
+        # If Paged.js is present, wait for it to finish paginating before
+        # capturing — networkidle fires before its JS layout pass completes.
+        page.wait_for_function(
+            "typeof window.PagedPolyfill === 'undefined'"
+            " || !!document.querySelector('.pagedjs_pages')"
+        )
+        page.pdf(path=str(dest), format="A4", print_background=True)
+        browser.close()
+
+
+def _install_chromium() -> None:
+    """Download the Chromium binary Playwright needs, or explain how to."""
+    log.warning("Chromium not found — downloading it now (~150 MB, one time).")
+    try:
+        subprocess.run(
+            [sys.executable, "-m", "playwright", "install", "chromium"],
+            check=True,
+        )
+    except (subprocess.CalledProcessError, OSError) as exc:
+        raise RuntimeError(_INSTALL_HINT) from exc

{mddoco-2.0.1 → mddoco-2.0.3}/src/mddoco/preprocessor.py

@@ -45,29 +45,29 @@ def _parse_csv_line(line: str) -> list[tuple[str, bool]]:
                 else:
                     parts.append(line[i])
                     i += 1
-            value = ''.join(parts)
-            while i < n and line[i] != ',':
+            value = "".join(parts)
+            while i < n and line[i] != ",":
                 i += 1
             fields.append((value, True))
         else:
             start = i
-            while i < n and line[i] != ',':
+            while i < n and line[i] != ",":
                 i += 1
             fields.append((line[start:i], False))
 
-        if i < n and line[i] == ',':
+        if i < n and line[i] == ",":
             i += 1
             if i >= n:
-                fields.append(('', False))
+                fields.append(("", False))
 
     return fields
 
 
 def _apply_semicolon_split(value: str, was_quoted: bool) -> str | list[str]:
     """Return value split on ';' unless the field was originally quoted."""
-    if was_quoted or ';' not in value:
+    if was_quoted or ";" not in value:
         return value
-    return [part.strip() for part in value.split(';')]
+    return [part.strip() for part in value.split(";")]
 
 
 def load_csv_context(input_path: Path) -> dict:
@@ -99,7 +99,7 @@ def load_csv_context(input_path: Path) -> dict:
                 if idx < len(fields):
                     value, was_quoted = fields[idx]
                 else:
-                    value, was_quoted = '', False
+                    value, was_quoted = "", False
                 row[key] = _apply_semicolon_split(value, was_quoted)
             rows.append(row)
 
@@ -114,7 +114,7 @@ def load_context(input_path: Path) -> dict:
     csv_ctx = load_csv_context(input_path)
     conflicts = set(json_ctx) & set(csv_ctx)
     if conflicts:
-        names = ', '.join(sorted(conflicts))
+        names = ", ".join(sorted(conflicts))
         raise ValueError(
             f"Context name conflict — both a .json and .csv exist for: {names}"
         )

{mddoco-2.0.1 → mddoco-2.0.3/src/mddoco.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mddoco
-Version: 2.0.1
+Version: 2.0.3
 Summary: Markdown to HTML/PDF document converter
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -10,6 +10,10 @@ Requires-Dist: markdown>=3.5
 Requires-Dist: jinja2>=3.1
 Requires-Dist: playwright>=1.40
 Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff<0.17,>=0.16; extra == "dev"
 Dynamic: license-file
 
 # mddoco
@@ -20,17 +24,23 @@ A CLI tool that converts markdown files to a single HTML (or future PDF) documen
 
 ```bash
 pip install mddoco
-playwright install chromium
 ```
 
 Or for development:
 
 ```bash
 pip install -e .
-playwright install chromium
 ```
 
-> Playwright (Chromium) is required for PDF output only. HTML output works without it.
+> **Playwright (Chromium) is required for PDF output only.** HTML output works without it.
+> The `playwright` Python package is installed automatically, but the Chromium
+> browser it drives is not. The first time you render a PDF, mddoco downloads
+> Chromium for you (~150 MB, one time). To do it ahead of time, or if the
+> automatic download fails, run it yourself:
+>
+> ```bash
+> playwright install chromium
+> ```
 
 ## Usage
 

{mddoco-2.0.1 → mddoco-2.0.3}/src/mddoco.egg-info/requires.txt

@@ -3,3 +3,8 @@ markdown>=3.5
 jinja2>=3.1
 playwright>=1.40
 matplotlib>=3.7
+
+[dev]
+pytest>=8.0
+black>=24.0
+ruff<0.17,>=0.16

{mddoco-2.0.1 → mddoco-2.0.3}/tests/test_preprocessor.py

@@ -1,6 +1,8 @@
-import pytest
 from pathlib import Path
 
+import pytest
+
+import mddoco
 from mddoco.preprocessor import (
     _apply_semicolon_split,
     _parse_csv_line,
@@ -8,9 +10,16 @@ from mddoco.preprocessor import (
     load_csv_context,
 )
 
+# --- version ---
+
+
+def test_version():
+    assert mddoco.__version__ == "2.0.3"
+
 
 # --- _parse_csv_line ---
 
+
 def test_parse_csv_line_simple():
     assert _parse_csv_line("a,b,c") == [("a", False), ("b", False), ("c", False)]
 
@@ -37,12 +46,17 @@ def test_parse_csv_line_single_field():
 
 # --- _apply_semicolon_split ---
 
+
 def test_split_unquoted_with_semicolon():
     assert _apply_semicolon_split("python;flask", False) == ["python", "flask"]
 
 
 def test_split_trims_whitespace():
-    assert _apply_semicolon_split("python ; flask ; sql", False) == ["python", "flask", "sql"]
+    assert _apply_semicolon_split("python ; flask ; sql", False) == [
+        "python",
+        "flask",
+        "sql",
+    ]
 
 
 def test_no_split_when_quoted():
@@ -59,8 +73,11 @@ def test_single_element_after_split():
 
 # --- load_csv_context ---
 
+
 def test_load_csv_basic(tmp_path: Path):
-    (tmp_path / "people.csv").write_text("name,role\nAlice,Engineer\nBob,Manager\n", encoding="utf-8")
+    (tmp_path / "people.csv").write_text(
+        "name,role\nAlice,Engineer\nBob,Manager\n", encoding="utf-8"
+    )
     ctx = load_csv_context(tmp_path)
     assert ctx == {
         "people": [
@@ -71,7 +88,9 @@ def test_load_csv_basic(tmp_path: Path):
 
 
 def test_load_csv_semicolon_becomes_list(tmp_path: Path):
-    (tmp_path / "data.csv").write_text("name,skills\nAlice,python;flask\n", encoding="utf-8")
+    (tmp_path / "data.csv").write_text(
+        "name,skills\nAlice,python;flask\n", encoding="utf-8"
+    )
     ctx = load_csv_context(tmp_path)
     assert ctx["data"][0]["skills"] == ["python", "flask"]
 
@@ -111,6 +130,7 @@ def test_load_csv_from_file_path(tmp_path: Path):
 
 # --- load_context ---
 
+
 def test_load_context_merges_json_and_csv(tmp_path: Path):
     (tmp_path / "config.json").write_text('{"env": "prod"}', encoding="utf-8")
     (tmp_path / "people.csv").write_text("name\nAlice\n", encoding="utf-8")

mddoco-2.0.1/src/mddoco/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.0.0"

mddoco-2.0.1/src/mddoco/pdf.py

@@ -1,39 +0,0 @@
-import tempfile
-from pathlib import Path
-
-
-def html_to_pdf(html_content: str, dest: Path) -> None:
-    """Render an HTML string to a PDF file using a headless Chromium browser.
-
-    Navigates via a temporary file:// URL so that external resources (CDN
-    scripts, Mermaid.js, etc.) load correctly before the page is printed.
-    """
-    try:
-        from playwright.sync_api import sync_playwright
-    except ImportError:
-        raise RuntimeError(
-            "Playwright is required for PDF output. "
-            "Run: pip install playwright && playwright install chromium"
-        )
-
-    with tempfile.NamedTemporaryFile(
-        suffix=".html", delete=False, mode="w", encoding="utf-8"
-    ) as f:
-        f.write(html_content)
-        tmp_path = Path(f.name)
-
-    try:
-        with sync_playwright() as p:
-            browser = p.chromium.launch()
-            page = browser.new_page()
-            page.goto(tmp_path.as_uri(), wait_until="networkidle")
-            # If Paged.js is present, wait for it to finish paginating before
-            # capturing — networkidle fires before its JS layout pass completes.
-            page.wait_for_function(
-                "typeof window.PagedPolyfill === 'undefined'"
-                " || !!document.querySelector('.pagedjs_pages')"
-            )
-            page.pdf(path=str(dest), format="A4", print_background=True)
-            browser.close()
-    finally:
-        tmp_path.unlink(missing_ok=True)