simpdf 0.1.0__tar.gz

simpdf-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: simpdf
+Version: 0.1.0
+Summary: Markdown-to-PDF rendering with FPDF2 and configurable TTF fonts.
+Author: Dmitry
+Keywords: markdown,pdf,fpdf,cyrillic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: fpdf2<3,>=2.8.0
+Requires-Dist: markdown-it-py<4,>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0.0; extra == "dev"
+
+# simpdf
+
+`simpdf` is a small Python library for rendering Markdown into PDF with `fpdf2`, while keeping font handling explicit so Cyrillic and other non-Latin text work reliably with external TTF fonts.
+
+The library is centered on a `MarkdownPdfRenderer` class. You give it a directory with TTF files, describe the font face to register, and then render Markdown into PDF bytes or directly into a file.
+
+## Features
+
+- Uses `fpdf2` as the PDF backend
+- Supports external TTF fonts and Cyrillic-friendly fonts such as DejaVu Sans
+- Provides a helper to download DejaVu Sans fonts into a target directory
+- Class-first API with optional convenience helpers
+- Minimal CLI for rendering Markdown and downloading DejaVu fonts
+- Supports these Markdown elements in v1:
+  - headings
+  - paragraphs
+  - bold and italic text
+  - inline code
+  - ordered and unordered lists
+  - tables
+  - blockquotes
+  - fenced code blocks
+  - thematic breaks
+  - clickable links
+
+## Installation
+
+```bash
+pip install simpdf
+```
+
+For development and tests:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="fonts",
+    font_face=FontFace.dejavu_sans(),
+)
+
+markdown_text = """
+# Example
+
+Привет, мир.
+
+- one
+- two
+"""
+
+pdf_bytes = renderer.render_to_bytes(markdown_text)
+
+with open("output.pdf", "wb") as handle:
+    handle.write(pdf_bytes)
+```
+
+## Downloading DejaVu Fonts
+
+The library does not bundle fonts inside the wheel. Use the download helper to populate your own font directory.
+
+```python
+from simpdf import download_dejavu_fonts
+
+downloaded = download_dejavu_fonts("fonts")
+print([path.name for path in downloaded])
+```
+
+The helper downloads the DejaVu font files from this public GitHub repository layout:
+
+- `https://github.com/shwars/simpdf/raw/refs/heads/main/fonts/DejaVuSans.ttf`
+- other font files use the same URL pattern
+
+## Using Custom Fonts
+
+You can use any TTF family as long as you provide at least a regular face. Bold, italic, and bold-italic are optional; if omitted, the regular face is reused.
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="my-fonts",
+    font_face=FontFace(
+        family="NotoSansCustom",
+        regular="NotoSans-Regular.ttf",
+        bold="NotoSans-Bold.ttf",
+        italic="NotoSans-Italic.ttf",
+        bold_italic="NotoSans-BoldItalic.ttf",
+    ),
+)
+```
+
+Font file values may be file names relative to `font_directory` or absolute paths.
+
+## Formatting Options
+
+Formatting is configured with a plain nested dictionary. Any omitted value falls back to the library defaults.
+
+Example:
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="fonts",
+    font_face=FontFace.dejavu_sans(),
+    formatting_options={
+        "text": {"font_size": 11},
+        "headings": {
+            "sizes": {1: 26, 2: 20, 3: 16},
+        },
+        "lists": {"indent": 9},
+        "table": {"heading_font_size": 13},
+    },
+)
+```
+
+Supported option groups:
+
+- `page`: page size, orientation, and margins
+- `text`: base font size, line height multiplier, text color
+- `headings`: per-level sizes and spacing
+- `paragraph`: paragraph spacing
+- `lists`: indent, bullet symbol, list spacing
+- `blockquote`: indent, bar styling, text color
+- `table`: font sizes, padding, minimum column width, spacing
+- `code_block`: font size, padding, colors, spacing
+- `inline_code`: inline code text color
+- `links`: link color and underline toggle
+- `thematic_break`: rule color, width, spacing
+
+## Convenience Helpers
+
+If you prefer a functional call site, `simpdf` also exports:
+
+- `render_markdown_to_pdf_bytes(...)`
+- `render_markdown_to_pdf_file(...)`
+
+These helpers internally construct `MarkdownPdfRenderer`.
+
+## CLI Usage
+
+Render Markdown into PDF:
+
+```bash
+simpdf render input.md output.pdf \
+  --fonts-dir ./fonts \
+  --family-name DejaVuSans \
+  --font-regular DejaVuSans.ttf \
+  --font-bold DejaVuSans-Bold.ttf \
+  --font-italic DejaVuSans-Oblique.ttf \
+  --font-bold-italic DejaVuSans-BoldOblique.ttf
+```
+
+Download DejaVu fonts:
+
+```bash
+simpdf download-dejavu ./fonts
+```
+
+If you want custom formatting from the CLI, pass a JSON file with `--options-file`.
+
+## Examples
+
+See [`examples/basic_render.py`](/D:/GIT/simpdf/examples/basic_render.py), [`examples/custom_font_and_style.py`](/D:/GIT/simpdf/examples/custom_font_and_style.py), and [`examples/rich_markdown.py`](/D:/GIT/simpdf/examples/rich_markdown.py).
+
+## Tests
+
+The repo now contains a pytest suite that covers:
+
+- font config validation
+- DejaVu download helper behavior
+- markdown token flattening and table extraction
+- PDF rendering with Cyrillic content
+- formatting overrides
+- CLI render and download flows
+
+Run tests with:
+
+```bash
+pytest
+```
+
+## Compatibility Note
+
+For older code that imported `simpdf.pdfgen`, a small compatibility wrapper is still present. The recommended API is the class-based renderer from `simpdf`.

simpdf-0.1.0/README.md

@@ -0,0 +1,191 @@
+# simpdf
+
+`simpdf` is a small Python library for rendering Markdown into PDF with `fpdf2`, while keeping font handling explicit so Cyrillic and other non-Latin text work reliably with external TTF fonts.
+
+The library is centered on a `MarkdownPdfRenderer` class. You give it a directory with TTF files, describe the font face to register, and then render Markdown into PDF bytes or directly into a file.
+
+## Features
+
+- Uses `fpdf2` as the PDF backend
+- Supports external TTF fonts and Cyrillic-friendly fonts such as DejaVu Sans
+- Provides a helper to download DejaVu Sans fonts into a target directory
+- Class-first API with optional convenience helpers
+- Minimal CLI for rendering Markdown and downloading DejaVu fonts
+- Supports these Markdown elements in v1:
+  - headings
+  - paragraphs
+  - bold and italic text
+  - inline code
+  - ordered and unordered lists
+  - tables
+  - blockquotes
+  - fenced code blocks
+  - thematic breaks
+  - clickable links
+
+## Installation
+
+```bash
+pip install simpdf
+```
+
+For development and tests:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="fonts",
+    font_face=FontFace.dejavu_sans(),
+)
+
+markdown_text = """
+# Example
+
+Привет, мир.
+
+- one
+- two
+"""
+
+pdf_bytes = renderer.render_to_bytes(markdown_text)
+
+with open("output.pdf", "wb") as handle:
+    handle.write(pdf_bytes)
+```
+
+## Downloading DejaVu Fonts
+
+The library does not bundle fonts inside the wheel. Use the download helper to populate your own font directory.
+
+```python
+from simpdf import download_dejavu_fonts
+
+downloaded = download_dejavu_fonts("fonts")
+print([path.name for path in downloaded])
+```
+
+The helper downloads the DejaVu font files from this public GitHub repository layout:
+
+- `https://github.com/shwars/simpdf/raw/refs/heads/main/fonts/DejaVuSans.ttf`
+- other font files use the same URL pattern
+
+## Using Custom Fonts
+
+You can use any TTF family as long as you provide at least a regular face. Bold, italic, and bold-italic are optional; if omitted, the regular face is reused.
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="my-fonts",
+    font_face=FontFace(
+        family="NotoSansCustom",
+        regular="NotoSans-Regular.ttf",
+        bold="NotoSans-Bold.ttf",
+        italic="NotoSans-Italic.ttf",
+        bold_italic="NotoSans-BoldItalic.ttf",
+    ),
+)
+```
+
+Font file values may be file names relative to `font_directory` or absolute paths.
+
+## Formatting Options
+
+Formatting is configured with a plain nested dictionary. Any omitted value falls back to the library defaults.
+
+Example:
+
+```python
+from simpdf import FontFace, MarkdownPdfRenderer
+
+renderer = MarkdownPdfRenderer(
+    font_directory="fonts",
+    font_face=FontFace.dejavu_sans(),
+    formatting_options={
+        "text": {"font_size": 11},
+        "headings": {
+            "sizes": {1: 26, 2: 20, 3: 16},
+        },
+        "lists": {"indent": 9},
+        "table": {"heading_font_size": 13},
+    },
+)
+```
+
+Supported option groups:
+
+- `page`: page size, orientation, and margins
+- `text`: base font size, line height multiplier, text color
+- `headings`: per-level sizes and spacing
+- `paragraph`: paragraph spacing
+- `lists`: indent, bullet symbol, list spacing
+- `blockquote`: indent, bar styling, text color
+- `table`: font sizes, padding, minimum column width, spacing
+- `code_block`: font size, padding, colors, spacing
+- `inline_code`: inline code text color
+- `links`: link color and underline toggle
+- `thematic_break`: rule color, width, spacing
+
+## Convenience Helpers
+
+If you prefer a functional call site, `simpdf` also exports:
+
+- `render_markdown_to_pdf_bytes(...)`
+- `render_markdown_to_pdf_file(...)`
+
+These helpers internally construct `MarkdownPdfRenderer`.
+
+## CLI Usage
+
+Render Markdown into PDF:
+
+```bash
+simpdf render input.md output.pdf \
+  --fonts-dir ./fonts \
+  --family-name DejaVuSans \
+  --font-regular DejaVuSans.ttf \
+  --font-bold DejaVuSans-Bold.ttf \
+  --font-italic DejaVuSans-Oblique.ttf \
+  --font-bold-italic DejaVuSans-BoldOblique.ttf
+```
+
+Download DejaVu fonts:
+
+```bash
+simpdf download-dejavu ./fonts
+```
+
+If you want custom formatting from the CLI, pass a JSON file with `--options-file`.
+
+## Examples
+
+See [`examples/basic_render.py`](/D:/GIT/simpdf/examples/basic_render.py), [`examples/custom_font_and_style.py`](/D:/GIT/simpdf/examples/custom_font_and_style.py), and [`examples/rich_markdown.py`](/D:/GIT/simpdf/examples/rich_markdown.py).
+
+## Tests
+
+The repo now contains a pytest suite that covers:
+
+- font config validation
+- DejaVu download helper behavior
+- markdown token flattening and table extraction
+- PDF rendering with Cyrillic content
+- formatting overrides
+- CLI render and download flows
+
+Run tests with:
+
+```bash
+pytest
+```
+
+## Compatibility Note
+
+For older code that imported `simpdf.pdfgen`, a small compatibility wrapper is still present. The recommended API is the class-based renderer from `simpdf`.

simpdf-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simpdf"
+version = "0.1.0"
+description = "Markdown-to-PDF rendering with FPDF2 and configurable TTF fonts."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  {name = "Dmitry"}
+]
+dependencies = [
+  "fpdf2>=2.8.0,<3",
+  "markdown-it-py>=3.0.0,<4",
+]
+keywords = ["markdown", "pdf", "fpdf", "cyrillic"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0,<9",
+]
+
+[project.scripts]
+simpdf = "simpdf.cli:main"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+include = ["simpdf*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

simpdf-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simpdf-0.1.0/simpdf/__init__.py

@@ -0,0 +1,11 @@
+from .fonts import DEJAVU_FONT_FILES, FontFace, download_dejavu_fonts
+from .renderer import MarkdownPdfRenderer, render_markdown_to_pdf_bytes, render_markdown_to_pdf_file
+
+__all__ = [
+    "DEJAVU_FONT_FILES",
+    "FontFace",
+    "MarkdownPdfRenderer",
+    "download_dejavu_fonts",
+    "render_markdown_to_pdf_bytes",
+    "render_markdown_to_pdf_file",
+]

simpdf-0.1.0/simpdf/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simpdf-0.1.0/simpdf/cli.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .fonts import FontFace, download_dejavu_fonts
+from .renderer import MarkdownPdfRenderer
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="simpdf", description="Render Markdown into PDF with configurable TTF fonts.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    render_parser = subparsers.add_parser("render", help="Render a Markdown file into PDF.")
+    render_parser.add_argument("input_markdown", type=Path)
+    render_parser.add_argument("output_pdf", type=Path)
+    render_parser.add_argument("--fonts-dir", type=Path, required=True)
+    render_parser.add_argument("--family-name", default="DejaVuSans")
+    render_parser.add_argument("--font-regular", required=True)
+    render_parser.add_argument("--font-bold")
+    render_parser.add_argument("--font-italic")
+    render_parser.add_argument("--font-bold-italic")
+    render_parser.add_argument("--options-file", type=Path, help="Path to a JSON file with formatting options.")
+
+    download_parser = subparsers.add_parser("download-dejavu", help="Download the DejaVu Sans font files.")
+    download_parser.add_argument("target_dir", type=Path)
+    download_parser.add_argument("--overwrite", action="store_true")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "download-dejavu":
+        download_dejavu_fonts(args.target_dir, overwrite=args.overwrite)
+        return 0
+
+    options = {}
+    if args.options_file:
+        options = json.loads(args.options_file.read_text(encoding="utf-8"))
+
+    renderer = MarkdownPdfRenderer(
+        font_directory=args.fonts_dir,
+        font_face=FontFace(
+            family=args.family_name,
+            regular=args.font_regular,
+            bold=args.font_bold,
+            italic=args.font_italic,
+            bold_italic=args.font_bold_italic,
+        ),
+        formatting_options=options,
+    )
+    markdown_text = args.input_markdown.read_text(encoding="utf-8")
+    renderer.render_to_file(markdown_text, args.output_pdf)
+    return 0

simpdf-0.1.0/simpdf/fonts.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+from urllib.request import urlopen
+
+
+DEJAVU_BASE_URL = "https://github.com/shwars/simpdf/raw/refs/heads/main/fonts"
+DEJAVU_FONT_FILES = (
+    "DejaVuSans.ttf",
+    "DejaVuSans-Bold.ttf",
+    "DejaVuSans-Oblique.ttf",
+    "DejaVuSans-BoldOblique.ttf",
+    "DejaVuSansCondensed.ttf",
+    "DejaVuSansCondensed-Bold.ttf",
+    "DejaVuSansCondensed-Oblique.ttf",
+    "DejaVuSansCondensed-BoldOblique.ttf",
+)
+
+
+@dataclass(frozen=True)
+class FontFace:
+    family: str
+    regular: str
+    bold: str | None = None
+    italic: str | None = None
+    bold_italic: str | None = None
+
+    @classmethod
+    def dejavu_sans(cls) -> "FontFace":
+        return cls(
+            family="DejaVuSans",
+            regular="DejaVuSans.ttf",
+            bold="DejaVuSans-Bold.ttf",
+            italic="DejaVuSans-Oblique.ttf",
+            bold_italic="DejaVuSans-BoldOblique.ttf",
+        )
+
+
+def coerce_font_face(font_face: FontFace | Mapping[str, str]) -> FontFace:
+    if isinstance(font_face, FontFace):
+        return font_face
+
+    try:
+        family = font_face["family"]
+        regular = font_face["regular"]
+    except KeyError as exc:
+        raise ValueError(f"Missing required font face field: {exc.args[0]}") from exc
+
+    return FontFace(
+        family=family,
+        regular=regular,
+        bold=font_face.get("bold"),
+        italic=font_face.get("italic"),
+        bold_italic=font_face.get("bold_italic"),
+    )
+
+
+def resolve_font_paths(font_directory: str | Path, font_face: FontFace | Mapping[str, str]) -> dict[str, Path]:
+    directory = Path(font_directory)
+    face = coerce_font_face(font_face)
+    if not directory.exists():
+        raise FileNotFoundError(f"Font directory does not exist: {directory}")
+
+    regular = _resolve_path(directory, face.regular)
+    bold = _resolve_path(directory, face.bold) if face.bold else regular
+    italic = _resolve_path(directory, face.italic) if face.italic else regular
+    bold_italic = _resolve_path(directory, face.bold_italic) if face.bold_italic else bold
+
+    missing = [path for path in (regular, bold, italic, bold_italic) if not path.exists()]
+    if missing:
+        message = ", ".join(str(path) for path in missing)
+        raise FileNotFoundError(f"Missing required font files: {message}")
+
+    return {
+        "regular": regular,
+        "bold": bold,
+        "italic": italic,
+        "bold_italic": bold_italic,
+    }
+
+
+def register_font_family(pdf, font_directory: str | Path, font_face: FontFace | Mapping[str, str]) -> str:
+    face = coerce_font_face(font_face)
+    resolved = resolve_font_paths(font_directory, face)
+    pdf.add_font(face.family, style="", fname=str(resolved["regular"]))
+    pdf.add_font(face.family, style="B", fname=str(resolved["bold"]))
+    pdf.add_font(face.family, style="I", fname=str(resolved["italic"]))
+    pdf.add_font(face.family, style="BI", fname=str(resolved["bold_italic"]))
+    return face.family
+
+
+def download_dejavu_fonts(
+    target_dir: str | Path,
+    *,
+    overwrite: bool = False,
+    timeout: int = 30,
+) -> list[Path]:
+    target = Path(target_dir)
+    target.mkdir(parents=True, exist_ok=True)
+    downloaded: list[Path] = []
+
+    for filename in DEJAVU_FONT_FILES:
+        destination = target / filename
+        if destination.exists() and not overwrite:
+            downloaded.append(destination)
+            continue
+
+        url = f"{DEJAVU_BASE_URL}/{filename}"
+        with urlopen(url, timeout=timeout) as response:
+            destination.write_bytes(response.read())
+        downloaded.append(destination)
+
+    return downloaded
+
+
+def _resolve_path(base_dir: Path, value: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    return base_dir / path