pdfrender 0.1.0__py3-none-any.whl

pdf_render/templates/rendering.py

@@ -0,0 +1,75 @@
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from jinja2 import FileSystemLoader
+
+from pdf_render.data.accessor import DBAccessor
+from pdf_render.import_functions import get_functions_by_prefix_from_modules
+from pdf_render.templates.environment import TypedVariableEnvironment
+
+
+def new_template_environment(
+    templates_dir: Path,
+    filters_modules: str | Sequence[str] = None,
+    filters_func_prefix: str = "jinja_filter",
+    tests_modules: str | Sequence[str] = None,
+    tests_func_prefix: str = "jinja_test",
+    trim_func_prefix: bool = True,
+    db_accessor: DBAccessor = None,
+    globals_mapping: Mapping[str, Any] = None,
+    **jinja2_env_kwargs,
+) -> TypedVariableEnvironment:
+    """Build a `TypedVariableEnvironment` wired up with filters, tests, and globals.
+
+    Discovers Jinja2 filter/test functions by name prefix from
+    `pdf_render.templates.filters`/`pdf_render.templates.tests` plus any
+    additional modules given, and registers them on the returned
+    environment. A `DBAccessor` (or plain mapping) can be supplied as the
+    environment's globals so templates can query the database directly.
+
+    Args:
+        templates_dir: The directory to load templates from.
+        filters_modules: Additional dotted module path(s) to search for
+            filter functions.
+        filters_func_prefix: The function name prefix that marks a function
+            as a Jinja2 filter.
+        tests_modules: Additional dotted module path(s) to search for test
+            functions.
+        tests_func_prefix: The function name prefix that marks a function as
+            a Jinja2 test.
+        trim_func_prefix: Whether to strip the prefix from the registered
+            filter/test name.
+        db_accessor: A `DBAccessor` (or mapping) to use as the environment's
+            globals, enabling database access from templates.
+        globals_mapping: Additional global variables to merge into the
+            environment's globals.
+        **jinja2_env_kwargs: Additional keyword arguments passed through to
+            `TypedVariableEnvironment`/`jinja2.Environment`.
+            See [Jinja2.Environment docs](https://jinja.palletsprojects.com/en/stable/api/#jinja2.Environment)
+
+    Returns:
+        A configured `TypedVariableEnvironment`.
+    """
+    filter_module_names = ["pdf_render.templates.filters"]
+    if isinstance(filters_modules, str):
+        filter_module_names.append(filters_modules)
+    elif isinstance(filters_modules, Sequence):
+        filter_module_names = [*filters_modules, *filter_module_names]
+    filters_dict = get_functions_by_prefix_from_modules(filter_module_names, filters_func_prefix, trim_func_prefix)
+
+    tests_module_names = ["pdf_render.templates.tests"]
+    if isinstance(tests_modules, str):
+        tests_module_names.append(tests_modules)
+    elif isinstance(filters_modules, Sequence):
+        tests_module_names = (*tests_modules, tests_module_names)
+    tests_dict = get_functions_by_prefix_from_modules(tests_module_names, tests_func_prefix, trim_func_prefix)
+
+    environment_loader = FileSystemLoader(searchpath=templates_dir)
+    environment = TypedVariableEnvironment(loader=environment_loader, **jinja2_env_kwargs)
+    environment.globals = db_accessor if db_accessor else {}
+
+    environment.globals.update(globals_mapping)
+    environment.filters.update(filters_dict)
+    environment.tests.update(tests_dict)
+
+    return environment

pdf_render/user_input/__init__.py

@@ -0,0 +1,3 @@
+from .undefined_variable_form import prompt_for_undefined_variables
+
+__all__ = ["prompt_for_undefined_variables"]

pdf_render/user_input/undefined_variable_form.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+import click
+from textual import on
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, ScrollableContainer
+from textual.validation import Function
+from textual.widgets import (
+    Button,
+    Checkbox,
+    Footer,
+    Header,
+    Input,
+    Label,
+    Select,
+    Static,
+)
+
+
+def _is_choice(t: Any) -> bool:
+    return isinstance(t, click.Choice)
+
+
+def _is_valid_float(v: str) -> bool:
+    try:
+        float(v)
+        return True
+    except ValueError:
+        return False
+
+
+def _coerce_to_type(value: Any, _type: Any) -> Any:
+    """Convert a raw widget value to the expected Python type."""
+    if _type is bool or _type is bool:
+        return bool(value)
+    if _type is int:
+        return int(value)
+    if _type is float:
+        return float(value)
+    if _is_choice(_type):
+        return str(value)
+    return str(value)
+
+
+def new_template_form(css: str = None, bindings: Iterable[Binding] = None):
+    class TemplateForm(App[dict[str, Any]]):
+        CSS = (
+            """
+        Screen {
+            background: $surface;
+        }
+    
+        #form-container {
+            padding: 1 2;
+            height: 1fr;
+        }
+    
+        .field-block {
+            height: 3;
+            align: left middle;
+        }
+    
+        .field-label {
+            width: 24;
+            color: $text-muted;
+            text-style: bold;
+            content-align: left middle;
+            height: 3;
+        }
+    
+        .type-hint {
+            width: 16;
+            color: $text-disabled;
+            text-style: italic;
+            content-align: left middle;
+            height: 3;
+        }
+    
+        .field-block Input {
+            width: 1fr;
+        }
+    
+        .field-block Select {
+            width: 1fr;
+        }
+    
+        .field-block Checkbox {
+            width: auto;
+            color: white;
+        }
+    
+        #button-bar {
+            align: right middle;
+            height: 3;
+            padding: 0 2;
+        }
+    
+        #btn-submit {
+            margin-left: 1;
+        }
+    
+        .error-msg {
+            color: $error;
+            text-style: bold;
+            height: auto;
+            padding: 0 0 1 0;
+        }
+    
+        ToggleButton {
+            & > .toggle--button {
+                color: #bfbfbf;
+                background: transparent;
+                text-style: dim;
+            }
+            &.-on > .toggle--button {
+                text-style: bold not dim;
+            }
+        }
+        """
+            if not isinstance(css, str)
+            else css
+        )
+
+        BINDINGS = (
+            [
+                Binding("ctrl+enter", "submit", "Submit", priority=True),
+                Binding("ctrl+s", "submit", "Submit"),
+                Binding("escape", "quit_app", "Quit"),
+            ]
+            if not isinstance(bindings, Iterable) or not all(isinstance(binding, Binding) for binding in bindings)
+            else bindings
+        )
+
+        def __init__(
+            self,
+            variables: dict[str, Any],
+            defaults: dict[str, Any] | None = None,
+            title: str = "",
+        ):
+            super().__init__()
+            self.variables = variables
+            self.defaults = defaults or {}
+            self.title = title
+            self._error_label: Static | None = None
+
+        def compose(self) -> ComposeResult:
+            yield Header(name=self.title, show_clock=False)
+            yield Footer()
+
+            with ScrollableContainer(id="form-container"):
+                for name, _type in self.variables.items():
+                    if _is_choice(_type):
+                        type_hint = "choice"
+                    elif _type is bool:
+                        type_hint = "bool"
+                    elif _type is int:
+                        type_hint = "int"
+                    elif _type is float:
+                        type_hint = "float"
+                    else:
+                        type_hint = "str"
+
+                    with Horizontal(classes="field-block"):
+                        yield Label(name, classes="field-label")
+                        yield Label(type_hint, classes="type-hint")
+
+                        default = self.defaults.get(name)
+
+                        if _is_choice(_type):
+                            options = [(c, c) for c in _type.choices]
+                            valid_default = (
+                                str(default) if default is not None and str(default) in _type.choices else None
+                            )
+                            select_kwargs = {"allow_blank": True, "prompt": "Select…"}
+                            if valid_default is not None:
+                                select_kwargs["value"] = valid_default
+
+                            yield Select(options, id=f"field_{name}", **select_kwargs)
+
+                        elif _type is bool:
+                            yield Checkbox(
+                                "",
+                                id=f"field_{name}",
+                                value=bool(default) if default is not None else False,
+                            )
+
+                        elif _type is int:
+                            yield Input(
+                                value=str(default) if default is not None else "",
+                                placeholder="integer…",
+                                id=f"field_{name}",
+                                validators=[
+                                    Function(
+                                        lambda v: v.lstrip("-").isdigit(),
+                                        "Must be a whole number",
+                                    )
+                                ],
+                            )
+
+                        elif _type is float:
+                            yield Input(
+                                value=str(default) if default is not None else "",
+                                placeholder="number…",
+                                id=f"field_{name}",
+                                validators=[
+                                    Function(
+                                        lambda v: _is_valid_float(v),
+                                        "Must be a valid number",
+                                    )
+                                ],
+                            )
+
+                        else:
+                            yield Input(
+                                value=str(default) if default is not None else "",
+                                placeholder="text…",
+                                id=f"field_{name}",
+                            )
+
+                yield Static("", id="error-msg", classes="error-msg")
+
+            with Horizontal(id="button-bar"):
+                yield Button("Cancel", variant="default", id="btn-cancel")
+                yield Button("Submit", variant="primary", id="btn-submit")
+
+        def action_submit(self) -> None:
+            self._do_submit()
+
+        def action_quit_app(self) -> None:
+            self.exit(None)
+
+        @on(Button.Pressed, "#btn-submit")
+        def handle_submit(self) -> None:
+            self._do_submit()
+
+        @on(Button.Pressed, "#btn-cancel")
+        def handle_cancel(self) -> None:
+            self.exit(None)
+
+        def _do_submit(self) -> None:
+            results: dict[str, Any] = {}
+            errors: list[str] = []
+
+            for name, t in self.variables.items():
+                widget_id = f"field_{name}"
+
+                if _is_choice(t):
+                    widget: Select = self.query_one(f"#{widget_id}", Select)
+                    if not isinstance(widget.value, str):
+                        errors.append(f"'{name}' requires a selection.")
+                        continue
+                    results[name] = str(widget.value)
+
+                elif t is bool:
+                    widget: Checkbox = self.query_one(f"#{widget_id}", Checkbox)
+                    results[name] = widget.value
+
+                else:
+                    widget: Input = self.query_one(f"#{widget_id}", Input)
+                    raw = widget.value.strip()
+
+                    if not raw:
+                        errors.append(f"'{name}' cannot be empty.")
+                        continue
+
+                    validation_result = widget.validate(raw)
+                    if validation_result is not None and validation_result.failures:
+                        errors.append(f"'{name}' has an invalid value.")
+                        continue
+
+                    try:
+                        results[name] = _coerce_to_type(raw, t)
+                    except (ValueError, TypeError):
+                        errors.append(f"'{name}' could not be converted to {t.__name__}.")
+
+            error_widget = self.query_one("#error-msg", Static)
+            if errors:
+                error_widget.update("\n".join(errors))
+            else:
+                error_widget.update("")
+                self.exit(results)
+
+    return TemplateForm
+
+
+def prompt_for_undefined_variables(
+    variables: dict[str, Any],
+    defaults: dict[str, Any] | None = None,
+    title: str = "",
+    css: str = None,
+    bindings: Iterable[Binding] = None,
+) -> dict[str, Any] | None:
+    """
+    Launch the Textual form and return the filled values dict.
+
+    Args:
+        variables: Mapping of variable_name -> type.  Duplicate keys are collapsed automatically
+                   (last definition wins, preserving insertion order of first occurrence).
+        defaults:  Optional mapping of variable_name -> default value.
+                   Pre-fills the corresponding widget; user can override.
+        title:     Shown at the top of the TUI window to provide users with additional context
+        css:       A str containing CSS you wish to override the defaults with.
+                   None for default CSS
+        bindings:  An iterable of textual.Binding objects you wish to override the defaults with.
+                   None for default bindings.
+
+    Returns:
+        A dict of {variable_name: coerced_value}, or None if the user cancelled.
+    """
+
+    seen_variables: dict[str, Any] = {}
+    for name, t in variables.items():
+        if name not in seen_variables:
+            seen_variables[name] = t
+
+    template_form = new_template_form(css, bindings)
+    app = template_form(seen_variables, defaults=defaults, title=title)
+    return app.run()

pdfrender-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: pdfrender
+Version: 0.1.0
+Summary: Using DB models and Jinja2 to generate templated PDF documents
+Author-email: Cam Ratchford <camratchford@gmail.com>
+Project-URL: Homepage, https://github.com/camratchford/pdfrender
+Project-URL: Source, https://github.com/camratchford/pdfrender
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: byoconfig
+Requires-Dist: typer
+Requires-Dist: jinja2
+Requires-Dist: click
+Requires-Dist: textual
+Requires-Dist: pyyaml
+Requires-Dist: sqlmodel
+Requires-Dist: pydantic
+Requires-Dist: markdown
+Requires-Dist: pymdown-extensions
+Requires-Dist: pygments
+Requires-Dist: weasyprint
+Provides-Extra: development
+Requires-Dist: pytest; extra == "development"
+Requires-Dist: pytest-cov; extra == "development"
+Requires-Dist: isort; extra == "development"
+Requires-Dist: ruff; extra == "development"
+Requires-Dist: build; extra == "development"
+Provides-Extra: docs
+Requires-Dist: mkdocs~=1.6; extra == "docs"
+Requires-Dist: mkdocs-autorefs~=1.4; extra == "docs"
+Requires-Dist: mkdocs-get-deps~=0.2.2; extra == "docs"
+Requires-Dist: mkdocs-material~=9.7; extra == "docs"
+Requires-Dist: mkdocs-material-extensions~=1.3; extra == "docs"
+Requires-Dist: mkdocstrings~=1.0; extra == "docs"
+Requires-Dist: mkdocstrings-python~=2.0; extra == "docs"
+Dynamic: license-file
+
+# pdfrender
+
+A database relationship and template-driven Markdown to PDF toolkit.
+
+Bring your own SQLAlchemy/SQLModel models, YAML data, and Jinja2 templates.
+
+
+- Type-aware model importing DB data from YAML. Supports nested instance data for dynamically assigning relationships.
+- Facilities to perform DB queries inside the Jinja2 template context
+- Custom Jinja2 Environment object:
+   - Pre-processes templates to support typed variables, allowing template authors to specify variable types 
+     using PEP 484 annotation syntax.
+   - Stores undefined variables, allowing for run-time user variable prompts
+- Dynamically composed Textual CLI form, to capture run-time user variable inputs 
+
+## Documentation
+
+Published at https://camratchford.github.io/pdfrender/ (deployed on release,
+see below). To view locally instead:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve -f extras/docs/mkdocs.yml
+```
+
+Then open http://127.0.0.1:8000.
+
+## Releasing
+
+The package version comes from git tags via `setuptools-scm` - there's
+nothing to bump by hand in `pyproject.toml`. To cut a release:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+Pushing a `v*` tag triggers `.github/workflows/release.yml`, which builds
+the package and publishes it to PyPI (via
+[trusted publishing](https://docs.pypi.org/trusted-publishers/), no stored
+token needed), and deploys `extras/docs` to GitHub Pages.
+
+One-time setup this repo needs before that works:
+
+- **PyPI**: add a trusted publisher on the
+  [pdfrender PyPI project](https://pypi.org/manage/project/pdfrender/publishing/)
+  pointing at this repo and the `release.yml` workflow.
+- **GitHub Pages**: under Settings -> Pages, set Source to "GitHub Actions".

pdfrender-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+pdf_render/__init__.py,sha256=qXaVJNBTdL8brrbRbKsynI0pAsaywZGsWD1kfdNZBvg,689
+pdf_render/import_functions.py,sha256=9dRIRWSMRRfB0pYfGcgWVyQ-ZFkTRlYhndFBgBsemQM,1452
+pdf_render/data/__init__.py,sha256=3-p3zPKYQMYSCj2DggunufeiGdjGrmVs6j2kKhV8_dQ,165
+pdf_render/data/accessor.py,sha256=Aswq679wqeVoRT9FdUaj9hXWeQoZnRzm1BCHFyBHdp8,6108
+pdf_render/data/importer.py,sha256=Txn-r1ShUWZa8ovpU9WMKE7kQtObCSdrjJFwjUsiIz4,8451
+pdf_render/data/model_field_typing.py,sha256=lRl49Q5A45NjN8gd45qAqH80skGBrxfunNcr-N6FpG4,5787
+pdf_render/md/__init__.py,sha256=sBfyzkX6jHIk7OmN97wnlcRjOt_AhkfYK9559qYhBwU,88
+pdf_render/md/rendering.py,sha256=xpiidPQxYYXW9nFyHDNSDlOPbqIxmb4-E4BACb23VtI,1169
+pdf_render/md/extensions/__init__.py,sha256=L561kJSQkx19-ycC51o8OA30cVIppxmyTgnubJeidUA,370
+pdf_render/md/extensions/columns.py,sha256=gZr95YG57Yj-ZPxRjoMOsFX02V6nz0TR_D2nZ82I-XU,1460
+pdf_render/md/extensions/flex_wrap.py,sha256=ooRDDS0adXOwLeIR6g9LyEglSt8FK7TI0l1Iir1wNGc,1664
+pdf_render/md/extensions/muted_text.py,sha256=G-8wmrf_qmfzzEOgHtYtNsnWjtQjl31MXpi6a84IVmw,1226
+pdf_render/md/extensions/nerdfont_glyph.py,sha256=5fCZohlfE5QzTZ_Yavj7Wr2_09OvJCe0OriYpw8UPXU,1005
+pdf_render/md/extensions/page_break.py,sha256=XOCKw4Ua5N4LYWOb9m5hQocywRpyawXgXxIo7di-OdU,1060
+pdf_render/pdf/__init__.py,sha256=2MOgdQSpp4Oq-FE1hXvb177P4lDPURiv_PpAPrTQ7vA,155
+pdf_render/pdf/document_template.py,sha256=oO0E6vsG9PSj9lduOfZJggzsNEv524c1mDu1GkVsBGw,1238
+pdf_render/pdf/metadata.py,sha256=3w9ZHbiufI9YHs2FigUhD7hIR8CjO4uBkblRR1XPg14,1392
+pdf_render/pdf/options.py,sha256=FSHtHFwn1lJ8_XjYJbrjugRugsBikEUtlMjkSaJi3Jg,2863
+pdf_render/pdf/rendering.py,sha256=bbVEB6wKS78iLBpNwUQT0JqHyaytYlKyUVHuQtQ4lpo,1568
+pdf_render/templates/__init__.py,sha256=wYLxecUtH-SjlgJ-ITpfZRd_e_DcbtWI9Iqm51EfaMU,166
+pdf_render/templates/environment.py,sha256=53k8PcHr1ISOCmdnbA7Jp7NUqabvm5C7A9dRfRmQM7Q,6301
+pdf_render/templates/rendering.py,sha256=C_kpovQhn2lWHJXvU2JCU5TesWnZFLSHu05Egq-qmb0,3439
+pdf_render/templates/filters/__init__.py,sha256=kxd5SpaEuAaTwSXErz17t9EesECXVNY2tpIj-aW2f3M,349
+pdf_render/templates/filters/format_filters.py,sha256=zE-3REsj0wHYe_eqOmFbuIyYXv1QpAb-tFrd2suyh9A,929
+pdf_render/templates/filters/getter_filters.py,sha256=S8Jf4bvNHzryW8xgReKlEFD6Ql5tVgRmKPXLHYM6dds,1653
+pdf_render/templates/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdf_render/user_input/__init__.py,sha256=7vxxbVasiYXWD8H8nzRmB3Lv7KiFqTnK5e4TqhWs2rA,114
+pdf_render/user_input/undefined_variable_form.py,sha256=wqHdQbJWJN0EZ3JZbjHyrN9WheUnaS7rolNdT_zEJ3I,10541
+pdfrender-0.1.0.dist-info/licenses/LICENSE,sha256=Rmn7wkN_w7iiZgvv4Q8Hy2jmiUq9E9iWYRp-iX75BBE,1073
+pdfrender-0.1.0.dist-info/METADATA,sha256=fM5BwPzlntXowQ3SRUsgpIp3mof2hqGgy89SWlBD4rA,3539
+pdfrender-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pdfrender-0.1.0.dist-info/entry_points.txt,sha256=nd_8klbU5TenNX6vtAWdB_wfLuuuyyCC6hP3vs-gGf4,54
+pdfrender-0.1.0.dist-info/top_level.txt,sha256=isBDCoFGvkIAy7ZWrHYEFRTESFikfE0s24vK0vsVvEE,11
+pdfrender-0.1.0.dist-info/RECORD,,

pdfrender-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdfrender-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfrender = pdf_render.__main__:cli

pdfrender-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Ratchford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdfrender-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdf_render