pdfrender 0.1.0__py3-none-any.whl

pdf_render/__init__.py

@@ -0,0 +1,25 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .data import DataImporter, DBAccessor
+from .md import create_markdown_renderer
+from .pdf import PDFMetadata, PDFOptions, render_pdf
+from .templates import TypedVariableEnvironment, new_template_environment
+from .user_input import prompt_for_undefined_variables
+
+try:
+    __version__ = version("pdfrender")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "__version__",
+    "DataImporter",
+    "DBAccessor",
+    "create_markdown_renderer",
+    "PDFOptions",
+    "PDFMetadata",
+    "render_pdf",
+    "new_template_environment",
+    "TypedVariableEnvironment",
+    "prompt_for_undefined_variables",
+]

pdf_render/data/__init__.py

@@ -0,0 +1,5 @@
+from .accessor import DBAccessor
+from .importer import DataImporter
+from .model_field_typing import ModelType
+
+__all__ = ["DBAccessor", "DataImporter", "ModelType"]

pdf_render/data/accessor.py

@@ -0,0 +1,161 @@
+from typing import Any, Mapping, Type
+
+from sqlalchemy import Engine, select
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.orm import DeclarativeBase, Session
+
+from pdf_render.data.model_field_typing import get_model_base_model_list, get_primary_key_reference
+
+
+class DBAccessor(Mapping):
+    """Read-only, dict-like access to a collection of SQLAlchemy models.
+
+    Can be used in place of a plain `dict` as `jinja2.Environment`'s
+    `globals` attribute. If an accessed key is not a table name known to
+    `base_model`, it falls back to a normal dictionary backed by `self._data`
+    (seeded from `data_key_values`). Accessing a table name always returns
+    every row for that table as a list of model instances.
+
+    Args:
+        base_model: The parent model every table's model is a subclass of -
+            for sqlmodel, `SQLModel`; for sqlalchemy, a subclass of
+            `DeclarativeBase`. When using `SQLModel`, every model is read
+            from SQLModel's single global registry, since `SQLModel.registry`
+            isn't otherwise accessible - passing a custom `registry` to a
+            `SQLModel` subclass isn't supported here.
+        engine: The return value of `sqlalchemy.create_engine()`
+            (`sqlmodel.create_engine()` returns the same type).
+        sqlalchemy_session: An already-opened `sqlalchemy.orm.Session`. When
+            omitted, a new session is opened on `__enter__` and closed on
+            `__exit__`.
+        **data_key_values: Initial non-table key/value pairs, accessible the
+            same way as table names.
+
+    Raises:
+        TypeError: If `engine` is not a `sqlalchemy.Engine`.
+    """
+
+    _engine: Engine = None
+    _session: Session = None
+    _data: dict[str, DeclarativeBase | None | Any]
+    _models: dict[str, Type[DeclarativeBase]]
+
+    def __init__(
+        self,
+        base_model: Type[DeclarativeBase],
+        engine: Engine,
+        sqlalchemy_session: Session = None,
+        **data_key_values,
+    ):
+        if sqlalchemy_session is not None:
+            self._session = sqlalchemy_session
+
+        self._engine = engine
+        models = get_model_base_model_list(base_model)
+
+        if not isinstance(engine, Engine):
+            raise TypeError(f"Parameter <engine>'s type should be a subclass of sqlalchemy.Engine - got {engine}")
+
+        self._models = {model.__name__: model for model in models}
+        placeholder_keys = {model: None for model in self._models}
+        self._data = {
+            **placeholder_keys,
+            **data_key_values,
+            "get_by_pk": self.get_by_pk,
+            "filter_where": self.filter_where,
+            "filter_where_eval": self.filter_where_eval,
+        }
+
+    def _get_from_db(self, model: Type[DeclarativeBase]):
+        return self._session.scalars(select(model)).all()
+
+    def get_by_pk(self, model_name: str, **key_value_kw_params):
+        if model_name not in self._models:
+            raise KeyError(f"No table with name {model_name}")
+        model = self._models[model_name]
+        primary_key_reference = get_primary_key_reference(model, key_value_kw_params)
+        return self._session.get(model, primary_key_reference)
+
+    def filter_where(self, model_name: str, **filter_kw_params):
+        if model_name not in self._models:
+            raise KeyError(f"No table with name {model_name}")
+        model = self._models[model_name]
+
+        select_statement = select(model).where(
+            *list(getattr(model, attr) == value for attr, value in filter_kw_params.items())
+        )
+        return self._session.scalars(select_statement).all()
+
+    def filter_where_eval(self, model_name: str, eval_statement: str):
+        model = self._models.get(model_name)
+        if len(model_name.split(".")) > 1:
+            try:
+                model = eval(model_name, None, self._models)
+            except (SyntaxError, NameError, AttributeError, TypeError) as e:
+                raise ValueError(f"Could not evaluate model_name {model_name!r}: {e}") from e
+        if not model:
+            raise KeyError(f"No table with name {model_name}")
+
+        try:
+            clauses = [eval(statement, None, self._models) for statement in eval_statement.split(",")]
+        except (SyntaxError, NameError, AttributeError, TypeError) as e:
+            raise ValueError(f"Could not evaluate eval_statement {eval_statement!r}: {e}") from e
+
+        try:
+            select_statement = select(model).where(*clauses)
+            return self._session.scalars(select_statement).all()
+        except SQLAlchemyError as e:
+            raise ValueError(f"Could not build/execute query for eval_statement {eval_statement!r}: {e}") from e
+
+    def __getitem__(self, key):
+        """
+        :param key: The table name of the model or the key from init's data_key_values parameter
+        :return: Either the corresponding table name instances or the data from init's data_key_values parameter
+        """
+        model = self._models.get(key)
+
+        if model is None:
+            try:
+                return self._data.get(key)
+            except KeyError as e:
+                raise KeyError(f"{self} has no field {key}") from e
+
+        return self._get_from_db(model)
+
+    def __setitem__(self, key, item):
+        if key not in self._models:
+            self._data[key] = item
+
+    def __delitem__(self, key):
+        if key not in self._models:
+            del self._data[key]
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __contains__(self, key):
+        return key in self._data
+
+    def __enter__(self):
+        if self._session is None:
+            self._session = Session(self._engine)
+        return self
+
+    def __exit__(self, *_):
+        self._session.close()
+        return False
+
+    def __len__(self):
+        return len(self._data)
+
+    def get(self, key, default=None):
+        if key in self:
+            return self[key]
+
+        return default
+
+    def update(self, _dict=None, /, **kwargs):
+        if _dict is not None:
+            self._data.update(_dict)
+        if kwargs:
+            self._data.update(kwargs)

pdf_render/data/importer.py

@@ -0,0 +1,209 @@
+from datetime import date, datetime
+from inspect import isclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from sqlalchemy import Engine
+from sqlalchemy.exc import InvalidRequestError
+from sqlalchemy.orm import DeclarativeBase, Session
+from sqlmodel import SQLModel
+from yaml import safe_load
+
+from pdf_render.data.model_field_typing import (
+    SCALAR_TYPES,
+    ModelType,
+    ScalarType,
+    get_date_from_date_str,
+    get_datetime_from_datetime_str,
+    get_first_type_from_union,
+    get_model_base_model_list,
+    get_model_type_annotations,
+    get_primary_key_reference,
+    is_list_type,
+    is_scalar_type,
+    is_union_type,
+)
+
+
+class DataImporter:
+    """Imports YAML data into a SQLAlchemy/SQLModel-backed database.
+
+    Reads a YAML sequence of records for a given model, coerces each field to
+    the model's declared type (including nested relationships and lists of
+    related models), and upserts the resulting rows by primary key so that
+    re-importing the same data updates existing rows instead of duplicating
+    them.
+
+    Args:
+        base_model: The parent model every importable model is a subclass
+            of - for sqlmodel, `SQLModel`; for sqlalchemy, a subclass of
+            `DeclarativeBase`. When using `SQLModel`, every model is read
+            from SQLModel's single global registry, since `SQLModel.registry`
+            isn't otherwise accessible - passing a custom `registry` to a
+            `SQLModel` subclass isn't supported here.
+        engine: The return value of `sqlalchemy.create_engine()`
+            (`sqlmodel.create_engine()` returns the same type).
+        sqlalchemy_session: An already-opened `sqlalchemy.orm.Session`. When
+            omitted, a new session is opened on `__enter__` and closed on
+            `__exit__`.
+
+    Raises:
+        TypeError: If `engine` is not a `sqlalchemy.Engine`.
+    """
+
+    _engine: Engine = None
+    _session: Session = None
+    _base_model: ModelType
+    _model_fields: dict[str, Any]
+    _all_models: dict[str, ModelType]
+    _current_file: Path
+
+    def __init__(
+        self,
+        base_model: ModelType,
+        engine: Engine,
+        sqlalchemy_session: Session = None,
+    ):
+        """
+        :param base_model:
+            The parent model that each created model is a subclass of,
+            for sqlmodel: SQLModel, for sqlalchemy: a subclass of DeclarativeBase
+        :param engine:
+            The return value of sqlalchemy.create_engine() (sqlmodel uses the same function)
+        :param (optional) sqlalchemy_session:
+            [Optional] An instantiated and opened sqlalchemy.Session object, typically via the context manager protocol
+             - `with Session(engine) as session:`
+        """
+
+        if sqlalchemy_session is not None:
+            self._session = sqlalchemy_session
+
+        self._engine = engine
+
+        if not isinstance(engine, Engine):
+            raise TypeError(f"Parameter <engine>'s type should be a subclass of sqlalchemy.Engine - got {engine}")
+
+        self._base_model = base_model
+        self._all_models = {m.__name__: m for m in get_model_base_model_list(base_model)}
+        self._model_fields = {m.__name__: get_model_type_annotations(m) for m in self._all_models.values()}
+
+    def load_data_from_file(self, yaml_text: str, model: ModelType):
+        data = safe_load(yaml_text)
+        if isinstance(data, Mapping):
+            raise TypeError("Top-level YAML object should be a Sequence - got Mapping")
+        for instance in data:
+            self._session.add_all([self._upsert(model, self._coerce_instance_data_types(model, instance))])
+            self._session.commit()
+
+    def _coerce_sequence(self, model: ModelType, field_key: str, field_value: Any, coerced_data: dict):
+        if not isinstance(field_value, Sequence):
+            raise TypeError(
+                f"Invalid type for {model.__name__}.{field_key}, expected Sequence - got '{type(field_value)}'"
+            )
+        if not field_value:
+            coerced_data[field_key] = []
+            return coerced_data
+
+        try:
+            type_annotation = self._model_fields[model.__name__].get(field_key).__args__[0]
+            if not isinstance(type_annotation, str) and hasattr(type_annotation, "__forward_arg__"):
+                type_annotation = type_annotation.__forward_arg__
+            model_name = type_annotation
+
+        except AttributeError as e:
+            raise AttributeError(
+                f"Error processing type for {model.__name__}.{field_key} with annotations "
+                f"'{self._model_fields[model.__name__].get(field_key).__args__[0]}' "
+                f"(Type {type(self._model_fields[model.__name__].get(field_key).__args__[0])})"
+                f": {e}"
+            ) from e
+
+        if isclass(model_name) and issubclass(model_name, DeclarativeBase):
+            model_name = model_name.__tablename__
+
+        model_type = self._all_models.get(model_name)
+        if not model_type:
+            model_type = model_name
+
+        coerced_data[field_key] = []
+
+        for sequence_index, instance in enumerate(field_value):
+            coerced_data[field_key].append(self._upsert(model_type, instance))
+
+        return coerced_data
+
+    def _coerce_model(
+        self, model: ModelType, field_key: str, field_value: Any, field_type: ModelType, coerced_data: dict
+    ):
+        if not isinstance(field_value, Mapping):
+            raise TypeError(
+                f"Invalid type for {model.__name__}.{field_key}, expected Mapping - got '{type(field_value)}'"
+            )
+        coerced_data[field_key] = self._upsert(field_type, field_value)
+
+    @staticmethod
+    def _coerce_scalar(model: ModelType, field_key: str, field_value: Any, field_type: ScalarType, coerced_data: dict):
+        if not is_scalar_type(field_value) and field_value is not None:
+            scalar_types_str = "[" + ", ".join(str(_type) for _type in SCALAR_TYPES) + "]"
+            raise TypeError(
+                f"Invalid type for {model.__name__}.{field_key}, "
+                f"expecting '{field_type}' '{scalar_types_str}' - got '{type(field_value)}'"
+            )
+        try:
+            coerced_data[field_key] = field_type(field_value)
+        except TypeError as e:
+            raise TypeError(f"{e.args}\n\n\n{field_type} is not callable") from e
+
+    def _coerce_instance_data_types(self, model: ModelType, instance_data: dict[str, Any]):
+        coerced_data = {}
+        for field_key in instance_data:
+            field_type = self._model_fields[model.__name__].get(field_key, None)
+
+            if is_union_type(field_type):
+                field_type = get_first_type_from_union(field_type)
+
+            field_value = instance_data[field_key]
+            if field_type is None:
+                raise KeyError(f"Invalid field for model '{model.__name__}': Has no field '{field_key}'")
+
+            if is_list_type(field_type):
+                coerced_data = self._coerce_sequence(model, field_key, field_value, coerced_data)
+
+            elif isclass(field_type) and issubclass(field_type, (DeclarativeBase, SQLModel)):
+                self._coerce_model(model, field_key, field_value, field_type, coerced_data)
+
+            elif field_type is date:
+                coerced_data[field_key] = get_date_from_date_str(field_value)
+
+            elif field_type is datetime:
+                coerced_data[field_key] = get_datetime_from_datetime_str(field_value)
+
+            else:
+                self._coerce_scalar(model, field_key, field_value, field_type, coerced_data)
+
+        return coerced_data
+
+    def _upsert(self, model: ModelType, reference_value: Any):
+        primary_key_reference = get_primary_key_reference(model, reference_value)
+        init_data = reference_value if isinstance(reference_value, (Mapping, dict)) else primary_key_reference
+        try:
+            instance = self._session.get(model, primary_key_reference)
+        except InvalidRequestError as e:
+            raise InvalidRequestError(f"{e}: got {primary_key_reference}")
+
+        if not instance:
+            return model(**init_data)
+
+        for key, value in init_data.items():
+            setattr(instance, key, value)
+
+        return instance
+
+    def __enter__(self):
+        if self._session is None:
+            self._session = Session(self._engine)
+        return self
+
+    def __exit__(self, *_):
+        self._session.close()
+        return False

pdf_render/data/model_field_typing.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import importlib
+import typing
+from datetime import date, datetime
+from inspect import isclass
+from pprint import pformat
+from types import UnionType
+
+# Only importing the whole modules so ModelType's docstring shows which package the classes come from
+import sqlalchemy.orm
+import sqlmodel
+from sqlmodel.main import default_registry
+
+SCALAR_TYPES = {str, int, bytes, float, bool}
+ScalarType: typing.TypeAlias = typing.Type[str | int | bytes | float | bool]
+
+VALID_DATETIME_FORMATS: tuple[str, ...] = (
+    # Ordered deliberately: a plain tuple (not a set) so match priority for an
+    # ambiguous input (e.g. a trailing "Z") is deterministic across runs.
+    "%Y-%m-%dT%H:%M:%S.%fZ",
+    "%Y-%m-%dT%H:%M:%SZ",
+    "%Y-%m-%dT%H:%M:%S.%f",
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%dT%H:%M:%S.%f%z",
+    "%Y-%m-%dT%H:%M:%S%z",
+    "%Y-%m-%d",
+    "%H:%M:%S.%f",
+    "%H:%M:%S",
+)
+
+ModelType: typing.TypeAlias = typing.Type[sqlmodel.SQLModel | sqlalchemy.orm.DeclarativeBase]
+"""A model class - either an SQLModel or SQLAlchemy DeclarativeBase subclass."""
+
+
+def get_model_base_model_list(base_model: ModelType):
+    if issubclass(base_model, sqlmodel.SQLModel):
+        # SQLModel.registry is inaccessible because of some metaclassing sorcery, so this
+        # always reads from SQLModel's single global registry instead. Documented as a
+        # restriction on DataImporter/DBAccessor's base_model - see their docstrings.
+        models = [i.class_ for i in default_registry.mappers]
+    elif isclass(base_model) and issubclass(base_model, (sqlalchemy.orm.DeclarativeBase, sqlmodel.SQLModel)):
+        models = [i.class_ for i in base_model.registry.mappers]
+    else:
+        raise TypeError(
+            f"Parameter <base_model>'s type should be a subclass of sqlalchemy.DeclarativeBase - got {base_model}"
+        )
+
+    return models
+
+
+def derive_type_from_mapped_column(mapped: sqlalchemy.orm.Mapped, module_name: str):
+    first_arg = mapped.__args__[0]
+
+    if not isinstance(first_arg, typing.ForwardRef):
+        return first_arg
+
+    module = importlib.import_module(module_name)
+    return getattr(module, first_arg.__forward_arg__, None)
+
+
+def derive_type_from_annotated_type(annotated_type: typing.Any, module_name: str):
+    if not isinstance(annotated_type, typing._GenericAlias):
+        return annotated_type
+
+    return derive_type_from_mapped_column(annotated_type, module_name)
+
+
+def get_model_type_annotations(model: ModelType):
+    if issubclass(model, sqlmodel.SQLModel):
+        annotations = {
+            name: derive_type_from_annotated_type(annotation, model.__module__)
+            for name, annotation in model.__annotations__.items()
+        }
+
+    elif issubclass(model, sqlalchemy.orm.DeclarativeBase):
+        annotations = {
+            name: derive_type_from_mapped_column(annotation, model.__module__)
+            for name, annotation in model.__annotations__.items()
+        }
+    else:
+        raise TypeError(f"Parameter <model>'s type should be a subclass of sqlalchemy.DeclarativeBase - got {model}")
+    return annotations
+
+
+def is_scalar_type(value: typing.Any):
+    return any(isinstance(value, _type) for _type in SCALAR_TYPES)
+
+
+def is_union_type(_type: typing.Any) -> bool:
+    origin = typing.get_origin(_type)
+    return origin is typing.Union or origin is UnionType
+
+
+def is_list_type(_type: typing.Any) -> bool:
+    origin = typing.get_origin(_type)
+    return origin is list
+
+
+def is_forward_ref(_type: typing.Any) -> bool:
+    origin = typing.get_origin(_type)
+    return origin is typing.ForwardRef
+
+
+def get_first_type_from_union(_type: typing.Union | UnionType):
+    for arg in _type.__args__:
+        if arg is not None:
+            return arg
+    return None
+
+
+def get_primary_key_reference(model: ModelType, reference_value: typing.Any):
+    primary_key_field = model.__table__.primary_key
+
+    field_types = get_model_type_annotations(model)
+    primary_keys = [key.name for key in primary_key_field]
+    primary_key_types = {primary_key: field_types[primary_key] for primary_key in primary_keys}
+
+    primary_key_types_str = "[" + ", ".join(f"{k}: {v}" for k, v in primary_key_types.items()) + "]"
+    key_type = "single" if len(primary_key_types) == 1 else " composite"
+    if not isinstance(reference_value, (typing.Mapping, dict)):
+        raise TypeError(
+            f"Invalid primary key reference for {model}."
+            f"{model.__name__} has a {key_type} primary key: {primary_key_types_str} "
+            f" - got {pformat(reference_value)}"
+        )
+
+    if not all(key in reference_value for key in primary_key_types):
+        missing_keys = [key for key in primary_key_types if key not in reference_value]
+        raise KeyError(
+            f"Invalid model reference for {model}."
+            f"{model.__name__} has a {key_type} primary key: {primary_key_types_str} "
+            f"Missing key(s)='{', '.join(missing_keys)}'"
+            f" - got {pformat(reference_value)}"
+        )
+
+    return {k: reference_value[k] for k in primary_key_types}
+
+
+def get_date_from_date_str(maybe_date_str: str):
+    if not isinstance(maybe_date_str, str):
+        return maybe_date_str
+    try:
+        return datetime.strptime(maybe_date_str, "%Y-%m-%d").date()
+    except ValueError:
+        raise ValueError(f"Could not parse '{maybe_date_str}' as a date")
+
+
+def get_datetime_from_datetime_str(maybe_datetime_str: str):
+    if isinstance(maybe_datetime_str, date) or isinstance(maybe_datetime_str, datetime):
+        return maybe_datetime_str
+
+    for fmt in VALID_DATETIME_FORMATS:
+        try:
+            return datetime.strptime(maybe_datetime_str, fmt)
+        except ValueError:
+            continue
+
+    raise ValueError(f"Could not parse '{maybe_datetime_str}' as a datetime")

pdf_render/import_functions.py

@@ -0,0 +1,43 @@
+import importlib
+import pkgutil
+from inspect import isfunction
+from typing import Iterable
+
+
+def import_submodules(module_name: str, recursive: bool = True, has_attr_filter: str = None):
+    if isinstance(module_name, str):
+        module_name = importlib.import_module(module_name)
+
+    results = {}
+    for loader, name, is_pkg in pkgutil.walk_packages(module_name.__path__, module_name.__name__ + "."):
+        try:
+            module = importlib.import_module(name)
+
+            if isinstance(has_attr_filter, str) and hasattr(module, has_attr_filter) or has_attr_filter is None:
+                results[name] = module
+
+            if recursive and is_pkg:
+                results.update(import_submodules(name, recursive, has_attr_filter))
+
+        except ImportError:
+            pass
+
+    return results
+
+
+def get_functions_by_prefix_from_modules(
+    module_names: Iterable[str], func_name_prefix: str, trim_func_name_prefix: bool = True
+):
+    func_name_prefix = func_name_prefix.rstrip("_") + "_"
+    modules = {
+        mod_name: mod for module_name in module_names for mod_name, mod in import_submodules(module_name).items()
+    }
+
+    functions_map = {
+        func_name[len(func_name_prefix) :] if trim_func_name_prefix else func_name: func
+        for module in modules.values()
+        for func_name, func in module.__dict__.items()
+        if isfunction(func) and func_name.startswith(func_name_prefix)
+    }
+
+    return functions_map

pdf_render/md/__init__.py

@@ -0,0 +1,3 @@
+from .rendering import create_markdown_renderer
+
+__all__ = ["create_markdown_renderer"]

pdf_render/md/extensions/__init__.py

@@ -0,0 +1,13 @@
+from .columns import FlexColumnsExtension
+from .flex_wrap import FlexWrapExtension
+from .muted_text import MutedTextExtension
+from .nerdfont_glyph import NerdfontGlyphExtension
+from .page_break import PageBreakExtension
+
+__all__ = [
+    "FlexColumnsExtension",
+    "FlexWrapExtension",
+    "MutedTextExtension",
+    "NerdfontGlyphExtension",
+    "PageBreakExtension",
+]

pdf_render/md/extensions/columns.py

@@ -0,0 +1,47 @@
+import xml.etree.ElementTree as ElementTree
+
+from markdown import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+# Pattern to match %% content %%
+FLEX_COLUMNS_RE = r"%%\s*(.*?)\s*%%"
+
+
+class FlexColumnsInlineProcessor(InlineProcessor):
+    def __init__(self, pattern, md=None):
+        super().__init__(pattern, md)
+
+    def handleMatch(self, match, data):
+        # Extract the content between %% and %%
+        content = match.group(1)
+
+        columns = [col.strip() for col in content.split("||")]
+
+        container = ElementTree.Element("div")
+        container.set("class", "row")
+        for col_text in columns:
+            column = ElementTree.SubElement(container, "div")
+            column.set("class", "column")
+            column.text = col_text
+
+        return container, match.start(0), match.end(0)
+
+
+class FlexColumnsExtension(Extension):
+    """Markdown extension for the `%% col1 || col2 || ... %%` inline syntax.
+
+    Renders the given `||`-separated items as a `<div class="row">`
+    containing one `<div class="column">` per item, for simple side-by-side
+    layouts.
+    """
+
+    def extendMarkdown(self, md):
+        processor = FlexColumnsInlineProcessor(FLEX_COLUMNS_RE, md)
+
+        # Add with priority to ensure it runs before other inline processors
+        md.inlinePatterns.register(processor, "columns", 175)
+
+
+# noinspection PyPep8Naming
+def makeExtension(**kwargs):
+    return FlexColumnsExtension(**kwargs)