docmarq 0.1.0__tar.gz

docmarq-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: docmarq
+Version: 0.1.0
+Summary: DOCX generation library with fluent API
+Author: Xaeian
+License: MIT
+Project-URL: Repository, https://github.com/Xaeian/docmarq
+Keywords: docx,word,ooxml,document,generation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-docx
+Provides-Extra: md
+Requires-Dist: PyYAML; extra == "md"
+Requires-Dist: markdown-it-py; extra == "md"
+Requires-Dist: mdit-py-plugins; extra == "md"
+Provides-Extra: all
+Requires-Dist: PyYAML; extra == "all"
+Requires-Dist: markdown-it-py; extra == "all"
+Requires-Dist: mdit-py-plugins; extra == "all"
+
+# DocMarQ
+
+DOCX generation with a fluent API. Core is lean _(just `python-docx`)_. Optional `[md]` extra adds markdown-to-DOCX rendering with banner headers, mermaid, GitHub callouts and more. Sibling library to [`pdfmarq`](https://github.com/Xaeian/PDFMarQ) with the same API shape and `.docx` output.
+
+## Philosophy
+
+DocMarQ wraps `python-docx` _(OOXML zip plumbing, content types, relationships)_ into a fluent paragraph/run API. You describe document flow; Word handles layout, pagination, and reflow on open.
+
+- **Fluent paragraph/run model**: `doc.para("First.")` opens a paragraph, `doc.text(" with bold", bold=True)` appends a styled run. Close with `enter()` or let the next block auto-open one.
+- **One way per feature**: `doc.table()`, `doc.image()`, `doc.bullet()`, `doc.link()`, no overloaded call signatures
+- **Markdown is optional**: core → 1 dep _(`python-docx`)_, `[md]` adds `markdown-it-py`, `mdit-py-plugins`, `PyYAML`
+- **Cross-library parity**: API shape mirrors [`pdfmarq`](https://github.com/Xaeian/PDFMarQ), including `TableStyle`, `Styles`, `parse_color`, `rgb255`, page sizes, and `lang_style()` for i18n. The same markdown source can target both PDF and DOCX.
+- **Word-native output**: opens cleanly in Word, LibreOffice, Google Docs. Templates `.dotx` / `.docx` are respected, so themes and styles carry over.
+
+Trade-offs:
+- No cursor or coordinate control. Word owns layout. Great for content-driven documents, not for pixel-perfect grids _(use `pdfmarq` if you need that)_.
+- No math support. Word's equation editor is OOXML-native and out of scope for v0.2.0. For math-heavy docs use `pdfmarq` with matplotlib.
+- Syntax highlighting in code blocks is not rendered yet. The `language` argument is accepted but ignored.
+- The dep tree is small but `python-docx` is the only path to OOXML. If it can't express something _(e.g. complex equation OMML)_, neither can DocMarQ. Drop to `doc.doc` for raw `python-docx` access.
+
+## Install
+
+```sh
+pip install docmarq      # core: python-docx
+pip install docmarq[md]  # + markdown rendering stack
+```
+
+## Examples
+
+```py
+from docmarq import DOCX
+# Fluent core API
+with DOCX("report.docx") as doc:
+  doc.font("Calibri", 20, "Bold").para("Quarterly Report")
+  doc.font(size=11, mode="Regular")
+  doc.para("Revenue up 23% year-over-year.")
+  doc.table(
+    [["Q1", "120k"], ["Q2", "148k"], ["Q3", "172k"]],
+    header=["Quarter", "Revenue"],
+    aligns=["C", "R"],
+  )
+  doc.image("chart.png", width=180, height=80)
+  doc.link("google.com", url="https://google.com")
+```
+
+```py
+from docmarq.md import md_to_docx, MarkdownStyle
+# Markdown to DOCX
+style = MarkdownStyle(
+  body_family="Calibri",
+  mono_family="Consolas",
+  line_height=1.4,
+)
+md_to_docx(open("doc.md").read(), "doc.docx", style=style)
+```
+
+See [`example.py`](example.py) for an end-to-end CLI script: language preset, Word-native fonts, `link_root` for cross-document references, and `base_dir` for relative images.
+
+## Markdown features
+
+- GitHub-flavored markdown _(tables, fenced code, lists, strikethrough)_
+- YAML frontmatter rendered as a page-1 banner _(logo, status badge, version, sign block)_
+- Built-in language presets _(en|pl|de|fr|es|it|cs|sk)_ via `lang_style()`: covers banner labels, callouts, date format
+- Skip-duplicate-title: drops `# X` when it matches frontmatter `title`
+- Auto-slugged headings with clickable `[text](#anchor)` internal links _(unicode-aware)_
+- Local-path links configurable via `link_root` + `link_base` _(or per-doc YAML `base:`)_
+- Mermaid diagrams via `mermaid-cli` _(local)_ or `mermaid.ink` _(network fallback)_, with a shared cache with `pdfmarq`
+- Footnotes, emoji shortcodes `:rocket:`, nested lists, blockquotes, GitHub callouts _(`> [!NOTE]`, `> [!WARNING]`, …)_
+- Images with size caps for block and inline use _(`![alt](logo.svg)` works inline at x-height)_
+- Headerless single-row tables for label/value cards
+- Setext-heading-with-image recovery: `![](img.svg)\n---` renders as block image + `<hr>` instead of a thumbnail-sized setext h2
+
+Not supported _(use `pdfmarq` if you need them)_: math formulas, syntax highlighting in code blocks, deferred page numbering _(Word does its own page numbers via field codes, see `doc.footer(page_number=True)`)_.
+
+## Modules
+
+| Module       | Description                                         | Docs                                         |
+| ------------ | --------------------------------------------------- | -------------------------------------------- |
+| `docmarq`    | Core DOCX API _(fluent paragraph/run model)_        | [docmarq/readme.md](docmarq/readme.md)       |
+| `docmarq.md` | Markdown-to-DOCX renderer _(optional `[md]` extra)_ | [docmarq/md/readme.md](docmarq/md/readme.md) |
+
+## See also
+
+Need PDF instead of `.docx`? Check [**PDFMarQ**](https://github.com/Xaeian/PDFMarQ), the sibling library with the same API shape and PDF output. It adds math formulas, syntax highlighting, and pre-measured page breaks. Otherwise feature parity _(banner, callouts, mermaid, lang presets)_.

docmarq-0.1.0/docmarq/__init__.py

@@ -0,0 +1,54 @@
+# docmarq/__init__.py
+
+"""
+DOCX generation with fluent API. Built on `python-docx`.
+
+Mirror of `pdfmarq` philosophy: thin fluent layer over a heavy backend.
+We use `python-docx` for OOXML zip plumbing, content types, and
+relationships - everything user-facing is our own API.
+
+Example:
+  >>> from docmarq import DOCX, Align
+  >>> with DOCX("out.docx") as doc:
+  ...   doc.heading("Tytuł", level=1)
+  ...   doc.para("Pierwszy akapit.")
+  ...   doc.text("Drugi z ").text("bold", bold=True).text(" tekstem.")
+"""
+
+#----------------------------------------------------------------------- Metadata for auto-toml
+
+__version__ = "0.1.0"
+__repo__ = "Xaeian/docmarq"
+__python__ = ">=3.10"
+__description__ = "DOCX generation library with fluent API"
+__author__ = "Xaeian"
+__keywords__ = ["docx", "word", "ooxml", "document", "generation"]
+__dependencies__ = ["python-docx"]
+# pip-name → import-name mapping. `python-docx` is the pip package but
+# the import is `import docx`; the hint surfaces in dependency diagnostics
+# so users debugging `No module named 'docx'` see the right install command.
+__import_names__ = {"python-docx": "docx"}
+
+#----------------------------------------------------------------------------------- Public API
+
+from .constants import (
+  Unit, PageSize, Align, Colors, Defaults,
+  A4, A3, A5, LETTER, LEGAL, EMU_PER_MM, EMU_PER_PT,
+)
+from .styles import Style, TableStyle, Styles
+from .layout import PageGeometry
+from .structure import Metadata, Bookmark
+from .utils import to_mm, mm_to_emu, pt_to_emu, parse_color, parse_margin, color_hex, rgb255
+from .inline import RichSegment
+from .core import DOCX
+
+__all__ = [
+  "DOCX",
+  "Unit", "PageSize", "Align", "Colors", "Defaults",
+  "A4", "A3", "A5", "LETTER", "LEGAL", "EMU_PER_MM", "EMU_PER_PT",
+  "Style", "TableStyle", "Styles",
+  "PageGeometry",
+  "Metadata", "Bookmark",
+  "to_mm", "mm_to_emu", "pt_to_emu", "parse_color", "parse_margin", "color_hex", "rgb255",
+  "RichSegment",
+]

docmarq-0.1.0/docmarq/constants.py

@@ -0,0 +1,77 @@
+# docmarq/constants.py
+
+"""Constants for DOCX library - units, page sizes, alignment, defaults."""
+from dataclasses import dataclass
+
+# OOXML uses EMU (English Metric Units): 1 inch = 914400 EMU = 25.4 mm
+EMU_PER_MM = 36000
+EMU_PER_PT = 12700 # 1 pt = 1/72 inch
+
+#---------------------------------------------------------------------------------------- Units
+
+class Unit:
+  """Unit conversion factors to millimeters."""
+  MM = 1.0
+  CM = 10.0
+  INCH = 25.4
+  PT = 25.4 / 72
+  PX = 25.4 / 96
+
+#------------------------------------------------------------------------------------- PageSize
+
+@dataclass
+class PageSize:
+  """Common page sizes in mm."""
+  width: float
+  height: float
+  def landscape(self) -> "PageSize":
+    """Return a copy with width/height swapped (landscape orientation)."""
+    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. Match pdfmarq values for cross-lib reuse."""
+  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 DOCX generation."""
+  PAGE_WIDTH = 210
+  PAGE_HEIGHT = 297
+  MARGIN = 20
+  FONT_FAMILY = "Calibri"
+  FONT_SIZE = 11
+  FONT_MODE = "Regular"
+  LINE_HEIGHT = 1.15
+  UNIT = "mm"
+  # Heading palette - GitHub-light, mirrors `pdfmarq.MarkdownStyle`
+  HEAD_COLOR = (0.09, 0.11, 0.13) # near-black #1f2328
+  RULE_COLOR = (0.82, 0.84, 0.87) # light grey #d0d7de (h1/h2 underline)
+  # h1..h6 sizes in pt. Matches `pdfmarq.MarkdownStyle.h{1-6}_size` so
+  # the same markdown source renders at the same scale in both libs.
+  HEAD_SIZES = (20, 16, 13, 11, 11, 11)
+  HEAD_UNDERLINE_LEVELS = (1, 2) # which heading levels get bottom border