docxrender 0.1.0__py3-none-any.whl

docxrender/writer.py

@@ -0,0 +1,423 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Self
+
+from docxrender.contracts import (
+    DocxFieldRefreshOptions,
+    DocxFontStyle,
+    DocxParagraphStyle,
+    DocxSizeStyle,
+    DocxStyle,
+    DocxTableStyle,
+    DocxWriteOptions,
+    DocxWriteResult,
+)
+
+
+def create_default_docx_style() -> DocxStyle:
+    """Create the default DOCX style used by the fluent writer.
+
+    Returns:
+        DocxStyle: Complete style object modeled after the shared report style
+            defaults.
+    """
+
+    return DocxStyle(
+        fonts=DocxFontStyle(
+            font_name_latin="Times New Roman",
+            font_name_body_east_asia="宋体",
+            font_name_heading_east_asia="宋体",
+        ),
+        sizes=DocxSizeStyle(
+            pt_title_page_title=36.0,
+            pt_title_page_meta=18.0,
+            pt_title_page_compiler=15.0,
+            pt_body=12.0,
+            pt_caption=10.5,
+            pt_table=12.0,
+            pt_heading_by_level={
+                1: 16.0,
+                2: 14.0,
+                3: 12.0,
+                4: 12.0,
+                5: 12.0,
+                6: 12.0,
+            },
+        ),
+        table=DocxTableStyle(
+            border_color="000000",
+            stripe_fill_color="D9D9D9",
+            border_size_main="12",
+            border_size_header="6",
+            line_spacing=1.5,
+        ),
+        paragraph=DocxParagraphStyle(
+            line_spacing_body=1.5,
+            line_spacing_note=1.2,
+            first_line_indent_cm=0.74,
+        ),
+    )
+
+
+class DocxWriter:
+    """Fluent facade for configuring and writing DOCX files.
+
+    `DocxWriter` is an ergonomic wrapper around `DocxWriteOptions` and the
+    module-level `write_docx` function. It does not own a separate rendering
+    pipeline.
+    """
+
+    def __init__(self, style: DocxStyle | None = None) -> None:
+        """Initialize a fluent DOCX writer.
+
+        Args:
+            style (DocxStyle | None): Optional starting style. When omitted,
+                shared report-style defaults are used.
+        """
+
+        self._style = style or create_default_docx_style()
+        self._field_refresh: DocxFieldRefreshOptions | None = None
+
+    def with_style(self, style: DocxStyle) -> Self:
+        """Replace the writer style.
+
+        Args:
+            style (DocxStyle): Complete style object to use for future writes.
+
+        Returns:
+            Self: This writer, for method chaining.
+        """
+
+        self._style = style
+        return self
+
+    @property
+    def style(self) -> DocxStyle:
+        """Current complete DOCX style.
+
+        Returns:
+            DocxStyle: Complete style after applying fluent overrides.
+        """
+
+        return self._style
+
+    def with_fonts(
+        self,
+        *,
+        font_name_latin: str | None = None,
+        font_name_body_east_asia: str | None = None,
+        font_name_heading_east_asia: str | None = None,
+    ) -> Self:
+        """Override font settings.
+
+        Args:
+            font_name_latin (str | None): Latin font name applied to runs.
+            font_name_body_east_asia (str | None): East Asian body font name.
+            font_name_heading_east_asia (str | None): East Asian heading font name.
+
+        Returns:
+            Self: This writer, for method chaining.
+        """
+
+        fonts = self._style.fonts
+        self._style = DocxStyle(
+            fonts=DocxFontStyle(
+                font_name_latin=font_name_latin or fonts.font_name_latin,
+                font_name_body_east_asia=(
+                    font_name_body_east_asia or fonts.font_name_body_east_asia
+                ),
+                font_name_heading_east_asia=(
+                    font_name_heading_east_asia or fonts.font_name_heading_east_asia
+                ),
+            ),
+            sizes=self._style.sizes,
+            table=self._style.table,
+            paragraph=self._style.paragraph,
+        )
+        return self
+
+    def with_sizes(
+        self,
+        *,
+        pt_title_page_title: float | None = None,
+        pt_title_page_meta: float | None = None,
+        pt_title_page_compiler: float | None = None,
+        pt_body: float | None = None,
+        pt_caption: float | None = None,
+        pt_table: float | None = None,
+        pt_heading_by_level: Mapping[int, float] | None = None,
+    ) -> Self:
+        """Override size settings.
+
+        Args:
+            pt_title_page_title (float | None): Title-page report title size.
+            pt_title_page_meta (float | None): Title-page metadata size.
+            pt_title_page_compiler (float | None): Compiler or organization size.
+            pt_body (float | None): Body paragraph text size.
+            pt_caption (float | None): Caption and note text size.
+            pt_table (float | None): Markdown table text size.
+            pt_heading_by_level (Mapping[int, float] | None): Heading sizes by level.
+
+        Returns:
+            Self: This writer, for method chaining.
+        """
+
+        self._style = DocxStyle(
+            fonts=self._style.fonts,
+            sizes=self._style.sizes.with_overrides(
+                pt_title_page_title=pt_title_page_title,
+                pt_title_page_meta=pt_title_page_meta,
+                pt_title_page_compiler=pt_title_page_compiler,
+                pt_body=pt_body,
+                pt_caption=pt_caption,
+                pt_table=pt_table,
+                pt_heading_by_level=pt_heading_by_level,
+            ),
+            table=self._style.table,
+            paragraph=self._style.paragraph,
+        )
+        return self
+
+    def with_table(
+        self,
+        *,
+        border_color: str | None = None,
+        stripe_fill_color: str | None = None,
+        border_size_main: str | None = None,
+        border_size_header: str | None = None,
+        line_spacing: float | None = None,
+    ) -> Self:
+        """Override table style settings.
+
+        Args:
+            border_color (str | None): WordprocessingML border color.
+            stripe_fill_color (str | None): Body-row stripe fill color.
+            border_size_main (str | None): Main border size in Word units.
+            border_size_header (str | None): Header border size in Word units.
+            line_spacing (float | None): Table paragraph line spacing.
+
+        Returns:
+            Self: This writer, for method chaining.
+        """
+
+        table = self._style.table
+        self._style = DocxStyle(
+            fonts=self._style.fonts,
+            sizes=self._style.sizes,
+            table=DocxTableStyle(
+                border_color=border_color or table.border_color,
+                stripe_fill_color=stripe_fill_color or table.stripe_fill_color,
+                border_size_main=border_size_main or table.border_size_main,
+                border_size_header=border_size_header or table.border_size_header,
+                line_spacing=(
+                    line_spacing if line_spacing is not None else table.line_spacing
+                ),
+            ),
+            paragraph=self._style.paragraph,
+        )
+        return self
+
+    def with_paragraph(
+        self,
+        *,
+        line_spacing_body: float | None = None,
+        line_spacing_note: float | None = None,
+        first_line_indent_cm: float | None = None,
+        note_prefixes: tuple[str, ...] | None = None,
+    ) -> Self:
+        """Override paragraph style settings.
+
+        Args:
+            line_spacing_body (float | None): Body paragraph line spacing.
+            line_spacing_note (float | None): Note paragraph line spacing.
+            first_line_indent_cm (float | None): First-line indent in centimeters.
+            note_prefixes (tuple[str, ...] | None): Prefixes classified as notes.
+
+        Returns:
+            Self: This writer, for method chaining.
+        """
+
+        paragraph = self._style.paragraph
+        self._style = DocxStyle(
+            fonts=self._style.fonts,
+            sizes=self._style.sizes,
+            table=self._style.table,
+            paragraph=DocxParagraphStyle(
+                line_spacing_body=(
+                    line_spacing_body
+                    if line_spacing_body is not None
+                    else paragraph.line_spacing_body
+                ),
+                line_spacing_note=(
+                    line_spacing_note
+                    if line_spacing_note is not None
+                    else paragraph.line_spacing_note
+                ),
+                first_line_indent_cm=(
+                    first_line_indent_cm
+                    if first_line_indent_cm is not None
+                    else paragraph.first_line_indent_cm
+                ),
+                note_prefixes=note_prefixes or paragraph.note_prefixes,
+            ),
+        )
+        return self
+
+    def with_field_refresh(
+        self,
+        options: DocxFieldRefreshOptions | None = None,
+        *,
+        exe_libreoffice: Path | None = None,
+        dir_user_profile: Path | None = None,
+        file_out_docx_refreshed: Path | None = None,
+        file_listener_log: Path | None = None,
+        should_require_toc: bool = False,
+        should_freeze_fields: bool = False,
+        timeout_seconds: float = 30.0,
+        poll_interval_seconds: float = 0.5,
+        stable_checks: int = 2,
+    ) -> Self:
+        """Configure optional LibreOffice UNO field refresh.
+
+        Args:
+            options (DocxFieldRefreshOptions | None): Complete refresh options.
+            exe_libreoffice (Path | None): LibreOffice executable path.
+            dir_user_profile (Path | None): Isolated LibreOffice profile directory.
+            file_out_docx_refreshed (Path | None): Optional refreshed DOCX output.
+            file_listener_log (Path | None): Optional listener log path.
+            should_require_toc (bool): Whether refreshed DOCX must contain TOC results.
+            should_freeze_fields (bool): Whether refreshed fields should be frozen.
+            timeout_seconds (float): Maximum wait time for refreshed DOCX validation.
+            poll_interval_seconds (float): Poll interval for validation.
+            stable_checks (int): Consecutive stable file-stat checks required.
+
+        Returns:
+            Self: This writer, for method chaining.
+
+        Raises:
+            ValueError: `exe_libreoffice` or `dir_user_profile` is missing when
+                `options` is not provided.
+        """
+
+        if options is not None:
+            self._field_refresh = options
+            return self
+        if exe_libreoffice is None or dir_user_profile is None:
+            raise ValueError(
+                "exe_libreoffice and dir_user_profile are required when "
+                "DocxFieldRefreshOptions is not provided."
+            )
+        self._field_refresh = DocxFieldRefreshOptions(
+            exe_libreoffice=exe_libreoffice,
+            dir_user_profile=dir_user_profile,
+            file_out_docx_refreshed=file_out_docx_refreshed,
+            file_listener_log=file_listener_log,
+            should_require_toc=should_require_toc,
+            should_freeze_fields=should_freeze_fields,
+            timeout_seconds=timeout_seconds,
+            poll_interval_seconds=poll_interval_seconds,
+            stable_checks=stable_checks,
+        )
+        return self
+
+    def build_style(self) -> DocxStyle:
+        """Build the current complete DOCX style.
+
+        Returns:
+            DocxStyle: Complete style object.
+        """
+
+        return self.style
+
+    def build_options(
+        self,
+        *,
+        file_template: Path,
+        file_out_docx: Path,
+        context: Mapping[str, Any],
+        markdown_body: str,
+        dir_base: Path,
+        anchor_token: str = "__REPORT_BODY_ANCHOR__",
+        should_update_fields: bool = True,
+        should_freeze_fields: bool = False,
+        field_refresh: DocxFieldRefreshOptions | None = None,
+    ) -> DocxWriteOptions:
+        """Build `DocxWriteOptions` from fluent settings and write inputs.
+
+        Args:
+            file_template (Path): Input DOCX template path.
+            file_out_docx (Path): Output DOCX path to write.
+            context (Mapping[str, Any]): Template context passed to `docxtpl`.
+            markdown_body (str): Markdown body to insert into the DOCX.
+            dir_base (Path): Base directory used to resolve relative image paths.
+            anchor_token (str): Paragraph text marking markdown insertion point.
+            should_update_fields (bool): Whether fields should be marked for update.
+            should_freeze_fields (bool): Whether fields should be frozen after writing.
+            field_refresh (DocxFieldRefreshOptions | None): Optional per-call field
+                refresh override.
+
+        Returns:
+            DocxWriteOptions: Complete options for the core writer.
+        """
+
+        return DocxWriteOptions(
+            file_template=file_template,
+            file_out_docx=file_out_docx,
+            context=context,
+            markdown_body=markdown_body,
+            dir_base=dir_base,
+            style=self.style,
+            anchor_token=anchor_token,
+            should_update_fields=should_update_fields,
+            should_freeze_fields=should_freeze_fields,
+            field_refresh=field_refresh or self._field_refresh,
+        )
+
+    def write_docx(
+        self,
+        *,
+        file_template: Path,
+        file_out_docx: Path,
+        context: Mapping[str, Any],
+        markdown_body: str,
+        dir_base: Path,
+        anchor_token: str = "__REPORT_BODY_ANCHOR__",
+        should_update_fields: bool = True,
+        should_freeze_fields: bool = False,
+        field_refresh: DocxFieldRefreshOptions | None = None,
+    ) -> DocxWriteResult:
+        """Write a DOCX file using the fluent writer settings.
+
+        Args:
+            file_template (Path): Input DOCX template path.
+            file_out_docx (Path): Output DOCX path to write.
+            context (Mapping[str, Any]): Template context passed to `docxtpl`.
+            markdown_body (str): Markdown body to insert into the DOCX.
+            dir_base (Path): Base directory used to resolve relative image paths.
+            anchor_token (str): Paragraph text marking markdown insertion point.
+            should_update_fields (bool): Whether fields should be marked for update.
+            should_freeze_fields (bool): Whether fields should be frozen after writing.
+            field_refresh (DocxFieldRefreshOptions | None): Optional per-call field
+                refresh override.
+
+        Returns:
+            DocxWriteResult: Result containing the written DOCX path.
+        """
+
+        from docxrender.api import write_docx
+
+        return write_docx(
+            self.build_options(
+                file_template=file_template,
+                file_out_docx=file_out_docx,
+                context=context,
+                markdown_body=markdown_body,
+                dir_base=dir_base,
+                anchor_token=anchor_token,
+                should_update_fields=should_update_fields,
+                should_freeze_fields=should_freeze_fields,
+                field_refresh=field_refresh,
+            )
+        )

docxrender-0.1.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.1
+Name: docxrender
+Version: 0.1.0
+Summary: Minimal DOCX rendering core for template, markdown, field refresh, and PDF conversion workflows
+Author-Email: FuqingZhang <fuqin.zhang@proton.me>
+License: MIT
+Requires-Python: >=3.13
+Requires-Dist: docxtpl>=0.20.2
+Requires-Dist: python-docx>=1.2.0
+Description-Content-Type: text/markdown
+
+# docxrender
+
+`docxrender` is a small Python package for Word-first DOCX rendering.
+
+Its core boundary is intentionally narrow:
+
+```text
+file_template + context + markdown_body + DocxStyle -> DOCX -> PDF
+```
+
+The package owns technical rendering mechanics: DOCX template rendering,
+markdown body insertion, Word style application, DOCX field handling, and
+eventual LibreOffice-based PDF conversion. Product repositories own report
+content, workflow resource layout, section rendering, manifest schemas, figure
+selection, captions, and delivery directory semantics.
+
+## Status
+
+Current implementation:
+
+- Public style/options/result dataclasses are available.
+- `write_docx(...)` can create a minimal DOCX from a DOCX template, context,
+  markdown body, image assets, and `DocxStyle`.
+- Markdown support currently covers headings, paragraphs, hard line breaks,
+  ordered lists, tables, images, page breaks, and spacers.
+- Basic Word styling is applied from caller-provided `DocxStyle`.
+- DOCX field update/freeze behavior is implemented through DOCX XML rewriting.
+- `write_docx(...)` can optionally refresh TOC/page fields through LibreOffice
+  UNO when `DocxFieldRefreshOptions` is provided.
+- `convert_docx_to_pdf(...)` converts through LibreOffice UNO when the external
+  LibreOffice/UNO runtime is available.
+
+## Install For Local Development
+
+```bash
+pdm install
+```
+
+Runtime dependencies are declared in `pyproject.toml`:
+
+- `docxtpl`
+- `python-docx`
+
+PDF conversion and DOCX field refresh are optional runtime features. They do
+not require extra Python packages from `docxrender`, but they do require an
+external LibreOffice/UNO runtime.
+
+```bash
+libreoffice --headless --version
+python -c "import uno"
+```
+
+On Debian or Ubuntu, that runtime is typically installed outside Python:
+
+```bash
+sudo apt install libreoffice python3-uno
+```
+
+`docxrender` intentionally does not provide a `docxrender[pdf]` extra. Installing a
+Python package should not silently install system software or require
+administrator privileges. Base DOCX writing with `field_refresh=None` does not
+import UNO and works without LibreOffice.
+
+## Public API
+
+The stable public API is exported from the package root. Product repositories
+should prefer `from docxrender import ...`; implementation modules such as
+`docxrender.markdown` and `docxrender.docx` are technical
+layers and are not compatibility-stable public contracts.
+
+```python
+from docxrender import (
+    DocxWriter,
+    DocxFieldRefreshOptions,
+    DocxFontStyle,
+    DocxParagraphStyle,
+    DocxSizeStyle,
+    DocxStyle,
+    DocxTableStyle,
+    DocxWriteOptions,
+    write_docx,
+)
+```
+
+`DocxFieldRefreshOptions` is optional. Use it only when the caller has provided
+a LibreOffice/UNO runtime and wants a DOCX whose TOC, page fields, or other
+Word fields have been refreshed by LibreOffice:
+
+```python
+DocxWriteOptions(
+    ...,
+    field_refresh=DocxFieldRefreshOptions(
+        exe_libreoffice=Path("/usr/bin/libreoffice"),
+        dir_user_profile=Path("tmp/lo-profile"),
+        should_require_toc=True,
+        should_freeze_fields=True,
+    ),
+)
+```
+
+Minimal fluent DOCX write example:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxWriter
+
+result = (
+    DocxWriter()
+    .with_fonts(
+        font_name_latin="Times New Roman",
+        font_name_body_east_asia="宋体",
+        font_name_heading_east_asia="宋体",
+    )
+    .with_sizes(
+        pt_title_page_title=36.0,
+        pt_title_page_meta=18.0,
+        pt_title_page_compiler=15.0,
+        pt_body=12.0,
+        pt_caption=10.5,
+        pt_table=12.0,
+        pt_heading_by_level={1: 16.0, 2: 14.0, 3: 12.0},
+    )
+    .with_table(
+        border_color="000000",
+        stripe_fill_color="D9D9D9",
+        border_size_main="12",
+        border_size_header="6",
+        line_spacing=1.5,
+    )
+    .with_paragraph(
+        line_spacing_body=1.5,
+        line_spacing_note=1.2,
+        first_line_indent_cm=0.74,
+    )
+    .write_docx(
+        file_template=Path("template.docx"),
+        file_out_docx=Path("report.docx"),
+        context={"report_title": "Example Report"},
+        markdown_body="# Summary\n\nBody text.",
+        dir_base=Path("."),
+    )
+)
+print(result.file_docx)
+```
+
+`markdown_body` is the already-rendered Markdown body to insert into the DOCX
+template. `dir_base` is the base directory used to resolve relative image paths
+inside that Markdown body.
+
+Explicit dataclass DOCX write example:
+
+```python
+from pathlib import Path
+
+from docxrender import (
+    DocxFontStyle,
+    DocxParagraphStyle,
+    DocxSizeStyle,
+    DocxStyle,
+    DocxTableStyle,
+    DocxWriteOptions,
+    write_docx,
+)
+
+style = DocxStyle(
+    fonts=DocxFontStyle(
+        font_name_latin="Times New Roman",
+        font_name_body_east_asia="宋体",
+        font_name_heading_east_asia="宋体",
+    ),
+    sizes=DocxSizeStyle(
+        pt_title_page_title=36.0,
+        pt_title_page_meta=18.0,
+        pt_title_page_compiler=15.0,
+        pt_body=12.0,
+        pt_caption=10.5,
+        pt_table=12.0,
+        pt_heading_by_level={1: 16.0, 2: 14.0, 3: 12.0},
+    ),
+    table=DocxTableStyle(
+        border_color="000000",
+        stripe_fill_color="D9D9D9",
+        border_size_main="12",
+        border_size_header="6",
+        line_spacing=1.5,
+    ),
+    paragraph=DocxParagraphStyle(
+        line_spacing_body=1.5,
+        line_spacing_note=1.2,
+        first_line_indent_cm=0.74,
+    ),
+)
+
+result = write_docx(
+    DocxWriteOptions(
+        file_template=Path("template.docx"),
+        file_out_docx=Path("report.docx"),
+        context={"report_title": "Example Report"},
+        markdown_body="# Summary\n\nBody text.",
+        dir_base=Path("."),
+        style=style,
+    )
+)
+print(result.file_docx)
+```
+
+The template should contain a paragraph whose text is the body anchor token:
+
+```text
+{{ body_anchor }}
+```
+
+`docxrender` sets `body_anchor` in the template context when the caller does not
+provide it.
+
+## Style Configuration
+
+`docxrender` does not read TOML, JSON, YAML, or any other config file in its public
+API. Callers convert their own configuration into `DocxStyle`.
+
+The initial style model is based on:
+
+```text
+/home/fqzhang/project/workflows/resources/common/report/style.toml
+```
+
+That file is a reference for fields and defaults, not a runtime dependency of
+the package.
+
+## Non-Goals
+
+`docxrender` does not own:
+
+- report manifest schemas
+- workflow resource layout
+- Jinja section discovery
+- product-specific context builders
+- figure registries or captions
+- `Result/...` delivery path semantics
+- `结果目录` text generation
+- style config file readers
+
+## Tests
+
+Run the current test suite:
+
+```bash
+pdm run python -m pytest -v
+```
+
+`ty` is available as an advisory type checker beside pyright:
+
+```bash
+pdm run ty check .
+```
+
+Pyright remains the primary type gate.
+
+The suite currently covers public API construction, minimal DOCX writing,
+markdown body insertion, basic style application, and the boundary that
+`docxrender` does not import product repositories.

docxrender-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+docxrender-0.1.0.dist-info/METADATA,sha256=qSg_esY9mfCizzLt1bLY3QKChHJEz2-Q6vwN1f9dr_o,7372
+docxrender-0.1.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+docxrender-0.1.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+docxrender/__init__.py,sha256=88Ui9rkkK-QJM8gfdQzpil18Jz9r-XwgtR2RimNJkso,659
+docxrender/api.py,sha256=az-Sicnr60KOnoOtsV75izWlyha7fJvSwWfBeeOlGKE,2692
+docxrender/contracts.py,sha256=xzuj6fVp4oqnX2XMz0KBqV4UcQZBgO95Udxezjz8sTc,9199
+docxrender/docx/__init__.py,sha256=z-7-r9mkfr6l7UffCrRxhJCTxghnVSyClMlJnbBz4-8,39
+docxrender/docx/body.py,sha256=IRmgwY3tyCs9NSIjd0Mt1429RTkCs6uRO61almlbViM,11805
+docxrender/docx/fields.py,sha256=KYbmbkee9vd3mR0Y4Y0RxfQ6kuQQNWxokLRLmA0LCVk,4433
+docxrender/docx/refresh.py,sha256=PgEqWHpmUlvyJvne3oV-ejXbulF6geEiTj-moa4J_Rg,3669
+docxrender/markdown.py,sha256=mAy-lNzN0-EhcmT_6HQ97kDIf_4YGNzFaobEO_UtYhs,5045
+docxrender/pdf_uno.py,sha256=yMTer-5ri_SDRl2lWqQ3XjbnOFgczJmwzDI1LulAj-8,20147
+docxrender/writer.py,sha256=0ubd1viSWIcfuSQj-sA-4HZNPxW8geQNMnJndKSJiUQ,15152
+docxrender-0.1.0.dist-info/RECORD,,