pyprojection 0.1.2__py3-none-any.whl

pyprojection/__init__.py

@@ -0,0 +1,52 @@
+"""pyprojection: output shapes as values.
+
+`columns["name"]() & computed("Yearly pay", salary * 12)` is a `Projection`:
+it maps one subject to one dict. Columns come from a registry, the whitelist,
+so a field that is not registered can never be selected, from Python or JSON.
+"""
+
+from .compilers import (
+    ColumnCallDict,
+    ColumnDefinition,
+    Compiler,
+    ComputedDict,
+    ProjectionCompiler,
+)
+from .exceptions import (
+    ColumnAlreadyRegisteredError,
+    ColumnDoesNotExistError,
+    DuplicateOutputNameError,
+    InvalidColumnArgumentsError,
+    InvalidColumnError,
+    InvalidColumnNameError,
+    InvalidOutputNameError,
+    InvalidProjectionDefinitionError,
+    PyprojectionError,
+)
+from .json_schema import FORMULA_SCHEMA_ID, get_projection_json_schema
+from .projection import Field, Projection, computed
+from .registry import ColumnFactory, ProjectionRegistry
+
+__all__ = [
+    "FORMULA_SCHEMA_ID",
+    "ColumnAlreadyRegisteredError",
+    "ColumnCallDict",
+    "ColumnDefinition",
+    "ColumnDoesNotExistError",
+    "ColumnFactory",
+    "Compiler",
+    "ComputedDict",
+    "DuplicateOutputNameError",
+    "Field",
+    "InvalidColumnArgumentsError",
+    "InvalidColumnError",
+    "InvalidColumnNameError",
+    "InvalidOutputNameError",
+    "InvalidProjectionDefinitionError",
+    "Projection",
+    "ProjectionCompiler",
+    "ProjectionRegistry",
+    "PyprojectionError",
+    "computed",
+    "get_projection_json_schema",
+]

pyprojection/compilers.py

@@ -0,0 +1,208 @@
+"""Compile a projection from JSON: a list of columns, in output order.
+
+```json
+[
+  "name",
+  {"name": "salary", "args": [2], "kwargs": {}, "label": "Monthly pay"},
+  {"label": "Yearly pay", "formula": {"operator": "multiply", "expressions": ["salary", 12]}}
+]
+```
+
+A bare string selects a column with no arguments, so `?fields=name,salary` is
+`compiler.compile(fields.split(","))`. Formulas are delegated to an injected
+compiler, e.g. pyformula's `FormulaCompiler`.
+"""
+
+from collections.abc import Callable, Mapping
+from typing import Any, NotRequired, Protocol, TypedDict, cast
+
+from pyvocabulary import index_path, key_path, located
+
+from .exceptions import (
+    ColumnDoesNotExistError,
+    DuplicateOutputNameError,
+    InvalidColumnArgumentsError,
+    InvalidProjectionDefinitionError,
+)
+from .projection import Projection, computed
+from .registry import ProjectionRegistry
+
+_ROOT = "$"
+_CALL_KEYS = {"name", "args", "kwargs", "label"}
+_COMPUTED_KEYS = {"label", "formula"}
+
+
+class ColumnCallDict(TypedDict):
+    name: str
+    args: NotRequired[list[Any]]
+    kwargs: NotRequired[dict[str, Any]]
+    label: NotRequired[str]
+
+
+class ComputedDict(TypedDict):
+    label: str
+    formula: Any
+
+
+type ColumnDefinition = str | ColumnCallDict | ComputedDict
+
+
+class Compiler[F](Protocol):
+    """Anything with a `compile(definition) -> F` method."""
+
+    def compile(self, definition: Any, /) -> F: ...
+
+
+class ProjectionCompiler[T]:
+    """Compile projection definitions against a registry of columns.
+
+    Every problem is reported here, before any subject is exported. Errors from
+    the registry and the formula compiler keep their type and get a note with
+    their JSON path.
+
+    Args:
+        columns: The registry; only its visible columns can be selected.
+        formulas: Compiles the `formula` of computed columns. Without it, a
+            definition with a computed column is rejected.
+
+    Example:
+    ```python
+    >>> columns = ProjectionRegistry[dict[str, str]]()
+    >>> @columns.column()
+    ... def name(user: dict[str, str]) -> str:
+    ...     return user["name"]
+    >>> compiler = ProjectionCompiler(columns)
+    >>> compiler.compile(["name", {"name": "name", "label": "Name again"}])
+    Projection(name, Name again)
+    >>> compiler.compile(["name", "email"])
+    Traceback (most recent call last):
+    ...
+    pyprojection.exceptions.ColumnDoesNotExistError: Column 'email' does not exist. ...
+
+    ```
+
+    """
+
+    __slots__ = ("_columns", "_formulas")
+
+    def __init__(
+        self,
+        columns: ProjectionRegistry[T],
+        formulas: Compiler[Callable[[T], Any]] | None = None,
+        /,
+    ) -> None:
+        self._columns = columns
+        self._formulas = formulas
+
+    def compile(self, definition: list[ColumnDefinition] | Any, /) -> Projection[T]:
+        """Compile `definition` into a `Projection`.
+
+        Raises:
+            InvalidProjectionDefinitionError: If the definition has the wrong shape.
+            ColumnDoesNotExistError: If a column is not registered or is hidden.
+            InvalidColumnArgumentsError: If a column's `args`/`kwargs` do not fit it.
+            DuplicateOutputNameError: If two columns share an output name.
+
+        """
+        if not isinstance(definition, list):
+            raise _invalid(_ROOT, f"expected a list, received {definition!r}")
+
+        if not definition:
+            raise _invalid(_ROOT, "expected at least one column")
+
+        projection: Projection[T] = Projection(())
+
+        for index, item in enumerate(cast("list[Any]", definition)):
+            path = index_path(_ROOT, index)
+            column = self._compile_column(item, path)
+
+            with located(path, DuplicateOutputNameError):
+                projection &= column
+
+        return projection
+
+    def _compile_column(self, item: Any, path: str) -> Projection[T]:
+        match item:
+            case str():
+                with located(path, ColumnDoesNotExistError):
+                    return self._columns[item]()
+            case Mapping():
+                item = cast("Mapping[str, Any]", item)
+
+                if "name" in item and "formula" in item:
+                    raise _invalid(path, "use either 'name' or 'formula', not both")
+
+                if "formula" in item:
+                    return self._compile_computed(item, path)
+
+                if "name" in item:
+                    return self._compile_call(item, path)
+
+                raise _invalid(path, "missing 'name' or 'formula'")
+            case _:
+                raise _invalid(path, f"expected a column name or an object, received {item!r}")
+
+    def _compile_call(self, item: Mapping[str, Any], path: str) -> Projection[T]:
+        _check_unknown_keys(item, _CALL_KEYS, path)
+        name, args, kwargs = item["name"], item.get("args", []), item.get("kwargs", {})
+
+        if not isinstance(name, str):
+            raise _invalid(key_path(path, "name"), f"expected a string, received {name!r}")
+
+        if not isinstance(args, list):
+            raise _invalid(key_path(path, "args"), f"expected a list, received {args!r}")
+
+        if not isinstance(kwargs, Mapping):
+            raise _invalid(key_path(path, "kwargs"), f"expected an object, received {kwargs!r}")
+
+        if "label" in kwargs:
+            raise _invalid(key_path(path, "kwargs"), "'label' goes beside 'name', not in 'kwargs'")
+
+        label = _label(item, path) if "label" in item else None
+
+        with located(path, ColumnDoesNotExistError, InvalidColumnArgumentsError):
+            return self._columns[name](
+                *cast("list[Any]", args), label=label, **cast("Mapping[str, Any]", kwargs)
+            )
+
+    def _compile_computed(self, item: Mapping[str, Any], path: str) -> Projection[T]:
+        _check_unknown_keys(item, _COMPUTED_KEYS, path)
+
+        if "label" not in item:
+            raise _invalid(path, "missing 'label', a computed column needs an output name")
+
+        label = _label(item, path)
+
+        if self._formulas is None:
+            raise _invalid(path, "computed columns are not allowed: no formula compiler was given")
+
+        with located(key_path(path, "formula"), Exception):
+            formula = self._formulas.compile(item["formula"])
+
+        return computed(label, formula)
+
+
+# -----------------------
+# helpers
+# -----------------------
+
+
+def _label(item: Mapping[str, Any], path: str) -> str:
+    label = item["label"]
+
+    if not isinstance(label, str) or not label:
+        raise _invalid(key_path(path, "label"), f"expected a non-empty string, received {label!r}")
+
+    return label
+
+
+def _check_unknown_keys(item: Mapping[str, Any], allowed: set[str], path: str) -> None:
+    if unknown := sorted(set(item) - allowed):
+        problem = (
+            f"unknown {', '.join(map(repr, unknown))}. Allowed keys: {', '.join(sorted(allowed))}"
+        )
+        raise _invalid(path, problem)
+
+
+def _invalid(path: str, problem: str) -> InvalidProjectionDefinitionError:
+    return InvalidProjectionDefinitionError(f"Invalid projection at {path}: {problem}")

pyprojection/exceptions.py

@@ -0,0 +1,65 @@
+"""Exceptions raised by pyprojection.
+
+Errors raised by an injected formula compiler keep their own type (e.g.
+pyformula's `FormulaNotFoundError`); pyprojection only adds a note with their
+JSON path, e.g. `at $[3].formula`.
+"""
+
+from collections.abc import Iterable
+
+from pyvocabulary import InvalidNameError
+
+
+class PyprojectionError(Exception):
+    """Base class for every exception raised by pyprojection."""
+
+
+class ColumnDoesNotExistError(PyprojectionError, LookupError):
+    """Raised when a column is not registered, or is hidden.
+
+    Example:
+    ```python
+    >>> str(ColumnDoesNotExistError("salary", ["name", "department"]))
+    "Column 'salary' does not exist. Available columns: name, department"
+
+    ```
+
+    """
+
+    def __init__(self, name: str, available: Iterable[str], /) -> None:
+        names = ", ".join(available) or "(none)"
+        super().__init__(f"Column '{name}' does not exist. Available columns: {names}")
+
+
+class ColumnAlreadyRegisteredError(PyprojectionError):
+    """Raised when a column name is registered twice in the same registry."""
+
+    def __init__(self, name: str, /) -> None:
+        super().__init__(f"Column '{name}' is already registered.")
+
+
+class InvalidColumnNameError(PyprojectionError, InvalidNameError):
+    """Raised when a column name is not a valid ASCII Python identifier."""
+
+    def __init__(self, name: object, /) -> None:
+        super().__init__(name, kind="column")
+
+
+class InvalidColumnError(PyprojectionError, TypeError):
+    """Raised when a function cannot be used as a column (checked when registered)."""
+
+
+class InvalidColumnArgumentsError(PyprojectionError, TypeError):
+    """Raised when a column factory is called with arguments its function does not take."""
+
+
+class InvalidOutputNameError(PyprojectionError, ValueError):
+    """Raised when an output name (a label) is not a non-empty string."""
+
+
+class DuplicateOutputNameError(PyprojectionError, ValueError):
+    """Raised when two fields of one projection share an output name."""
+
+
+class InvalidProjectionDefinitionError(PyprojectionError, ValueError):
+    """Raised when a JSON projection definition does not have the expected shape."""

pyprojection/json_schema.py

@@ -0,0 +1,76 @@
+"""The JSON Schema of a projection definition, as accepted by `ProjectionCompiler.compile`.
+
+Generated from the registry, so a column picker can list exactly the selectable
+columns (`$defs.column_name.enum`) and an editor can check arguments as typed.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pyvocabulary import JSON_SCHEMA_DIALECT, call_json_schema
+
+from .registry import ProjectionRegistry
+
+FORMULA_SCHEMA_ID = "urn:pyprojection:formula"
+
+_LABEL_SCHEMA = {"type": "string", "minLength": 1}
+
+
+def get_projection_json_schema(
+    columns: ProjectionRegistry[Any],
+    formula_schema: Mapping[str, Any] | None = None,
+    /,
+) -> dict[str, Any]:
+    """Return the JSON Schema of a list of column names, column calls and computed columns.
+
+    Args:
+        columns: The registry; hidden columns are left out.
+        formula_schema: The schema of one `formula`. Without it, computed columns
+            are not allowed, matching a `ProjectionCompiler` without a formula compiler.
+
+    Example:
+    ```python
+    >>> columns = ProjectionRegistry[dict[str, int]]()
+    >>> @columns.column()
+    ... def age(user: dict[str, int], *, in_months: bool = False) -> int:
+    ...     '''Age in years.'''
+    ...     return user["age"] * 12 if in_months else user["age"]
+    >>> schema = get_projection_json_schema(columns)
+    >>> schema["$defs"]["column_name"]
+    {'type': 'string', 'enum': ['age']}
+    >>> call = schema["$defs"]["call"]["anyOf"][0]
+    >>> call["properties"]["kwargs"]["properties"], call["description"]
+    ({'in_months': {'type': 'boolean', 'default': False}}, 'Age in years.')
+
+    ```
+
+    """
+    calls = [
+        call_json_schema(name, factory, extra_properties={"label": _LABEL_SCHEMA})
+        for name, factory in columns.columns.items()
+    ]
+    items: list[dict[str, Any]] = [{"$ref": "#/$defs/column_name"}, {"$ref": "#/$defs/call"}]
+    defs: dict[str, Any] = {
+        "column_name": {"type": "string", "enum": list(columns.columns)},
+        # `anyOf` must not be empty; with no columns, no call is valid
+        "call": {"anyOf": calls} if calls else False,
+    }
+
+    if formula_schema is not None:
+        items.append({"$ref": "#/$defs/computed"})
+        defs["computed"] = {
+            "type": "object",
+            "properties": {"label": _LABEL_SCHEMA, "formula": {"$ref": FORMULA_SCHEMA_ID}},
+            "required": ["label", "formula"],
+            "additionalProperties": False,
+        }
+        # its own `$id`, so `#/$defs/...` refs inside it keep pointing into itself
+        defs["formula"] = {**formula_schema, "$id": FORMULA_SCHEMA_ID}
+
+    return {
+        "$schema": JSON_SCHEMA_DIALECT,
+        "type": "array",
+        "minItems": 1,
+        "items": {"anyOf": items},
+        "$defs": defs,
+    }

pyprojection/projection.py

@@ -0,0 +1,111 @@
+"""Output shapes as values: which fields, under which names, computed how.
+
+```python
+export = (
+    columns["name"]()
+    & columns["salary"](label="Monthly pay")
+    & computed("Yearly pay", salary * 12)
+)
+export(employee)  # {"name": ..., "Monthly pay": ..., "Yearly pay": ...}
+```
+
+A projection is an ordered tuple of `(output name, callable)` pairs. `&` joins
+two of them; a repeated output name is rejected when the projection is built,
+not when the first row is exported.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .exceptions import DuplicateOutputNameError, InvalidColumnError, InvalidOutputNameError
+
+type Field[T] = tuple[str, Callable[[T], Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class Projection[T]:
+    """Fields in output order. Calling it maps one subject to one dict.
+
+    Build projections with a `ProjectionRegistry` and `computed`, then join them with `&`.
+
+    Example:
+    ```python
+    >>> person = computed("name", lambda p: p["name"]) & computed("age", lambda p: p["age"])
+    >>> person
+    Projection(name, age)
+    >>> person({"name": "Alice", "age": 30, "password": "hunter2"})
+    {'name': 'Alice', 'age': 30}
+    >>> person.names
+    ('name', 'age')
+    >>> person & computed("age", lambda p: p["age"] + 1)
+    Traceback (most recent call last):
+    ...
+    pyprojection.exceptions.DuplicateOutputNameError: Output name 'age' is used more than once. ...
+
+    ```
+
+    """
+
+    fields: tuple[Field[T], ...]
+
+    def __post_init__(self) -> None:
+        seen: set[str] = set()
+
+        for name, value in self.fields:
+            _check_output_name(name)
+
+            if not callable(value):
+                msg = f"Column '{name}' must be callable, received {value!r}"
+                raise InvalidColumnError(msg)
+
+            if name in seen:
+                msg = (
+                    f"Output name '{name}' is used more than once. "
+                    "Give one of them another name with label=..."
+                )
+                raise DuplicateOutputNameError(msg)
+
+            seen.add(name)
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        """The output names in order, e.g. a CSV header."""
+        return tuple(name for name, _ in self.fields)
+
+    def __call__(self, subject: T, /) -> dict[str, Any]:
+        return {name: value(subject) for name, value in self.fields}
+
+    def __and__(self, other: "Projection[T]", /) -> "Projection[T]":
+        match other:
+            case Projection(fields=fields):
+                return Projection((*self.fields, *fields))
+            case _:
+                return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"Projection({', '.join(self.names)})"
+
+
+def computed[T](name: str, value: Callable[[T], Any], /) -> Projection[T]:
+    """Return a one-field projection that outputs `value(subject)` under `name`.
+
+    Args:
+        name: The output name, any non-empty string (`"Yearly pay"` is fine).
+        value: Any `T -> R` callable, typically a pyformula `Formula`.
+
+    Example:
+    ```python
+    >>> computed("Initial", lambda name: name[0])("Alice")
+    {'Initial': 'A'}
+
+    ```
+
+    """
+    return Projection(((name, value),))
+
+
+def _check_output_name(name: object) -> None:
+    if not isinstance(name, str) or not name:
+        msg = f"Invalid output name: {name!r}, expected a non-empty string"
+        raise InvalidOutputNameError(msg)

pyprojection/registry.py

@@ -0,0 +1,153 @@
+"""The columns a projection may select: the whitelist, and so the privacy boundary.
+
+A registered function `fn(subject, *args, **kwargs)` becomes a factory: calling
+`columns["salary"](2, label="Monthly pay")` binds the arguments right away and
+returns a one-field `Projection`. A field that is not registered cannot be
+selected at all, from Python lookups or from JSON.
+"""
+
+from collections.abc import Callable, Mapping
+from functools import update_wrapper
+from inspect import Parameter, Signature, signature
+from typing import Any, Protocol
+
+from pyvocabulary import Vocabulary
+
+from .exceptions import (
+    ColumnAlreadyRegisteredError,
+    ColumnDoesNotExistError,
+    InvalidColumnArgumentsError,
+    InvalidColumnError,
+    InvalidColumnNameError,
+)
+from .projection import Projection
+
+_SUBJECT_KINDS = (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
+_LABEL = "label"
+
+
+class ColumnFactory[T](Protocol):
+    """Builds a one-field `Projection` from the column's arguments and an optional label."""
+
+    def __call__(self, *args: Any, label: str | None = None, **kwargs: Any) -> Projection[T]: ...
+
+
+class ProjectionRegistry[T]:
+    """Named columns over subjects of type `T`, registered with `@registry.column()`.
+
+    Example:
+    ```python
+    >>> columns = ProjectionRegistry[dict[str, str]]()
+    >>> @columns.column()
+    ... def name(user: dict[str, str], *, upper: bool = False) -> str:
+    ...     return user["name"].upper() if upper else user["name"]
+    >>> @columns.column(hidden=True)
+    ... def password(user: dict[str, str]) -> str:
+    ...     return user["password"]
+    >>> list(columns.columns)
+    ['name']
+    >>> columns["name"](upper=True, label="Name")({"name": "Alice", "password": "x"})
+    {'Name': 'ALICE'}
+    >>> columns["password"]
+    Traceback (most recent call last):
+    ...
+    pyprojection.exceptions.ColumnDoesNotExistError: Column 'password' does not exist. ...
+
+    ```
+
+    """
+
+    __slots__ = ("_columns",)
+
+    def __init__(self) -> None:
+        self._columns: Vocabulary[ColumnFactory[T]] = Vocabulary(
+            "column",
+            does_not_exist=ColumnDoesNotExistError,
+            already_registered=ColumnAlreadyRegisteredError,
+            invalid_name=InvalidColumnNameError,
+        )
+
+    @property
+    def columns(self) -> Mapping[str, ColumnFactory[T]]:
+        """A read-only view of the visible columns, the ones a compiler may select."""
+        return self._columns
+
+    def __getitem__(self, name: str, /) -> ColumnFactory[T]:
+        return self._columns[name]
+
+    def column(
+        self,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        hidden: bool = False,
+    ) -> Callable[[Callable[..., Any]], ColumnFactory[T]]:
+        """Return a decorator that registers a function as a column and returns its factory.
+
+        Args:
+            name: The column name. Defaults to the function's name.
+            description: Documents the column in its JSON Schema. Defaults to the docstring.
+            hidden: Keep the column usable from Python but out of lookups, compilers
+                and schemas, e.g. for a field only internal reports may show.
+
+        """
+
+        def decorator(fn: Callable[..., Any]) -> ColumnFactory[T]:
+            return self.register_column(fn, name=name, description=description, hidden=hidden)
+
+        return decorator
+
+    def register_column(
+        self,
+        fn: Callable[..., Any],
+        /,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        hidden: bool = False,
+    ) -> ColumnFactory[T]:
+        """Register `fn(subject, *args, **kwargs)` as a column and return its factory.
+
+        Raises:
+            InvalidColumnNameError: If the name is not a Python identifier (a lambda needs `name=`).
+            ColumnAlreadyRegisteredError: If the name is taken, hidden or not.
+            InvalidColumnError: If `fn` takes no subject, or has a `label` parameter.
+
+        """
+        column_name: str = name or getattr(fn, "__name__", "")
+        factory: ColumnFactory[T] = _factory(fn, column_name, description)
+        return self._columns.add(column_name, factory, hidden=hidden)
+
+
+def _factory(fn: Callable[..., Any], name: str, description: str | None) -> ColumnFactory[Any]:
+    parameters = list(signature(fn).parameters.values())
+
+    if not parameters or parameters[0].kind not in _SUBJECT_KINDS:
+        msg = f"Column '{name}' must take the subject as its first positional parameter."
+        raise InvalidColumnError(msg)
+
+    if any(parameter.name == _LABEL for parameter in parameters):
+        msg = (
+            f"Column '{name}' has a 'label' parameter, but 'label' is reserved for the output name."
+        )
+        raise InvalidColumnError(msg)
+
+    arguments = Signature(parameters[1:])
+
+    def factory(*args: Any, label: str | None = None, **kwargs: Any) -> Projection[Any]:
+        try:
+            bound = arguments.bind(*args, **kwargs)
+        except TypeError as error:
+            msg = f"Column '{name}' got invalid arguments: {error}"
+            raise InvalidColumnArgumentsError(msg) from error
+
+        def value(subject: Any) -> Any:
+            return fn(subject, *bound.args, **bound.kwargs)
+
+        return Projection(((name if label is None else label, value),))
+
+    update_wrapper(factory, fn)
+    # the JSON Schema describes the arguments JSON sends, so the subject is left out
+    factory.__signature__ = arguments  # pyright: ignore[reportFunctionMemberAccess]
+    factory.__doc__ = description or fn.__doc__
+    return factory

pyprojection-0.1.2.dist-info/METADATA

@@ -0,0 +1,389 @@
+Metadata-Version: 2.4
+Name: pyprojection
+Version: 0.1.2
+Summary: Output shapes as values: which fields, under which names, computed how; definable as JSON.
+Keywords: projection,export,serialization,json,dsl,composition
+Author: aaltatan
+Author-email: aaltatan <a.altatan@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pyvocabulary>=0.1.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/aaltatan/pyprojection
+Project-URL: Repository, https://github.com/aaltatan/pyprojection
+Project-URL: Issues, https://github.com/aaltatan/pyprojection/issues
+Description-Content-Type: text/markdown
+
+# pyprojection
+
+Output shapes as values: which fields, under which names, computed how. Composable with `&`
+and definable as JSON.
+
+```python
+export = (
+    columns["name"]()
+    & columns["monthly_salary"](label="Monthly pay")
+    & computed("Yearly pay", salary * 12)
+)
+
+export(employee)
+# {'name': 'Alice', 'Monthly pay': Decimal('3000.00'), 'Yearly pay': Decimal('36000.00')}
+```
+
+A `Projection` maps one subject to one dict. Columns come from a registry, which is the
+**privacy boundary**: a field that is not registered (or is registered as hidden) can never be
+selected, not from Python lookups and not from a JSON definition a user sent.
+
+| Piece | What it does |
+| --- | --- |
+| [`ProjectionRegistry`](#registering-columns) | The whitelist: `@columns.column()` turns `fn(subject, ...)` into a column factory |
+| [`Projection`](#composing-with-) | Ordered `(output name, callable)` pairs; callable, joined with `&` |
+| [`computed`](#computed-columns) | A derived column from any `T -> R` callable, e.g. a pyformula `Formula` |
+| [`ProjectionCompiler`](#from-json) | Builds a `Projection` from JSON (or `?fields=`), errors carry a JSON path |
+| [`get_projection_json_schema`](#json-schema) | The JSON Schema of that JSON, generated from the registry |
+
+**When not to use it.** If the output shape is fixed, write a dict comprehension. pyprojection
+earns its place when a screen lets *users* choose their columns: an export dialog, a report
+builder, a `?fields=` API parameter.
+
+## Installation
+
+```bash
+uv add pyprojection
+```
+
+Python 3.12+. The only runtime dependency is
+[pyvocabulary](https://github.com/aaltatan/pyvocabulary). [pyformula](https://github.com/aaltatan/pyformula)
+is optional: `computed` takes any callable.
+
+## Quick start
+
+The examples in this README build on each other and are run by the test suite. A comment
+directly under a line shows what it outputs or raises.
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+from pyformula import variable
+from pyprojection import ProjectionRegistry, computed
+
+
+@dataclass(frozen=True)
+class Employee:
+    name: str
+    department: str
+    salary: Decimal
+    national_id: str
+
+
+alice = Employee("Alice", "Sales", Decimal("3000.00"), "123-45")
+
+bob = Employee("Bob", "IT", Decimal("4500.50"), "678-90")
+
+columns = ProjectionRegistry[Employee]()
+
+
+@columns.column()
+def name(employee: Employee) -> str:
+    """Full name."""
+    return employee.name
+
+
+@columns.column()
+def monthly_salary(employee: Employee, places: int = 2) -> Decimal:
+    """Monthly salary, rounded to `places` decimals."""
+    return round(employee.salary, places)
+
+
+@variable()
+def salary(employee: Employee) -> Decimal:
+    return employee.salary
+
+
+export = (
+    columns["name"]()
+    & columns["monthly_salary"](label="Monthly pay")
+    & computed("Yearly pay", salary * 12)
+)
+
+export
+# Projection(name, Monthly pay, Yearly pay)
+
+export(alice)
+# {'name': 'Alice', 'Monthly pay': Decimal('3000.00'), 'Yearly pay': Decimal('36000.00')}
+
+[export(e)["name"] for e in (alice, bob)]
+# ['Alice', 'Bob']
+```
+
+## Registering columns
+
+A column is a function whose first parameter is the subject. Any further parameters become
+arguments of its factory, bound **when the projection is built**, so a wrong argument fails
+before the first row is exported.
+
+```python
+@columns.column(name="department", description="Department, optionally upper-cased.")
+def dept(employee: Employee, *, upper: bool = False) -> str:
+    return employee.department.upper() if upper else employee.department
+
+
+columns["department"](upper=True)(alice)
+# {'department': 'SALES'}
+
+columns["monthly_salary"](0)(bob)
+# {'monthly_salary': Decimal('4500')}
+
+columns["department"](lower=True)
+# InvalidColumnArgumentsError: Column 'department' got invalid arguments: got an unexpected keyword argument 'lower'
+```
+
+`label=` sets the output name. It is reserved on every factory, so a column function may not
+have a `label` parameter of its own (that is rejected at registration).
+
+```python
+columns["name"](label="Full name")(alice)
+# {'Full name': 'Alice'}
+```
+
+The decorator returns the factory, so it can also be used directly:
+
+```python
+name()(bob)
+# {'name': 'Bob'}
+```
+
+Register a lambda or an existing function without the decorator with `register_column`:
+
+```python
+columns.register_column(lambda e: e.name[0], name="initial")
+
+columns["initial"]()(alice)
+# {'initial': 'A'}
+```
+
+### Hidden columns
+
+`hidden=True` keeps a column usable from Python (through the factory the decorator returns)
+but out of lookups, compilers and schemas. Use it for fields only internal code may export.
+
+```python
+@columns.column(hidden=True)
+def national_id(employee: Employee) -> str:
+    return employee.national_id
+
+
+national_id()(alice)
+# {'national_id': '123-45'}
+
+list(columns.columns)
+# ['name', 'monthly_salary', 'department', 'initial']
+
+columns["national_id"]
+# ColumnDoesNotExistError: Column 'national_id' does not exist. Available columns: name, monthly_salary, department, initial
+```
+
+## Composing with `&`
+
+`&` returns a new projection with the fields of both, in order. Projections are frozen, so a
+base projection can be shared and extended safely.
+
+```python
+base = columns["name"]() & columns["department"]()
+
+payroll = base & columns["monthly_salary"](label="Pay")
+
+base.names, payroll.names
+# (('name', 'department'), ('name', 'department', 'Pay'))
+```
+
+`names` is the output header, e.g. for CSV. Two fields with the same output name are rejected
+when built; give one a `label`:
+
+```python
+base & columns["name"]()
+# DuplicateOutputNameError: Output name 'name' is used more than once. Give one of them another name with label=...
+
+(base & columns["name"](label="Name again")).names
+# ('name', 'department', 'Name again')
+```
+
+## Computed columns
+
+`computed(name, fn)` adds a derived column. The output name can be any non-empty string, and
+`fn` any callable: a pyformula `Formula`, a lambda, a method.
+
+```python
+bonus = computed("Bonus", (salary * Decimal("0.10")))
+
+(base & bonus)(bob)
+# {'name': 'Bob', 'department': 'IT', 'Bonus': Decimal('450.0500')}
+
+computed("Shouting", lambda e: e.name.upper())(alice)
+# {'Shouting': 'ALICE'}
+```
+
+## From JSON
+
+`ProjectionCompiler` builds a projection from a list of columns. Each item is one of:
+
+| Item | Meaning |
+| --- | --- |
+| `"name"` | A column with no arguments |
+| `{"name": ..., "args": [...], "kwargs": {...}, "label": ...}` | A column call; all keys but `name` are optional |
+| `{"label": ..., "formula": ...}` | A computed column; `formula` goes to the formula compiler you inject |
+
+```python
+from pyformula import FormulaCompiler, FormulaNotFoundError, decimal_literal
+from pyprojection import ProjectionCompiler
+
+compiler = ProjectionCompiler(
+    columns,
+    FormulaCompiler[Employee]({"salary": salary}, literal=decimal_literal),
+)
+
+report = compiler.compile(
+    [
+        "name",
+        {"name": "department", "kwargs": {"upper": True}, "label": "Dept"},
+        {"name": "monthly_salary", "args": [0], "label": "Monthly pay"},
+        {"label": "Yearly pay", "formula": {"operator": "multiply", "expressions": ["salary", 12]}},
+    ]
+)
+
+report
+# Projection(name, Dept, Monthly pay, Yearly pay)
+
+report(alice)
+# {'name': 'Alice', 'Dept': 'SALES', 'Monthly pay': Decimal('3000'), 'Yearly pay': Decimal('36000.00')}
+```
+
+`literal=decimal_literal` keeps JSON numbers exact in money formulas. Leave the formula compiler
+out to allow registered columns only: a definition with a computed column is then rejected.
+
+### Errors point at the JSON
+
+Every problem is found by `compile`, before any row is exported. Errors keep their type and get
+a note with their JSON path, so an API can answer `400` with exactly what is wrong.
+
+```python
+try:
+    compiler.compile(["name", "national_id"])
+except LookupError as error:
+    print(error, error.__notes__)
+# Column 'national_id' does not exist. Available columns: name, monthly_salary, department, initial ['at $[1]']
+
+try:
+    compiler.compile(
+        ["name", {"label": "x", "formula": {"operator": "add", "expressions": ["salry", 1]}}]
+    )
+except FormulaNotFoundError as error:  # pyformula's own error type is kept
+    print(error.__notes__)
+# ['at $[1].formula.expressions[0]']
+
+compiler.compile([{"name": "name", "kwarg": {}}])
+# InvalidProjectionDefinitionError: Invalid projection at $[0]: unknown 'kwarg'. Allowed keys: args, kwargs, label, name
+```
+
+## Recipes
+
+### `?fields=` in an API
+
+A bare string is a column, so a comma-separated query parameter compiles as it is. Hidden and
+unregistered fields are refused, which is the point.
+
+```python
+fields = "name,department"  # request.query_params["fields"]
+
+compiler.compile(fields.split(","))(bob)
+# {'name': 'Bob', 'department': 'IT'}
+```
+
+### CSV export
+
+```python
+import csv, io
+
+out = io.StringIO()
+
+writer = csv.DictWriter(out, fieldnames=report.names, lineterminator="\n")
+
+writer.writeheader()
+
+writer.writerows(report(e) for e in (alice, bob))
+
+print(out.getvalue())
+# name,Dept,Monthly pay,Yearly pay
+# Alice,SALES,3000,36000.00
+# Bob,IT,4500,54006.00
+```
+
+### Saved report layouts
+
+Store the JSON the user built (in a database row, a settings file) and compile it when the
+report runs. A layout that refers to a column you have since removed fails with its path, not
+with a half-written file.
+
+## JSON Schema
+
+`get_projection_json_schema(columns, formula_schema=None)` describes what `compile` accepts. It
+is generated from the registry: column names, each column's arguments (from its signature) and
+its description (from its docstring or `description=`). Hidden columns are left out.
+
+```python
+from pyprojection import get_projection_json_schema
+
+schema = get_projection_json_schema(columns)
+
+schema["$defs"]["column_name"]["enum"]  # what a column picker lists
+# ['name', 'monthly_salary', 'department', 'initial']
+
+department = schema["$defs"]["call"]["anyOf"][2]
+
+department["description"]
+# 'Department, optionally upper-cased.'
+
+department["properties"]["kwargs"]["properties"]
+# {'upper': {'type': 'boolean', 'default': False}}
+```
+
+Pass `formula_schema` to allow computed columns; it is embedded under its own `$id`
+(`urn:pyprojection:formula`) so `$ref`s inside it keep working.
+
+## Errors
+
+All errors derive from `PyprojectionError` and also from the matching built-in, so
+`except LookupError` / `ValueError` / `TypeError` work too.
+
+| Exception | Also a | Raised when |
+| --- | --- | --- |
+| `ColumnDoesNotExistError` | `LookupError` | A column is not registered or is hidden |
+| `ColumnAlreadyRegisteredError` | | A column name is registered twice |
+| `InvalidColumnNameError` | `ValueError` | A column name is not a Python identifier (a lambda needs `name=`) |
+| `InvalidColumnError` | `TypeError` | A function takes no subject or has a `label` parameter; a computed value is not callable |
+| `InvalidColumnArgumentsError` | `TypeError` | A factory gets arguments its function does not take |
+| `InvalidOutputNameError` | `ValueError` | An output name is not a non-empty string |
+| `DuplicateOutputNameError` | `ValueError` | Two fields of one projection share an output name |
+| `InvalidProjectionDefinitionError` | `ValueError` | A JSON definition has the wrong shape |
+
+## The family
+
+pyprojection is one of a set of packages that wrap a `Callable[[T], R]` in an immutable value
+with an algebra: [pyspecification](https://github.com/aaltatan/pyspecification) (`T -> bool`,
+`& | ~`), [pyformula](https://github.com/aaltatan/pyformula) (`T -> number`, arithmetic),
+[pyflowstep](https://github.com/aaltatan/pyflowstep) (`T -> T`, `>>`),
+[pyruleset](https://github.com/aaltatan/pyruleset) (`T -> V`, first match wins) and
+pyprojection (`T -> dict`, `&`). They share [pyvocabulary](https://github.com/aaltatan/pyvocabulary)
+for registries, JSON Schemas and JSON-path errors.
+
+## License
+
+GPL-3.0-only.

pyprojection-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyprojection/__init__.py,sha256=_y8GKarc9UUtdp8sm3oDvsGQ56e1Wi6-rFdJ3AVrKrM,1493
+pyprojection/compilers.py,sha256=XHS_FCRowUSSTxNMJdu1O4kdYPvH2G9sA2CqiW_5wcU,7247
+pyprojection/exceptions.py,sha256=1WzpOAnP_ENkbS5Xn8QlL5XInBGmx6ffOi79eiSFqXQ,2232
+pyprojection/json_schema.py,sha256=ydQnjp19A5f77gIPG7Zr_SYL178SS9fUe-BZqnViies,2856
+pyprojection/projection.py,sha256=uCnozYrLWF4crNqrh0PR-X7vploDOzX2yr1bXs4QyUU,3540
+pyprojection/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyprojection/registry.py,sha256=b6Bv06ea_Ou08dh__qrhA0buZN6T9s5shGTmA3q7GQc,5744
+pyprojection-0.1.2.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+pyprojection-0.1.2.dist-info/METADATA,sha256=XK9Cu5tZpTYhh7-2p_IBpO0A8Os_p7r5LeSXWKJ6tfI,13251
+pyprojection-0.1.2.dist-info/RECORD,,

pyprojection-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.6
+Root-Is-Purelib: true
+Tag: py3-none-any