docxrender 0.1.0__tar.gz → 0.1.1__tar.gz

{docxrender-0.1.0 → docxrender-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: docxrender
-Version: 0.1.0
+Version: 0.1.1
 Summary: Minimal DOCX rendering core for template, markdown, field refresh, and PDF conversion workflows
 Author-Email: FuqingZhang <fuqin.zhang@proton.me>
 License: MIT
@@ -25,15 +25,17 @@ 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
+## Capabilities
 
-Current implementation:
+Current package surface:
 
 - 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.
+- Markdown support currently covers a CommonMark-ish shared subset: headings,
+  paragraphs, hard line breaks, unordered lists, ordered lists, pipe tables,
+  images, inline bold, inline code text cleanup, link-text reduction, 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
@@ -41,7 +43,7 @@ Current implementation:
 - `convert_docx_to_pdf(...)` converts through LibreOffice UNO when the external
   LibreOffice/UNO runtime is available.
 
-## Install For Local Development
+## Install
 
 ```bash
 pdm install
@@ -53,8 +55,7 @@ Runtime dependencies are declared in `pyproject.toml`:
 - `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.
+require an external LibreOffice/UNO runtime.
 
 ```bash
 libreoffice --headless --version
@@ -67,32 +68,56 @@ On Debian or Ubuntu, that runtime is typically installed outside Python:
 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.
+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.
+should prefer `DocxRenderer` for normal use. The dataclasses and module-level
+functions remain public for advanced callers that want explicit contracts,
+configuration adapters, or focused tests. Implementation modules such as
+`docxrender.markdown` and `docxrender.docx` are technical layers and are not
+compatibility-stable public contracts.
+
+`DocxRenderer` follows value semantics. Every `with_*` call returns a new
+renderer object and leaves the original unchanged. Runtime `docxtpl` objects,
+including inline images, are materialized only by terminal methods such as
+`write_docx_template(...)`, `write_docx(...)`, and `write_pdf()`.
 
 ```python
 from docxrender import (
-    DocxWriter,
+    DocxRenderer,
+    DocxBodyAnchorOptions,
+    DocxBodyRenderPolicy,
+    DocxFieldMarkerOptions,
     DocxFieldRefreshOptions,
     DocxFontStyle,
+    DocxHeaderFooterImageOptions,
+    DocxMarkdownOptions,
     DocxParagraphStyle,
     DocxSizeStyle,
     DocxStyle,
     DocxTableStyle,
+    DocxTemplateContextPolicy,
+    DocxTemplateImageSpec,
+    DocxTemplateRenderOptions,
     DocxWriteOptions,
+    write_docx_template,
     write_docx,
 )
 ```
 
+`DocxFieldMarkerOptions` controls DOCX field update markers and field freezing
+without LibreOffice or UNO:
+
+```python
+DocxRenderer(file_docx=Path("report.docx")).with_field_update_markers(
+    should_update_fields=True,
+    should_freeze_fields=False,
+).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:
@@ -109,15 +134,52 @@ DocxWriteOptions(
 )
 ```
 
-Minimal fluent DOCX write example:
+`write_docx_template(...)` is the generic `docxtpl` technical boundary. It
+renders a DOCX template with caller context, optional inline images, and
+optional default injections. It does not insert markdown bodies, apply DOCX
+body styling, or run field/PDF post-processing:
 
 ```python
 from pathlib import Path
 
-from docxrender import DocxWriter
+from docxrender import DocxTemplateRenderOptions, write_docx_template
+
+result = write_docx_template(
+    DocxTemplateRenderOptions(
+        file_template=Path("template.docx"),
+        file_out_docx=Path("template-rendered.docx"),
+        context={"report_title": "Example Report"},
+        context_defaults={"body_anchor": "__REPORT_BODY_ANCHOR__"},
+        context_policy=DocxTemplateContextPolicy(
+            rule_conflict="caller_wins",
+            required_keys=("report_title",),
+        ),
+    )
+)
+print(result.file_docx)
+```
+
+`DocxTemplateContextPolicy` controls:
+
+- merge behavior between caller context and default injections
+- conflict priority: `caller_wins` or `defaults_win`
+- required keys that must exist after merge and before render
+
+Minimal `DocxRenderer` DOCX write example:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
 
 result = (
-    DocxWriter()
+    DocxRenderer()
+    .with_template(
+        file_template=Path("template.docx"),
+        context={"report_title": "Example Report"},
+        rule_conflict="caller_wins",
+        required_keys=("report_title",),
+    )
     .with_fonts(
         font_name_latin="Times New Roman",
         font_name_body_east_asia="宋体",
@@ -144,11 +206,28 @@ result = (
         line_spacing_note=1.2,
         first_line_indent_cm=0.74,
     )
+    .with_header_footer_images(
+        file_header_image=Path("header.png"),
+        file_footer_image=Path("footer.png"),
+        idx_section_start=1,
+    )
+    .with_markdown(
+        should_parse_inline_bold=True,
+        should_parse_inline_code=True,
+        should_parse_links_as_text=True,
+        should_parse_image_width_attr=True,
+        default_image_width_pct=90.0,
+    )
+    .with_body_render_policy(
+        should_number_headings=False,
+        rule_ordered_list="word_style",
+        rule_unordered_list="word_style",
+        should_stripe_table_rows=False,
+    )
+    .with_body_anchor(rule_match="equals", rule_missing="raise")
     .write_docx(
-        file_template=Path("template.docx"),
         file_out_docx=Path("report.docx"),
-        context={"report_title": "Example Report"},
-        markdown_body="# Summary\n\nBody text.",
+        markdown_body="# Summary **Bold**\n\nBody text with [link](https://example.com).",
         dir_base=Path("."),
     )
 )
@@ -159,7 +238,76 @@ print(result.file_docx)
 template. `dir_base` is the base directory used to resolve relative image paths
 inside that Markdown body.
 
-Explicit dataclass DOCX write example:
+`DocxMarkdownOptions` only covers the shared CommonMark-ish subset. Product
+repositories should keep custom markdown dialects outside `docxrender`, either
+through caller-side preprocessing or explicit higher-level options in their own
+repo.
+
+`DocxBodyRenderPolicy` controls structural rendering choices such as heading
+numbering, Word-style versus plain-text lists, and striped table body rows. It
+does not classify product-specific paragraphs.
+
+`DocxBodyAnchorOptions` controls where the Markdown body is inserted. The search
+is limited to top-level body paragraphs in the DOCX main document. `equals`
+matches `paragraph.text.strip() == anchor_token`; `contains` matches templates
+where the token is embedded in a larger paragraph. Missing anchors can either
+append content or raise a template error.
+
+`DocxRenderer` can also start from an existing DOCX and run only later
+technical steps:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
+
+DocxRenderer(file_docx=Path("report.docx")).with_field_refresh(
+    exe_libreoffice=Path("/usr/bin/libreoffice"),
+    dir_user_profile=Path("tmp/lo-profile"),
+    should_require_toc=True,
+).write_docx()
+```
+
+Generic `docxtpl` inline-image binding is also supported through the same
+template entrypoint:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer, DocxTemplateImageSpec
+
+renderer = DocxRenderer().with_template(
+    file_template=Path("template.docx"),
+    context={"report_title": "Example Report"},
+    inline_images={
+        "cover_image": DocxTemplateImageSpec(
+            file_image=Path("cover.png"),
+            width_mm=120,
+        ),
+    },
+)
+```
+
+The same renderer can convert the current DOCX to PDF:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
+
+result = (
+    DocxRenderer(file_docx=Path("report.docx"))
+    .with_pdf_conversion(
+        exe_libreoffice=Path("/usr/bin/libreoffice"),
+        dir_user_profile=Path("tmp/lo-profile"),
+        file_out_pdf=Path("report.pdf"),
+    )
+    .write_pdf()
+)
+print(result.file_pdf)
+```
+
+Advanced explicit dataclass DOCX write example:
 
 ```python
 from pathlib import Path

{docxrender-0.1.0 → docxrender-0.1.1}/README.md

@@ -14,15 +14,17 @@ 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
+## Capabilities
 
-Current implementation:
+Current package surface:
 
 - 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.
+- Markdown support currently covers a CommonMark-ish shared subset: headings,
+  paragraphs, hard line breaks, unordered lists, ordered lists, pipe tables,
+  images, inline bold, inline code text cleanup, link-text reduction, 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
@@ -30,7 +32,7 @@ Current implementation:
 - `convert_docx_to_pdf(...)` converts through LibreOffice UNO when the external
   LibreOffice/UNO runtime is available.
 
-## Install For Local Development
+## Install
 
 ```bash
 pdm install
@@ -42,8 +44,7 @@ Runtime dependencies are declared in `pyproject.toml`:
 - `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.
+require an external LibreOffice/UNO runtime.
 
 ```bash
 libreoffice --headless --version
@@ -56,32 +57,56 @@ On Debian or Ubuntu, that runtime is typically installed outside Python:
 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.
+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.
+should prefer `DocxRenderer` for normal use. The dataclasses and module-level
+functions remain public for advanced callers that want explicit contracts,
+configuration adapters, or focused tests. Implementation modules such as
+`docxrender.markdown` and `docxrender.docx` are technical layers and are not
+compatibility-stable public contracts.
+
+`DocxRenderer` follows value semantics. Every `with_*` call returns a new
+renderer object and leaves the original unchanged. Runtime `docxtpl` objects,
+including inline images, are materialized only by terminal methods such as
+`write_docx_template(...)`, `write_docx(...)`, and `write_pdf()`.
 
 ```python
 from docxrender import (
-    DocxWriter,
+    DocxRenderer,
+    DocxBodyAnchorOptions,
+    DocxBodyRenderPolicy,
+    DocxFieldMarkerOptions,
     DocxFieldRefreshOptions,
     DocxFontStyle,
+    DocxHeaderFooterImageOptions,
+    DocxMarkdownOptions,
     DocxParagraphStyle,
     DocxSizeStyle,
     DocxStyle,
     DocxTableStyle,
+    DocxTemplateContextPolicy,
+    DocxTemplateImageSpec,
+    DocxTemplateRenderOptions,
     DocxWriteOptions,
+    write_docx_template,
     write_docx,
 )
 ```
 
+`DocxFieldMarkerOptions` controls DOCX field update markers and field freezing
+without LibreOffice or UNO:
+
+```python
+DocxRenderer(file_docx=Path("report.docx")).with_field_update_markers(
+    should_update_fields=True,
+    should_freeze_fields=False,
+).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:
@@ -98,15 +123,52 @@ DocxWriteOptions(
 )
 ```
 
-Minimal fluent DOCX write example:
+`write_docx_template(...)` is the generic `docxtpl` technical boundary. It
+renders a DOCX template with caller context, optional inline images, and
+optional default injections. It does not insert markdown bodies, apply DOCX
+body styling, or run field/PDF post-processing:
 
 ```python
 from pathlib import Path
 
-from docxrender import DocxWriter
+from docxrender import DocxTemplateRenderOptions, write_docx_template
+
+result = write_docx_template(
+    DocxTemplateRenderOptions(
+        file_template=Path("template.docx"),
+        file_out_docx=Path("template-rendered.docx"),
+        context={"report_title": "Example Report"},
+        context_defaults={"body_anchor": "__REPORT_BODY_ANCHOR__"},
+        context_policy=DocxTemplateContextPolicy(
+            rule_conflict="caller_wins",
+            required_keys=("report_title",),
+        ),
+    )
+)
+print(result.file_docx)
+```
+
+`DocxTemplateContextPolicy` controls:
+
+- merge behavior between caller context and default injections
+- conflict priority: `caller_wins` or `defaults_win`
+- required keys that must exist after merge and before render
+
+Minimal `DocxRenderer` DOCX write example:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
 
 result = (
-    DocxWriter()
+    DocxRenderer()
+    .with_template(
+        file_template=Path("template.docx"),
+        context={"report_title": "Example Report"},
+        rule_conflict="caller_wins",
+        required_keys=("report_title",),
+    )
     .with_fonts(
         font_name_latin="Times New Roman",
         font_name_body_east_asia="宋体",
@@ -133,11 +195,28 @@ result = (
         line_spacing_note=1.2,
         first_line_indent_cm=0.74,
     )
+    .with_header_footer_images(
+        file_header_image=Path("header.png"),
+        file_footer_image=Path("footer.png"),
+        idx_section_start=1,
+    )
+    .with_markdown(
+        should_parse_inline_bold=True,
+        should_parse_inline_code=True,
+        should_parse_links_as_text=True,
+        should_parse_image_width_attr=True,
+        default_image_width_pct=90.0,
+    )
+    .with_body_render_policy(
+        should_number_headings=False,
+        rule_ordered_list="word_style",
+        rule_unordered_list="word_style",
+        should_stripe_table_rows=False,
+    )
+    .with_body_anchor(rule_match="equals", rule_missing="raise")
     .write_docx(
-        file_template=Path("template.docx"),
         file_out_docx=Path("report.docx"),
-        context={"report_title": "Example Report"},
-        markdown_body="# Summary\n\nBody text.",
+        markdown_body="# Summary **Bold**\n\nBody text with [link](https://example.com).",
         dir_base=Path("."),
     )
 )
@@ -148,7 +227,76 @@ print(result.file_docx)
 template. `dir_base` is the base directory used to resolve relative image paths
 inside that Markdown body.
 
-Explicit dataclass DOCX write example:
+`DocxMarkdownOptions` only covers the shared CommonMark-ish subset. Product
+repositories should keep custom markdown dialects outside `docxrender`, either
+through caller-side preprocessing or explicit higher-level options in their own
+repo.
+
+`DocxBodyRenderPolicy` controls structural rendering choices such as heading
+numbering, Word-style versus plain-text lists, and striped table body rows. It
+does not classify product-specific paragraphs.
+
+`DocxBodyAnchorOptions` controls where the Markdown body is inserted. The search
+is limited to top-level body paragraphs in the DOCX main document. `equals`
+matches `paragraph.text.strip() == anchor_token`; `contains` matches templates
+where the token is embedded in a larger paragraph. Missing anchors can either
+append content or raise a template error.
+
+`DocxRenderer` can also start from an existing DOCX and run only later
+technical steps:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
+
+DocxRenderer(file_docx=Path("report.docx")).with_field_refresh(
+    exe_libreoffice=Path("/usr/bin/libreoffice"),
+    dir_user_profile=Path("tmp/lo-profile"),
+    should_require_toc=True,
+).write_docx()
+```
+
+Generic `docxtpl` inline-image binding is also supported through the same
+template entrypoint:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer, DocxTemplateImageSpec
+
+renderer = DocxRenderer().with_template(
+    file_template=Path("template.docx"),
+    context={"report_title": "Example Report"},
+    inline_images={
+        "cover_image": DocxTemplateImageSpec(
+            file_image=Path("cover.png"),
+            width_mm=120,
+        ),
+    },
+)
+```
+
+The same renderer can convert the current DOCX to PDF:
+
+```python
+from pathlib import Path
+
+from docxrender import DocxRenderer
+
+result = (
+    DocxRenderer(file_docx=Path("report.docx"))
+    .with_pdf_conversion(
+        exe_libreoffice=Path("/usr/bin/libreoffice"),
+        dir_user_profile=Path("tmp/lo-profile"),
+        file_out_pdf=Path("report.pdf"),
+    )
+    .write_pdf()
+)
+print(result.file_pdf)
+```
+
+Advanced explicit dataclass DOCX write example:
 
 ```python
 from pathlib import Path

{docxrender-0.1.0 → docxrender-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docxrender"
-version = "0.1.0"
+version = "0.1.1"
 description = "Minimal DOCX rendering core for template, markdown, field refresh, and PDF conversion workflows"
 authors = [
     { name = "FuqingZhang", email = "fuqin.zhang@proton.me" },

docxrender-0.1.1/src/docxrender/__init__.py

@@ -0,0 +1,50 @@
+from docxrender.api import convert_docx_to_pdf, write_docx
+from docxrender.contracts import (
+    DocxBodyAnchorOptions,
+    DocxBodyRenderPolicy,
+    DocxFieldMarkerOptions,
+    DocxFieldRefreshOptions,
+    DocxFontStyle,
+    DocxHeaderFooterImageOptions,
+    DocxMarkdownOptions,
+    DocxParagraphStyle,
+    DocxSizeStyle,
+    DocxStyle,
+    DocxTableStyle,
+    DocxTemplateContextPolicy,
+    DocxTemplateImageSpec,
+    DocxTemplateRenderOptions,
+    DocxTemplateRenderResult,
+    DocxToPdfOptions,
+    DocxToPdfResult,
+    DocxWriteOptions,
+    DocxWriteResult,
+)
+from docxrender.renderer import DocxRenderer
+from docxrender.template import write_docx_template
+
+__all__ = [
+    "DocxRenderer",
+    "DocxBodyAnchorOptions",
+    "DocxBodyRenderPolicy",
+    "DocxFieldMarkerOptions",
+    "DocxFieldRefreshOptions",
+    "DocxFontStyle",
+    "DocxHeaderFooterImageOptions",
+    "DocxMarkdownOptions",
+    "DocxParagraphStyle",
+    "DocxSizeStyle",
+    "DocxStyle",
+    "DocxTableStyle",
+    "DocxTemplateContextPolicy",
+    "DocxTemplateImageSpec",
+    "DocxTemplateRenderOptions",
+    "DocxTemplateRenderResult",
+    "DocxToPdfOptions",
+    "DocxToPdfResult",
+    "DocxWriteOptions",
+    "DocxWriteResult",
+    "convert_docx_to_pdf",
+    "write_docx_template",
+    "write_docx",
+]