pdfmarq 0.1.0__tar.gz

pdfmarq-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: pdfmarq
+Version: 0.1.0
+Summary: PDF generation library with fluent API and optional markdown support
+Author: Xaeian
+License: MIT
+Project-URL: Repository, https://github.com/Xaeian/PDFMarQ
+Keywords: pdf,reportlab,document,generation,markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: reportlab
+Requires-Dist: Pillow
+Requires-Dist: svglib
+Provides-Extra: md
+Requires-Dist: PyYAML; extra == "md"
+Requires-Dist: Pygments; extra == "md"
+Requires-Dist: emoji; extra == "md"
+Requires-Dist: markdown-it-py; extra == "md"
+Requires-Dist: matplotlib; extra == "md"
+Requires-Dist: mdit-py-emoji; extra == "md"
+Requires-Dist: mdit-py-plugins; extra == "md"
+Provides-Extra: all
+Requires-Dist: PyYAML; extra == "all"
+Requires-Dist: Pygments; extra == "all"
+Requires-Dist: emoji; extra == "all"
+Requires-Dist: markdown-it-py; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
+Requires-Dist: mdit-py-emoji; extra == "all"
+Requires-Dist: mdit-py-plugins; extra == "all"
+
+# PDFMarQ
+
+PDF generation with a fluent API. Core is lean _(reportlab + Pillow + svglib)_. Optional `[md]` extra adds full markdown-to-PDF rendering with frontmatter headers, math, mermaid, syntax highlighting and more.
+
+## Philosophy
+
+PDFMarQ wraps reportlab's stateful canvas into a fluent, cursor-based API. You describe document flow, not coordinates. Markdown rendering lives in a separate subpackage so the core stays installable without heavyweight dependencies.
+
+- **Fluent over imperative**: `pdf.font("Helvetica", 12).text("Hi").enter().text("World")` vs `canvas.setFont() → canvas.drawString() → manual Y tracking`
+- **Cursor flows naturally**: top-left origin, `y` grows down, `enter()` is a newline
+- **One way per feature**: `pdf.table()`, `pdf.image()`, `pdf.svg()`, `pdf.link()`, no overloaded call signatures
+- **Markdown is optional**: core → 3 deps, `[md]` adds the stack
+- **Frontmatter as contract**: YAML block at top of markdown becomes a styled header with logo, status badge, version, dates, signature slot
+- **Lean output**: no headless Chrome, no web stack, no React SSR. Pure Python + native PDF primitives. Files stay small, rendering stays fast, fonts are embedded properly, and the output opens clean in every PDF reader
+
+Trade-offs:
+- Cursor mutation is a state machine. Great for linear documents, awkward for complex grid layouts. For those, drop into raw reportlab via `pdf._canvas`.
+- Markdown rendering estimates heights analytically to decide page breaks. Good enough for 95% of content. Edge cases with math + wide tables may push onto the next page more aggressively than necessary.
+- Installing Python + a stack of deps is a barrier for non-technical users. If you're building a tool end-users will actually touch, put PDFMarQ behind a backend service _(FastAPI endpoint, CLI wrapper, desktop app)_ rather than asking them to `pip install` anything.
+
+## Install
+
+```sh
+pip install pdfmarq      # core: reportlab, Pillow, svglib
+pip install pdfmarq[md]  # + markdown rendering stack
+```
+
+## Examples
+
+```py
+from pdfmarq import PDF
+# Fluent core API
+with PDF("report.pdf") as pdf:
+  pdf.font("Helvetica", 20, "Bold").text("Quarterly Report")
+  pdf.enter().font(size=12, mode="Regular")
+  pdf.text("Revenue up 23% year-over-year.")
+  pdf.table(
+    [["Q1", "120k"], ["Q2", "148k"], ["Q3", "172k"]],
+    header=["Quarter", "Revenue"],
+    sizes=[1, 2], aligns=["C", "R"],
+  )
+  pdf.image("chart.png", 180, 80)
+  pdf.link("https://xaeian.com", 40, 5)
+```
+
+```py
+from pdfmarq.md import md_to_pdf, MarkdownStyle
+# Markdown to PDF
+style = MarkdownStyle(
+  body_family="IBMPlexSans",
+  heading_family="Sora",
+  page_number_label="Page", # "Page 1/5" in footer
+)
+md_to_pdf(open("doc.md").read(), "doc.pdf", style=style, font_dir="./fonts")
+```
+
+## Markdown features
+
+- GitHub-flavored markdown _(tables, fenced code, lists, strikethrough)_
+- YAML frontmatter with styled document header _(logo, status badge, version, sign block, landscape flag)_
+- Mini-header on continuation pages with aspect-aware logo _(width + height caps)_
+- Page numbering `Page N/M` via deferred canvas rendering _(configurable)_
+- Configurable frontmatter labels for localization _(`fm_label_author`, `fm_label_created`, …)_
+- Skip-duplicate-title: drops `# X` when it matches frontmatter `title`
+- Auto-slugged headings with clickable `[text](#anchor)` internal links _(unicode-aware, broken targets degrade to plain text)_
+- Local-path links configurable via `link_root` + `link_base` _(or per-doc YAML `base:`)_
+- Syntax highlighting _(Pygments)_
+- Math formulas inline `$x^2$` and block `$$...$$` _(matplotlib)_
+- Mermaid diagrams via `mermaid-cli` _(local)_ or `mermaid.ink` _(network fallback)_, capped at a configurable max height
+- Footnotes, emoji shortcodes `:rocket:`, nested lists, blockquotes, GitHub callouts _(`> [!NOTE]`, `> [!WARNING]`, …)_
+- Zebra-striped tables _(subtle, readability without noise)_
+- Smart page breaks for paragraphs, tables, lists, and blockquotes _(pre-measured, no orphans)_
+
+## Modules
+
+| Module       | Description                                        | Docs                                         |
+| ------------ | -------------------------------------------------- | -------------------------------------------- |
+| `pdfmarq`    | Core PDF API _(fluent cursor-based drawing)_       | [pdfmarq/readme.md](pdfmarq/readme.md)       |
+| `pdfmarq.md` | Markdown-to-PDF renderer _(optional `[md]` extra)_ | [pdfmarq/md/readme.md](pdfmarq/md/readme.md) |

pdfmarq-0.1.0/pdfmarq/__init__.py

@@ -0,0 +1,57 @@
+# pdfmarq/__init__.py
+
+"""
+PDF generation with fluent API. Built on reportlab.
+
+Low-level drawing only - no markdown. For markdown rendering install
+the `[md]` extra and import from `pdfmarq.md`:
+
+  pip install pdfmarq[md]
+  from pdfmarq.md import md_to_pdf, MarkdownStyle
+
+Example:
+  >>> from pdfmarq import PDF, Align
+  >>> with PDF("output.pdf") as pdf:
+  ...   pdf.font("Helvetica", 12, "Bold")
+  ...   pdf.text("Hello World", align=Align.CENTER)
+"""
+
+#----------------------------------------------------------------------- Metadata for auto-toml
+
+__version__ = "0.1.0"
+__repo__ = "Xaeian/PDFMarQ"
+__python__ = ">=3.10"
+__description__ = "PDF generation library with fluent API and optional markdown support"
+__author__ = "Xaeian"
+__keywords__ = ["pdf", "reportlab", "document", "generation", "markdown"]
+__dependencies__ = ["reportlab", "Pillow", "svglib"]
+
+#----------------------------------------------------------------------------------- Public API
+
+from .constants import (
+  Unit, PageSize, Align, Colors, Defaults, MM_TO_PT,
+  A4, A3, A5, LETTER, LEGAL,
+)
+from .styles import Style, TableStyle, Styles
+from .layout import Cursor, PageGeometry
+from .text import TextMetrics, BoxFitResult
+from .tables import TableBuilder, TableData, Cell
+from .fonts import FontManager
+from .structure import Metadata, Bookmark, TOCEntry, BookmarkManager, LinkManager
+from .utils import to_mm, to_pt, mm_to_pt, parse_color, color_alpha, parse_margin
+from .inline import RichSegment, render_rich
+from .core import PDF
+
+__all__ = [
+  "PDF",
+  "Unit", "PageSize", "Align", "Colors", "Defaults", "MM_TO_PT",
+  "A4", "A3", "A5", "LETTER", "LEGAL",
+  "Style", "TableStyle", "Styles",
+  "Cursor", "PageGeometry",
+  "TextMetrics", "BoxFitResult",
+  "TableBuilder", "TableData", "Cell",
+  "FontManager",
+  "Metadata", "Bookmark", "TOCEntry", "BookmarkManager", "LinkManager",
+  "to_mm", "to_pt", "mm_to_pt", "parse_color", "color_alpha", "parse_margin",
+  "RichSegment", "render_rich",
+]

pdfmarq-0.1.0/pdfmarq/_warn.py

@@ -0,0 +1,36 @@
+# pdfmarq/_warn.py
+
+"""
+Deduplicated warning printer for missing optional dependencies.
+
+When a feature degrades because an optional package is absent, call
+`warn_missing(key, package, feature)` once. Repeated calls with the same
+key are suppressed so renders do not spam the console.
+
+Example:
+  >>> from ._warn import warn_missing
+  >>> warn_missing("matplotlib", "matplotlib", "math formulas")
+  pdfmarq: math formulas disabled, install with: pip install matplotlib
+"""
+import sys
+
+_seen: set = set()
+
+def warn_missing(key:str, package:str, feature:str) -> None:
+  """Print a one-time warning about a missing optional package.
+  Args:
+    key: Deduplication key (typically the import name).
+    package: pip-installable name (may differ from import name).
+    feature: Short human description of what was disabled.
+  """
+  if key in _seen:
+    return
+  _seen.add(key)
+  print(
+    f"pdfmarq: {feature} disabled, install with: pip install {package}",
+    file=sys.stderr,
+  )
+
+def reset_warnings() -> None:
+  """Clear the seen-warnings registry. Used in tests."""
+  _seen.clear()

pdfmarq-0.1.0/pdfmarq/constants.py

@@ -0,0 +1,68 @@
+# pdfmarq/constants.py
+
+"""Constants for PDF library - units, colors, defaults."""
+from dataclasses import dataclass
+
+# Exact mm ↔ pt conversion (1 inch = 72pt = 25.4mm)
+MM_TO_PT = 72 / 25.4  # ≈ 2.8346456692913384
+
+#---------------------------------------------------------------------------------------- Units
+
+class Unit:
+  """Unit conversion factors to millimeters."""
+  MM = 1.0
+  CM = 10.0
+  INCH = 25.4
+  PT = 25.4 / 72   # ≈ 0.35278 mm - exact
+  PX = 25.4 / 96   # ≈ 0.26458 mm - 96 DPI
+
+#------------------------------------------------------------------------------------- PageSize
+
+@dataclass
+class PageSize:
+  """Common page sizes in mm."""
+  width: float
+  height: float
+  def landscape(self) -> "PageSize":
+    return PageSize(self.height, self.width)
+
+A4 = PageSize(210, 297)
+A3 = PageSize(297, 420)
+A5 = PageSize(148, 210)
+LETTER = PageSize(215.9, 279.4)
+LEGAL = PageSize(215.9, 355.6)
+
+#---------------------------------------------------------------------------------------- Align
+
+class Align:
+  """Text/element alignment constants."""
+  LEFT = "L"
+  RIGHT = "R"
+  CENTER = "C"
+  JUSTIFY = "J"
+
+#--------------------------------------------------------------------------------------- Colors
+
+class Colors:
+  """Predefined colors as (r, g, b) tuples (0-1 range)."""
+  BLACK = (0, 0, 0)
+  WHITE = (1, 1, 1)
+  RED = (1, 0, 0)
+  GREEN = (0, 1, 0)
+  BLUE = (0, 0, 1)
+  GREY = (0.5, 0.5, 0.5)
+  LIGHT_GREY = (0.8, 0.8, 0.8)
+  DARK_GREY = (0.3, 0.3, 0.3)
+
+#------------------------------------------------------------------------------------- Defaults
+
+class Defaults:
+  """Default values for PDF generation."""
+  PAGE_WIDTH = 210
+  PAGE_HEIGHT = 297
+  MARGIN = 15
+  FONT_FAMILY = "Helvetica"
+  FONT_SIZE = 12
+  FONT_MODE = "Regular"
+  LINE_HEIGHT = 1.2
+  UNIT = "mm"