ymprint 0.1.0__tar.gz

ymprint-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: ymprint
+Version: 0.1.0
+Summary: Desktop publishing in YAML with Python
+Author: Connor Ferster
+Author-email: Connor Ferster <connor@structuralpython.com>
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pygments>=2.20.0
+Requires-Dist: pymupdf>=1.27.2.3
+Requires-Dist: pypdf>=6.14.0
+Requires-Dist: reportlab>=4.5.1
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: typer>=0.26.7
+Requires-Dist: wenmode>=0.8.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="ymprintlogolarge.png" alt="YMPrint" width="420">
+</p>
+
+<h3 align="center">Desktop publishing with YAML</h3>
+<p align="center"><em>The technology of the year 2000…today!</em></p>
+
+YMPrint is a Python-based PDF authoring application geared towards professionals who need to
+generate lots of PDF documents. You write the content of your report in YAML (as opposed to
+Markdown) and YMPrint renders it to PDF with near-instant speeds. YMPrint lets you use Python
+scripting within your document, create variables, render variable values, and pass live
+Python objects between report **blocks** to create a truly expressive authoring
+system—the likes of which have not been created before.
+
+```yaml
+Site inspection report:
+  - >
+    This is the first paragraph. The `>` character tells YAML you are entering a
+    multi-line string that should be word-wrapped. Leave a blank line to start a
+    new paragraph.
+  - Findings:
+    - Bullets:
+      - The handrail is loose on the north stair.
+      - Two ceiling tiles are water-stained in the lobby.
+    - Items observed:
+      - Item Number: 12.01
+        Description: There is a problem here. This report documents it.
+        Location: Under the stairs
+```
+
+```bash
+ym convert report.yml
+# ✍️ .... 📝 ... PDF created: report.pdf
+```
+
+## Why YMPrint?
+
+- **Readable source.** Your document *is* the outline. YAML nesting is the document
+  hierarchy — no markup soup, no LaTeX, no HTML.
+- **Batteries included.** Bundled fonts, sensible default styles, and a set of blocks for
+  the content markdown can't express.
+- **Dynamic content.** Interpolate variables with Jinja, execute `_py` blocks, load JSON,
+  embed matplotlib figures, and auto-fill PDF form fields.
+- **Custom templates.** Overlay your document onto a designed PDF background and
+  auto-populate its form fields from document variables.
+
+## Installation
+
+Requires **Python 3.14+**.
+
+```bash
+# With uv (recommended) — installs the `ym` command
+uv tool install ymprint
+
+# Or with pip
+pip install ymprint
+```
+
+From source:
+
+```bash
+git clone https://github.com/StructuralPython/yamlreports.git
+cd yamlreports
+uv sync
+uv run ym --help
+```
+
+## Usage
+
+YMPrint installs a single command, `ym`, with two subcommands.
+
+### `ym convert` — render once
+
+```bash
+ym convert report.yml               # writes report.pdf next to the source
+ym convert report.yml out/doc.pdf   # choose an output path
+```
+
+### `ym live` — hot-reload preview
+
+Renders the PDF, opens it in the [Okular](https://okular.kde.org/) viewer, and rebuilds on
+every save. Great for drafting.
+
+```bash
+ym live report.yml
+```
+
+## Core concepts
+
+- **Keys are headings.** A mapping key whose value is content becomes a heading; the value
+  is laid out underneath it. Lists render in order, lists of mappings render as tables.
+- **Configuration** lives in underscore-prefixed front matter — `_doc` (page template),
+  `_style` (text styles), and `_tablestyle` (table styles) — resolved across three
+  inheriting priority levels: internal defaults → project config → document front matter.
+- **Variables** are defined in `_vars`, interpolated into text with Jinja (`{{name}}`), and
+  passed as real Python objects into blocks with the `$name` syntax.
+- **Blocks** are underscore-prefixed keys that expand into custom content:
+
+  | Block | Purpose |
+  | --- | --- |
+  | `_img` | Embed an image with a caption |
+  | `_matplotfig` | Embed a matplotlib figure |
+  | `_info` / `_warning` / `_danger` / `_tip` / `_note` | Admonition callouts |
+  | `_blockquote` | A quotation with attribution |
+  | `_code` | A non-executable, syntax-highlighted code block |
+  | `_py` | Execute Python and optionally show the source |
+  | `_loadjson` | Load variables from a JSON file |
+  | `_pagebreak` | Force a page break |
+  | `_hrule` | A configurable horizontal rule |
+  | `_spacer` | Insert vertical whitespace |
+
+## Examples
+
+The [`Examples/`](Examples) directory contains a runnable report for each major feature —
+a simple document, document configuration, variables, PDF backgrounds, Python execution,
+and the full set of blocks. Render any of them with `ym convert`.
+
+## Documentation
+
+The full documentation site lives in [`docs/`](docs) (Sphinx + the Shibuya theme). Build it
+locally with:
+
+```bash
+uv run --with-requirements docs/requirements.txt \
+    sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`. See [`docs/README.md`](docs/README.md) for details.
+
+## License
+
+See [LICENSE](LICENSE).

ymprint-0.1.0/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <img src="ymprintlogolarge.png" alt="YMPrint" width="420">
+</p>
+
+<h3 align="center">Desktop publishing with YAML</h3>
+<p align="center"><em>The technology of the year 2000…today!</em></p>
+
+YMPrint is a Python-based PDF authoring application geared towards professionals who need to
+generate lots of PDF documents. You write the content of your report in YAML (as opposed to
+Markdown) and YMPrint renders it to PDF with near-instant speeds. YMPrint lets you use Python
+scripting within your document, create variables, render variable values, and pass live
+Python objects between report **blocks** to create a truly expressive authoring
+system—the likes of which have not been created before.
+
+```yaml
+Site inspection report:
+  - >
+    This is the first paragraph. The `>` character tells YAML you are entering a
+    multi-line string that should be word-wrapped. Leave a blank line to start a
+    new paragraph.
+  - Findings:
+    - Bullets:
+      - The handrail is loose on the north stair.
+      - Two ceiling tiles are water-stained in the lobby.
+    - Items observed:
+      - Item Number: 12.01
+        Description: There is a problem here. This report documents it.
+        Location: Under the stairs
+```
+
+```bash
+ym convert report.yml
+# ✍️ .... 📝 ... PDF created: report.pdf
+```
+
+## Why YMPrint?
+
+- **Readable source.** Your document *is* the outline. YAML nesting is the document
+  hierarchy — no markup soup, no LaTeX, no HTML.
+- **Batteries included.** Bundled fonts, sensible default styles, and a set of blocks for
+  the content markdown can't express.
+- **Dynamic content.** Interpolate variables with Jinja, execute `_py` blocks, load JSON,
+  embed matplotlib figures, and auto-fill PDF form fields.
+- **Custom templates.** Overlay your document onto a designed PDF background and
+  auto-populate its form fields from document variables.
+
+## Installation
+
+Requires **Python 3.14+**.
+
+```bash
+# With uv (recommended) — installs the `ym` command
+uv tool install ymprint
+
+# Or with pip
+pip install ymprint
+```
+
+From source:
+
+```bash
+git clone https://github.com/StructuralPython/yamlreports.git
+cd yamlreports
+uv sync
+uv run ym --help
+```
+
+## Usage
+
+YMPrint installs a single command, `ym`, with two subcommands.
+
+### `ym convert` — render once
+
+```bash
+ym convert report.yml               # writes report.pdf next to the source
+ym convert report.yml out/doc.pdf   # choose an output path
+```
+
+### `ym live` — hot-reload preview
+
+Renders the PDF, opens it in the [Okular](https://okular.kde.org/) viewer, and rebuilds on
+every save. Great for drafting.
+
+```bash
+ym live report.yml
+```
+
+## Core concepts
+
+- **Keys are headings.** A mapping key whose value is content becomes a heading; the value
+  is laid out underneath it. Lists render in order, lists of mappings render as tables.
+- **Configuration** lives in underscore-prefixed front matter — `_doc` (page template),
+  `_style` (text styles), and `_tablestyle` (table styles) — resolved across three
+  inheriting priority levels: internal defaults → project config → document front matter.
+- **Variables** are defined in `_vars`, interpolated into text with Jinja (`{{name}}`), and
+  passed as real Python objects into blocks with the `$name` syntax.
+- **Blocks** are underscore-prefixed keys that expand into custom content:
+
+  | Block | Purpose |
+  | --- | --- |
+  | `_img` | Embed an image with a caption |
+  | `_matplotfig` | Embed a matplotlib figure |
+  | `_info` / `_warning` / `_danger` / `_tip` / `_note` | Admonition callouts |
+  | `_blockquote` | A quotation with attribution |
+  | `_code` | A non-executable, syntax-highlighted code block |
+  | `_py` | Execute Python and optionally show the source |
+  | `_loadjson` | Load variables from a JSON file |
+  | `_pagebreak` | Force a page break |
+  | `_hrule` | A configurable horizontal rule |
+  | `_spacer` | Insert vertical whitespace |
+
+## Examples
+
+The [`Examples/`](Examples) directory contains a runnable report for each major feature —
+a simple document, document configuration, variables, PDF backgrounds, Python execution,
+and the full set of blocks. Render any of them with `ym convert`.
+
+## Documentation
+
+The full documentation site lives in [`docs/`](docs) (Sphinx + the Shibuya theme). Build it
+locally with:
+
+```bash
+uv run --with-requirements docs/requirements.txt \
+    sphinx-build -b html docs docs/_build/html
+```
+
+Then open `docs/_build/html/index.html`. See [`docs/README.md`](docs/README.md) for details.
+
+## License
+
+See [LICENSE](LICENSE).

ymprint-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "ymprint"
+version = "0.1.0"
+description = "Desktop publishing in YAML with Python"
+readme = "README.md"
+authors = [
+    { name = "Connor Ferster", email = "connor@structuralpython.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "jinja2>=3.1.6",
+    "pydantic>=2.13.4",
+    "pygments>=2.20.0",
+    "pymupdf>=1.27.2.3",
+    "pypdf>=6.14.0",
+    "reportlab>=4.5.1",
+    "ruamel-yaml>=0.19.1",
+    "typer>=0.26.7",
+    "wenmode>=0.8.0",
+]
+
+[project.scripts]
+ym = "ymprint.cli.main:app"
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "matplotlib>=3.11.0",
+    "pytest>=9.0.3",
+    "rich>=15.0.0",
+]

ymprint-0.1.0/src/ymprint/__init__.py

@@ -0,0 +1,2 @@
+from ymprint import config
+from ymprint import blocks

ymprint-0.1.0/src/ymprint/blocks/__init__.py

@@ -0,0 +1,107 @@
+import re
+
+from typing import Callable, Optional, Union, TypeAlias, Any
+
+from reportlab.platypus import (
+    Paragraph,
+    Spacer,
+    Table,
+    Image,
+    HRFlowable,
+    KeepTogether,
+)
+from reportlab.lib.units import mm
+from ymprint.config.docstyles import ReportStyles
+from ..content_checks import check_for_variable
+
+RLFlowables: TypeAlias = Union[Paragraph, Spacer, Table, KeepTogether, Image]
+
+YAML_Values: TypeAlias =Union[str, list, dict, float, int, None]
+
+# TODO: Create a block registration function and a singleton block registry
+
+class BlockExistsError(Exception):
+    pass
+
+def create_block_registry() -> tuple[Callable, Callable, Callable]:
+    """
+    Creates the block registry
+    """
+    _BLOCK_REGISTRY = {}
+
+    def register_block(block_code: str, block_convert: Callable) -> None:
+        """
+        Returns None. Adds a new block to the block registry.
+
+        'block_code': a str of the form '_{code}' where 'code' is an alphanumeric code used
+            to identify the block.
+        'block_convert':a function with the following signature:
+            my_func(obj: dict, context: dict) -> list[Flowable] 
+
+            Where:
+                obj: a dict which has a key that starts with the block code and a value
+                    which is a user-defined data structure that contains the data needed
+                    to generate the block as a ReportLab Flowable.
+                context: a dict that contains all of the internal state of this program
+                    at the time the conversion is executed. This will get passed to your 
+                    function automatically and gives your conversion function access to 
+                    anything and everything it needs to render your custom block. 
+                    Feel free to explore the context dict by using a print(context) call
+                    in your function.
+                
+            Return:
+                A list of ReportLab Flowable from the reportlab.platypus module. Your custom
+                block may be just one flowable (like a custom-populated table) or it can
+                be a list of many flowable. 
+        """
+        _BLOCK_REGISTRY.update({block_code: block_convert})
+
+    def list_blocks():
+        return list(_BLOCK_REGISTRY.keys())
+    
+    def get_block_callable(block_code: str) -> Optional[Callable]:
+        return _BLOCK_REGISTRY.get(block_code)
+
+    return list_blocks, get_block_callable, register_block
+
+list_blocks, get_block_callable, register_block = create_block_registry()
+
+def convert_blocks(block_key: str, block_value: YAML_Values, context: dict) -> list[RLFlowables]:
+    block_code_pattern = re.compile(r"(^_[a-zA-Z0-9]+)")
+    matches = block_code_pattern.match(block_key)
+    if matches is not None:
+        block_code = matches.groups()[0]
+    else:
+        raise ValueError(f"Block code not found within block key: {block_key=}")
+    block_converter = get_block_callable(block_code)
+    block_value_w_python_objects = retrieve_block_variables(block_value, context)
+    flowables = block_converter(block_key, block_value_w_python_objects, context)
+    return flowables
+
+
+def retrieve_block_variables(block_value: YAML_Values, context: dict) -> YAML_Values:
+    """
+    Returns 'block_value' but with list values or dictionary values that have
+    the "$VAR" syntax substituted with the object values
+    """
+    if isinstance(block_value, str) and check_for_variable(block_value, context):
+        var_name = get_variable_name(block_value)
+        return context['vars'].get(var_name, block_value)
+    elif isinstance(block_value, list):
+        acc = []
+        for elem in block_value:
+            new_elem = retrieve_block_variables(elem, context)
+            acc.append(new_elem)
+        return acc
+    elif isinstance(block_value, dict):
+        acc = {}
+        for k, v in block_value.items():
+            new_v = retrieve_block_variables(v, context)
+            acc.update({k: new_v})
+        return acc
+    else:
+        return block_value
+
+
+def get_variable_name(var_string: str) -> str:
+    return var_string.lstrip('$')

ymprint-0.1.0/src/ymprint/blocks/admonition_block.py

@@ -0,0 +1,42 @@
+from reportlab.platypus import Table, Paragraph, Spacer, KeepTogether
+from . import register_block
+from typing import Callable, Any
+from . import blockstyles
+
+def generate_admonition_block(kind: str) -> Callable:
+    """
+    Returns a callable to render that particular admonition type
+    """
+    
+
+    def convert_admonition_block(block_key: str, block_value: Any, context: dict) -> list[KeepTogether | Spacer]:
+        # Need an admonition block style or style modification
+        available_width = context['frames']['all_pages']['width']
+        text_spacing = context['styles']['ymprint'].body.spacing
+        text_size = context['styles']['ymprint'].body.size
+        space_around = text_spacing * text_size
+        width_ratio = 0.8
+        block_width = width_ratio * available_width
+        value = block_value
+        tablestyle = blockstyles.get_table_style(kind)
+        body_textstyle = blockstyles.get_text_styles().get(f'admonition_{kind}_body')
+        title_textstyle = blockstyles.get_text_styles().get(f'admonition_{kind}_title')
+        notice = Paragraph(text=blockstyles.admonition_title_text(kind), style=title_textstyle)
+        content = Paragraph(text=value, style=body_textstyle)
+        table = Table(
+            data=[[notice], [content]],
+            colWidths=[block_width],
+            style=tablestyle,
+            spaceBefore=space_around,
+            spaceAfter=space_around
+        )    
+        return [KeepTogether(table), Spacer(1, 10)]
+    
+    return convert_admonition_block
+
+
+register_block("_info", generate_admonition_block("info"))
+register_block("_warning", generate_admonition_block("warning"))
+register_block("_danger", generate_admonition_block("danger"))
+register_block("_tip", generate_admonition_block("tip"))
+register_block("_note", generate_admonition_block("note"))