templify-cli 0.1.0__py3-none-any.whl

templify/filter_rules.py

@@ -0,0 +1,366 @@
+"""Filter rules for the `--filter` option, each keeps the records matching a condition.
+
+The first argument of every rule is the column (`key`), and values coming from the filter
+JSON are converted to the rule type, so `{"name": "int__gt", "args": ["age", "30"]}` works.
+"""
+
+import re
+import uuid
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+from pyspecification import SubscriptableRulesRegistry
+
+rules = SubscriptableRulesRegistry[dict[str, Any], str, bool](
+    operator="logical",
+    check_key_existence=True,
+)
+"""The registry of every filter rule, keyed by rule name."""
+
+# -----------------------
+# bool
+# -----------------------
+
+
+@rules.rule()
+def is_true(d: dict[str, Any], key: str) -> bool:
+    """Keep records where `key` is `true`."""
+    return d[key] is True
+
+
+@rules.rule()
+def is_null(d: dict[str, Any], key: str) -> bool:
+    """Keep records where `key` is empty (`null`)."""
+    return d[key] is None
+
+
+# -----------------------
+# int
+# -----------------------
+
+
+@rules.rule(processors=int)
+def int__eq(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule(processors=int)
+def int__gt(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where `key` is greater than `value`."""
+    return d[key] > value
+
+
+@rules.rule(processors=int)
+def int__ge(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where `key` is greater than or equal to `value`."""
+    return d[key] >= value
+
+
+@rules.rule(processors=int)
+def int__lt(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where `key` is less than `value`."""
+    return d[key] < value
+
+
+@rules.rule(processors=int)
+def int__le(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where `key` is less than or equal to `value`."""
+    return d[key] <= value
+
+
+# -----------------------
+# float
+# -----------------------
+
+
+@rules.rule(processors=float)
+def float__eq(d: dict[str, Any], key: str, value: float) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule(processors=float)
+def float__gt(d: dict[str, Any], key: str, value: float) -> bool:
+    """Keep records where `key` is greater than `value`."""
+    return d[key] > value
+
+
+@rules.rule(processors=float)
+def float__ge(d: dict[str, Any], key: str, value: float) -> bool:
+    """Keep records where `key` is greater than or equal to `value`."""
+    return d[key] >= value
+
+
+@rules.rule(processors=float)
+def float__lt(d: dict[str, Any], key: str, value: float) -> bool:
+    """Keep records where `key` is less than `value`."""
+    return d[key] < value
+
+
+@rules.rule(processors=float)
+def float__le(d: dict[str, Any], key: str, value: float) -> bool:
+    """Keep records where `key` is less than or equal to `value`."""
+    return d[key] <= value
+
+
+# -----------------------
+# string
+# -----------------------
+
+
+@rules.rule()
+def string__eq(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule()
+def string__regex(d: dict[str, Any], key: str, pattern: str) -> bool:
+    """Keep records where `key` matches the regular expression `pattern`."""
+    return re.search(pattern, d[key]) is not None
+
+
+@rules.rule()
+def string__contains(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` contains `value`."""
+    return value in d[key]
+
+
+@rules.rule()
+def string__icontains(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` contains `value`, ignoring case."""
+    return value.lower() in d[key].lower()
+
+
+@rules.rule()
+def string__is_in(d: dict[str, Any], key: str, value: list[str]) -> bool:
+    """Keep records where `key` is one of the `value` list."""
+    return d[key] in value
+
+
+@rules.rule()
+def string__iis_in(d: dict[str, Any], key: str, value: list[str]) -> bool:
+    """Keep records where `key` is one of the `value` list, ignoring case."""
+    return d[key].lower() in [item.lower() for item in value]
+
+
+@rules.rule()
+def string__startswith(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` starts with `value`."""
+    return d[key].startswith(value)
+
+
+@rules.rule()
+def string__istartswith(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` starts with `value`, ignoring case."""
+    return d[key].lower().startswith(value.lower())
+
+
+@rules.rule()
+def string__endswith(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` ends with `value`."""
+    return d[key].endswith(value)
+
+
+@rules.rule()
+def string__iendswith(d: dict[str, Any], key: str, value: str) -> bool:
+    """Keep records where `key` ends with `value`, ignoring case."""
+    return d[key].lower().endswith(value.lower())
+
+
+@rules.rule()
+def string__length_eq(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where the length of `key` equals `value`."""
+    return len(d[key]) == value
+
+
+@rules.rule()
+def string__length_gt(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where the length of `key` is greater than `value`."""
+    return len(d[key]) > value
+
+
+@rules.rule()
+def string__length_ge(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where the length of `key` is greater than or equal to `value`."""
+    return len(d[key]) >= value
+
+
+@rules.rule()
+def string__length_lt(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where the length of `key` is less than `value`."""
+    return len(d[key]) < value
+
+
+@rules.rule()
+def string__length_le(d: dict[str, Any], key: str, value: int) -> bool:
+    """Keep records where the length of `key` is less than or equal to `value`."""
+    return len(d[key]) <= value
+
+
+# -----------------------
+# decimal
+# -----------------------
+
+
+def _process_decimal(value: str | float) -> Decimal:
+    if isinstance(value, (str, int)):
+        return Decimal(value)
+
+    if isinstance(value, float):
+        return Decimal.from_float(value).quantize(Decimal("0.01"))
+
+    msg = f"Unexpected type {type(value)}"
+    raise TypeError(msg)
+
+
+@rules.rule(processors=_process_decimal)
+def decimal__eq(d: dict[str, Any], key: str, value: Decimal) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule(processors=_process_decimal)
+def decimal__gt(d: dict[str, Any], key: str, value: Decimal) -> bool:
+    """Keep records where `key` is greater than `value`."""
+    return d[key] > value
+
+
+@rules.rule(processors=_process_decimal)
+def decimal__ge(d: dict[str, Any], key: str, value: Decimal) -> bool:
+    """Keep records where `key` is greater than or equal to `value`."""
+    return d[key] >= value
+
+
+@rules.rule(processors=_process_decimal)
+def decimal__lt(d: dict[str, Any], key: str, value: Decimal) -> bool:
+    """Keep records where `key` is less than `value`."""
+    return d[key] < value
+
+
+@rules.rule(processors=_process_decimal)
+def decimal__le(d: dict[str, Any], key: str, value: Decimal) -> bool:
+    """Keep records where `key` is less than or equal to `value`."""
+    return d[key] <= value
+
+
+# -----------------------
+# datetime
+# -----------------------
+
+
+@rules.rule(processors=datetime.fromisoformat)
+def datetime__eq(d: dict[str, Any], key: str, value: datetime) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule(processors=datetime.fromisoformat)
+def datetime__gt(d: dict[str, Any], key: str, value: datetime) -> bool:
+    """Keep records where `key` is greater than `value`."""
+    return d[key] > value
+
+
+@rules.rule(processors=datetime.fromisoformat)
+def datetime__ge(d: dict[str, Any], key: str, value: datetime) -> bool:
+    """Keep records where `key` is greater than or equal to `value`."""
+    return d[key] >= value
+
+
+@rules.rule(processors=datetime.fromisoformat)
+def datetime__lt(d: dict[str, Any], key: str, value: datetime) -> bool:
+    """Keep records where `key` is less than `value`."""
+    return d[key] < value
+
+
+@rules.rule(processors=datetime.fromisoformat)
+def datetime__le(d: dict[str, Any], key: str, value: datetime) -> bool:
+    """Keep records where `key` is less than or equal to `value`."""
+    return d[key] <= value
+
+
+# -----------------------
+# date
+# -----------------------
+
+
+def _to_date(value: date | str) -> date:
+    """Accept dates, datetimes (like Excel cells) and ISO strings (like JSON values)."""
+    if isinstance(value, datetime):
+        return value.date()
+
+    if isinstance(value, date):
+        return value
+
+    if isinstance(value, str):
+        return datetime.fromisoformat(value).date()
+
+    msg = f"Can not convert {type(value).__name__} '{value}' to a date"
+    raise TypeError(msg)
+
+
+@rules.rule(processors=_to_date)
+def date__eq(d: dict[str, Any], key: str, value: date) -> bool:
+    """Keep records where `key` equals `value`, comparing the day only."""
+    return _to_date(d[key]) == value
+
+
+@rules.rule(processors=_to_date)
+def date__gt(d: dict[str, Any], key: str, value: date) -> bool:
+    """Keep records where `key` is greater than `value`, comparing the day only."""
+    return _to_date(d[key]) > value
+
+
+@rules.rule(processors=_to_date)
+def date__ge(d: dict[str, Any], key: str, value: date) -> bool:
+    """Keep records where `key` is greater than or equal to `value`, comparing the day only."""
+    return _to_date(d[key]) >= value
+
+
+@rules.rule(processors=_to_date)
+def date__lt(d: dict[str, Any], key: str, value: date) -> bool:
+    """Keep records where `key` is less than `value`, comparing the day only."""
+    return _to_date(d[key]) < value
+
+
+@rules.rule(processors=_to_date)
+def date__le(d: dict[str, Any], key: str, value: date) -> bool:
+    """Keep records where `key` is less than or equal to `value`, comparing the day only."""
+    return _to_date(d[key]) <= value
+
+
+# -----------------------
+# uuid
+# -----------------------
+
+
+@rules.rule(processors=uuid.UUID)
+def uuid__eq(d: dict[str, Any], key: str, value: uuid.UUID) -> bool:
+    """Keep records where `key` equals `value`."""
+    return d[key] == value
+
+
+@rules.rule(processors=uuid.UUID)
+def uuid__gt(d: dict[str, Any], key: str, value: uuid.UUID) -> bool:
+    """Keep records where `key` is greater than `value`."""
+    return d[key] > value
+
+
+@rules.rule(processors=uuid.UUID)
+def uuid__ge(d: dict[str, Any], key: str, value: uuid.UUID) -> bool:
+    """Keep records where `key` is greater than or equal to `value`."""
+    return d[key] >= value
+
+
+@rules.rule(processors=uuid.UUID)
+def uuid__lt(d: dict[str, Any], key: str, value: uuid.UUID) -> bool:
+    """Keep records where `key` is less than `value`."""
+    return d[key] < value
+
+
+@rules.rule(processors=uuid.UUID)
+def uuid__le(d: dict[str, Any], key: str, value: uuid.UUID) -> bool:
+    """Keep records where `key` is less than or equal to `value`."""
+    return d[key] <= value

templify/models.py

@@ -0,0 +1,9 @@
+"""Types shared by readers, transformers and writers."""
+
+from typing import Any
+
+type DataItem = dict[str, Any]
+"""One record (a row), mapping column names to values."""
+
+type Data = list[dict[str, Any]]
+"""A list of records, as returned by a data reader."""

templify/readers.py

@@ -0,0 +1,148 @@
+"""Data readers: turn a data file into a list of records, picked by file extension."""
+
+import json
+from collections.abc import Callable
+from functools import wraps
+from pathlib import Path
+from typing import TypeGuard
+
+import openpyxl
+
+from .models import Data
+
+type ReadFn = Callable[[Path], Data]
+
+
+class ExtensionNotSupportedError(Exception):
+    """Raised when no reader is registered for a data file extension."""
+
+    def __init__(self, extension: str) -> None:
+        message = f"Extension '{extension}' is not supported for being a data file"
+        super().__init__(message)
+
+
+class ReaderRegistry:
+    """Maps data file extensions (case-insensitive, without the dot) to read functions.
+
+    Example:
+    ```python
+    readers = ReaderRegistry()
+
+
+    @readers.reader("csv")
+    def read_csv(filepath: Path) -> Data: ...
+
+
+    data = readers["csv"](Path("people.csv"))
+    ```
+
+    """
+
+    def __init__(self) -> None:
+        self._read_fns: dict[str, ReadFn] = {}
+
+    def __contains__(self, extension: str) -> bool:
+        """Whether a reader is registered for `extension`."""
+        return extension.lower() in self._read_fns
+
+    def __getitem__(self, extension: str) -> ReadFn:
+        """Return the reader registered for `extension`.
+
+        Raises:
+            ExtensionNotSupportedError: No reader is registered for `extension`.
+
+        """
+        if extension not in self:
+            raise ExtensionNotSupportedError(extension)
+        return self._read_fns[extension.lower()]
+
+    def reader(self, extension: str) -> Callable[[ReadFn], ReadFn]:
+        """Register the decorated function as the reader for `extension`."""
+
+        def decorator(fn: ReadFn) -> ReadFn:
+            @wraps(fn)
+            def wrapper(filepath: Path) -> Data:
+                return fn(filepath)
+
+            self._add_reader(wrapper, extension)
+
+            return wrapper
+
+        return decorator
+
+    def add_reader(self, fn: ReadFn, extension: str) -> None:
+        """Register `fn` as the reader for `extension`, replacing any existing one."""
+        self._add_reader(fn, extension)
+
+    def _add_reader(self, fn: ReadFn, extension: str) -> None:
+        self._read_fns[extension.lower()] = fn
+
+
+readers = ReaderRegistry()
+"""The default registry, used by the CLI `--data` option."""
+
+
+@readers.reader("xlsx")
+def read_excel(filepath: Path) -> Data:
+    """Read the active sheet of an Excel workbook.
+
+    The first row holds the column names, each following row is one record.
+    Fully blank rows are skipped, and formula cells give their last calculated value.
+
+    Raises:
+        ValueError: The workbook has no active sheet.
+
+    """
+    wb = openpyxl.load_workbook(filepath, data_only=True)
+    sheet = wb.active
+
+    if sheet is None:
+        message = "No sheet found"
+        raise ValueError(message)
+
+    headers = []
+
+    for row in sheet.iter_rows(min_row=1, max_row=1):
+        for cell in row:
+            headers.append(cell.value)  # noqa: PERF401
+
+    data = []
+
+    for row in sheet.iter_rows(min_row=2):
+        if all(cell.value is None for cell in row):
+            continue
+
+        row_dict = {}
+
+        for idx, cell in enumerate(row):
+            row_dict[headers[idx]] = cell.value
+
+        data.append(row_dict)
+
+    return data
+
+
+@readers.reader("json")
+def read_json(filepath: Path) -> Data:
+    """Read a UTF-8 JSON file holding a list of objects.
+
+    Raises:
+        ValueError: The file is not valid JSON, or not a list of objects.
+
+    """
+    with filepath.open(encoding="utf-8") as f:
+        data = json.load(f)
+
+    if _is_data(data):
+        return data
+
+    message = "JSON data must be a list of objects"
+    raise ValueError(message)
+
+
+def _is_data(d: object) -> TypeGuard[Data]:
+    return (
+        isinstance(d, list)
+        and all(isinstance(item, dict) for item in d)
+        and all(all(isinstance(key, str) for key in item) for item in d)
+    )

templify/transformers.py

@@ -0,0 +1,120 @@
+"""Data transformers applied before rendering: order, filter and group by."""
+
+from collections.abc import Callable
+from dataclasses import InitVar, dataclass, field
+from typing import Any, Literal
+
+from pyspecification import ExpressionWrapperDict, PredicateCompiler, PredicateDict
+
+from .models import Data, DataItem
+
+# -----------------------
+# order
+# -----------------------
+
+
+@dataclass
+class OrderByKey:
+    """A column to order by, parsed from `"column"` (ascending) or `"-column"` (descending).
+
+    Example:
+    ```python
+    OrderByKey("-salary")  # OrderByKey(name="salary", order="desc")
+    ```
+
+    """
+
+    string: InitVar[str]
+
+    name: str = field(init=False)
+    order: Literal["asc", "desc"] = field(init=False)
+
+    def __post_init__(self, key_string: str) -> None:
+        self.name = key_string.removeprefix("-")
+        self.order = "desc" if key_string.startswith("-") else "asc"
+
+
+def order_by_data(data: Data, keys: list[OrderByKey]) -> Data:
+    """Return `data` sorted by `keys`, the first key having the highest priority.
+
+    Raises:
+        KeyError: A key is missing from a record.
+
+    """
+    for key in reversed(keys):
+        data = sorted(data, key=_order_fn(key), reverse=key.order == "desc")
+
+    return data
+
+
+def _order_fn(key: OrderByKey) -> Callable[[DataItem], Any]:
+    def fn(item: DataItem) -> Any:
+        return _get_value(item, key.name)
+
+    return fn
+
+
+def _get_value(item: DataItem, key: str) -> Any:
+    if key not in item:
+        msg = f"Key '{key}' not found in data, Available keys: {', '.join(item.keys())}"
+        raise KeyError(msg)
+
+    return item[key]
+
+
+# -----------------------
+# filter
+# -----------------------
+
+
+def filter_data(
+    data: Data,
+    compiler: PredicateCompiler[DataItem, bool],
+    schema: ExpressionWrapperDict | PredicateDict,
+) -> Data:
+    """Return the records of `data` matching the filter `schema`.
+
+    Args:
+        data: The records to filter.
+        compiler: Compiles `schema` into a predicate using the filter rules.
+        schema: A single rule (`PredicateDict`), or rules combined with
+            `all` / `any` (`ExpressionWrapperDict`).
+
+    """
+    predicate = compiler.compile(schema)
+    return [row for row in data if predicate(row)]
+
+
+# -----------------------
+# group by
+# -----------------------
+
+
+def group_by_data(data: Data, keys: list[str], items_key: str = "items") -> Data:
+    """Group rows sharing the same `keys` values, keeping their first-appearance order.
+
+    Each group is a row holding the `keys` values plus its rows under `items_key`:
+
+    [{"city": "Homs", "items": [{"name": "Rama", "city": "Homs"}, ...]}, ...]
+
+    Raises:
+        KeyError: A key is missing from a record.
+        ValueError: `items_key` is one of `keys`.
+        TypeError: A key holds an unhashable value, like a list.
+
+    """
+    if items_key in keys:
+        msg = f"Items key '{items_key}' can not be one of the group by keys"
+        raise ValueError(msg)
+
+    groups: dict[tuple[Any, ...], DataItem] = {}
+
+    for item in data:
+        values = tuple(_get_value(item, key) for key in keys)
+
+        if values not in groups:
+            groups[values] = {**dict(zip(keys, values, strict=True)), items_key: []}
+
+        groups[values][items_key].append(item)
+
+    return list(groups.values())