pyordering 0.1.2__py3-none-any.whl

pyordering/__init__.py

@@ -0,0 +1,41 @@
+"""pyordering: sort orders as composable values.
+
+`~stars() >> price() >> name()` is an `Ordering`: keys applied left to right,
+sorting in memory with stable passes, compilable from JSON, and renderable to
+ORM `order_by` clauses.
+"""
+
+from .compilers import KeyDict, OrderingCompiler
+from .exceptions import (
+    InvalidKeyError,
+    InvalidKeyNameError,
+    InvalidOrderingDefinitionError,
+    KeyAlreadyRegisteredError,
+    KeyArgumentError,
+    KeyDoesNotExistError,
+    PyorderingError,
+)
+from .json_schema import get_ordering_json_schema
+from .ordering import Key, KeyFactory, KeyFn, Nulls, Ordering, Render, key
+from .registry import OrderingRegistry
+
+__all__ = [
+    "InvalidKeyError",
+    "InvalidKeyNameError",
+    "InvalidOrderingDefinitionError",
+    "Key",
+    "KeyAlreadyRegisteredError",
+    "KeyArgumentError",
+    "KeyDict",
+    "KeyDoesNotExistError",
+    "KeyFactory",
+    "KeyFn",
+    "Nulls",
+    "Ordering",
+    "OrderingCompiler",
+    "OrderingRegistry",
+    "PyorderingError",
+    "Render",
+    "get_ordering_json_schema",
+    "key",
+]

pyordering/compilers.py

@@ -0,0 +1,135 @@
+"""Compile an ordering from JSON: `[{"name": "stars", "descending": true}, {"name": "id"}]`.
+
+Only registered keys compile, so a definition sent by a client (a `?sort=`
+parameter, a saved view) can sort by nothing but the fields you allowed.
+"""
+
+from collections.abc import Mapping
+from typing import Any, NotRequired, TypedDict, cast
+
+from pyvocabulary import index_path, key_path, located
+
+from .exceptions import InvalidOrderingDefinitionError, KeyDoesNotExistError, PyorderingError
+from .ordering import KeyFactory, Nulls, Ordering
+
+_ALLOWED_KEYS = {"name", "args", "kwargs", "descending", "nulls"}
+
+
+class KeyDict(TypedDict):
+    name: str
+    args: NotRequired[list[Any]]
+    kwargs: NotRequired[dict[str, Any]]
+    descending: NotRequired[bool]
+    nulls: NotRequired[Nulls]
+
+
+class OrderingCompiler[T]:
+    """Compile JSON ordering definitions using a mapping of key factories.
+
+    Every problem is reported here, before anything is sorted, with a note
+    giving its JSON path.
+
+    Example:
+    ```python
+    >>> from pyordering import OrderingRegistry
+    >>> registry = OrderingRegistry[str]()
+    >>> @registry.key()
+    ... def length(word: str) -> int:
+    ...     return len(word)
+    >>> compiler = OrderingCompiler(registry.keys)
+    >>> ordering = compiler.compile([{"name": "length", "descending": True}])
+    >>> ordering, ordering(["fig", "apple", "kiwi"])
+    (Ordering(~length), ['apple', 'kiwi', 'fig'])
+    >>> compiler.compile([{"name": "size"}])
+    Traceback (most recent call last):
+    ...
+    pyordering.exceptions.KeyDoesNotExistError: Key 'size' does not exist. Available keys: length
+    at $[0].name
+
+    ```
+
+    """
+
+    __slots__ = ("_keys",)
+
+    def __init__(self, keys: Mapping[str, KeyFactory[T, ...]], /) -> None:
+        self._keys = keys
+
+    def compile(self, definition: list[KeyDict] | Any, /) -> Ordering[T]:
+        """Compile `definition`, a list of key objects, into an `Ordering`.
+
+        Raises:
+            InvalidOrderingDefinitionError: If the definition has the wrong shape.
+            KeyDoesNotExistError: If a name is not a registered key.
+            KeyArgumentError: If `args` or `kwargs` do not fit the key function.
+            InvalidKeyError: If `nulls` is not `"first"` or `"last"`.
+
+        """
+        if not isinstance(definition, list):
+            msg = f"Invalid ordering at $: expected a list, received {definition!r}"
+
+            raise InvalidOrderingDefinitionError(msg)
+
+        orderings = [
+            self._compile_key(item, index_path("$", index))
+            for index, item in enumerate(cast("list[Any]", definition))
+        ]
+
+        return Ordering(tuple(k for ordering in orderings for k in ordering.keys))
+
+    def _compile_key(self, item: Any, path: str) -> Ordering[T]:
+        _check_shape(item, path)
+
+        with located(key_path(path, "name"), PyorderingError):
+            if (factory := self._keys.get(item["name"])) is None:
+                raise KeyDoesNotExistError(item["name"], self._keys)
+
+        with located(path, PyorderingError):
+            ordering = factory(*item.get("args", []), **item.get("kwargs", {}))
+
+        if item.get("descending", False):
+            ordering = ~ordering
+
+        with located(key_path(path, "nulls"), PyorderingError):
+            return ordering.nulls(item.get("nulls", "last"))
+
+
+# ---
+
+
+_TYPES: dict[str, tuple[type, str]] = {
+    "name": (str, "a string"),
+    "args": (list, "a list"),
+    "kwargs": (dict, "an object"),
+    "descending": (bool, "a boolean"),
+}
+
+
+def _check_shape(item: Any, path: str) -> None:
+    if not isinstance(item, Mapping):
+        msg = f"Invalid ordering at {path}: expected an object, received {item!r}"
+
+        raise InvalidOrderingDefinitionError(msg)
+
+    mapping = cast("Mapping[str, Any]", item)
+
+    keys = set(mapping)
+
+    if "name" not in keys:
+        msg = f"Invalid ordering at {path}: missing 'name'"
+
+        raise InvalidOrderingDefinitionError(msg)
+
+    if unknown := sorted(keys - _ALLOWED_KEYS):
+        msg = (
+            f"Invalid ordering at {path}: unknown {', '.join(map(repr, unknown))}. "
+            f"Allowed keys: {', '.join(sorted(_ALLOWED_KEYS))}"
+        )
+
+        raise InvalidOrderingDefinitionError(msg)
+
+    for field, (expected, label) in _TYPES.items():
+        if field in keys and not isinstance(value := mapping[field], expected):
+            msg = f"Invalid ordering at {path}.{field}: expected {label}, received {value!r}"
+
+            raise InvalidOrderingDefinitionError(msg)

pyordering/exceptions.py

@@ -0,0 +1,56 @@
+"""Exceptions raised by pyordering.
+
+Every error is raised while an ordering is *built* (from Python or from JSON),
+never while it sorts. Compiler errors carry a note with their JSON path, e.g.
+`at $[1].name`.
+"""
+
+from collections.abc import Iterable
+
+from pyvocabulary import InvalidNameError, NameAlreadyRegisteredError, NameDoesNotExistError
+
+
+class PyorderingError(Exception):
+    """Base class for every exception raised by pyordering."""
+
+
+class InvalidKeyError(PyorderingError, ValueError):
+    """Raised when a key function or a key option (such as `nulls`) is invalid."""
+
+
+class KeyArgumentError(PyorderingError, TypeError):
+    """Raised when a key factory is called with arguments its function does not accept."""
+
+
+class InvalidOrderingDefinitionError(PyorderingError, ValueError):
+    """Raised when a JSON ordering definition does not have the expected shape."""
+
+
+class KeyDoesNotExistError(PyorderingError, NameDoesNotExistError):
+    """Raised when a key name is not in the registry.
+
+    Example:
+    ```python
+    >>> str(KeyDoesNotExistError("rating", ["price", "name"]))
+    "Key 'rating' does not exist. Available keys: price, name"
+
+    ```
+
+    """
+
+    def __init__(self, name: str, available: Iterable[str], /) -> None:
+        super().__init__(name, available, kind="key")
+
+
+class KeyAlreadyRegisteredError(PyorderingError, NameAlreadyRegisteredError):
+    """Raised when a key name is registered twice."""
+
+    def __init__(self, name: str, /) -> None:
+        super().__init__(name, kind="key")
+
+
+class InvalidKeyNameError(PyorderingError, InvalidNameError):
+    """Raised when a key name is not a valid ASCII Python identifier."""
+
+    def __init__(self, name: object, /) -> None:
+        super().__init__(name, kind="key")

pyordering/json_schema.py

@@ -0,0 +1,49 @@
+"""The JSON Schema of an ordering definition, as accepted by `OrderingCompiler.compile`.
+
+It is generated from the registered key signatures, so it can be handed to a
+form builder, an API spec, or an LLM that writes sort orders as JSON.
+"""
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from pyvocabulary import JSON_SCHEMA_DIALECT, call_json_schema, json_schema_of
+
+from .ordering import Nulls
+
+_OPTIONS = {
+    "descending": {"type": "boolean", "default": False},
+    "nulls": {**json_schema_of(Nulls), "default": "last"},
+}
+
+
+def get_ordering_json_schema(keys: Mapping[str, Callable[..., Any]], /) -> dict[str, Any]:
+    """Return the JSON Schema of a list of key objects. Pass `registry.keys`.
+
+    Example:
+    ```python
+    >>> from pyordering import key
+    >>> @key
+    ... def length(word: str) -> int:
+    ...     '''By number of characters.'''
+    ...     return len(word)
+    >>> schema = get_ordering_json_schema({"length": length})
+    >>> item = schema["items"]["oneOf"][0]
+    >>> schema["type"], item["properties"]["name"], item["description"]
+    ('array', {'const': 'length'}, 'By number of characters.')
+    >>> item["properties"]["nulls"]
+    {'enum': ['first', 'last'], 'type': 'string', 'default': 'last'}
+
+    ```
+
+    """
+    return {
+        "$schema": JSON_SCHEMA_DIALECT,
+        "type": "array",
+        "items": {
+            "oneOf": [
+                call_json_schema(name, factory, extra_properties=_OPTIONS)
+                for name, factory in keys.items()
+            ]
+        },
+    }

pyordering/ordering.py

@@ -0,0 +1,247 @@
+"""Sort orders as values: `~stars() >> price() >> name()`.
+
+A *key function* takes the subject first, then its own arguments, and returns
+what to sort by. `@key` turns it into a *key factory*: calling the factory binds
+the arguments and returns a one-key `Ordering`, ready to compose.
+
+```python
+@key
+def price(product: Product) -> Decimal:
+    return product.price
+
+ordering = ~stars() >> price()  # stars descending, then price ascending
+ordering(products)  # a new, sorted list
+```
+
+The same key function works for ORMs when the subject is the model class:
+`price(Product)` returns the `Product.price` column, and `Ordering.clauses`
+hands it to a render function that builds the `order_by` clause.
+"""
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, replace
+from functools import reduce, wraps
+from inspect import Parameter, Signature, signature
+from operator import itemgetter
+from typing import Any, Concatenate, Literal, cast, get_args
+
+from .exceptions import InvalidKeyError, KeyArgumentError
+
+type Nulls = Literal["first", "last"]
+type KeyFn[T, **P] = Callable[Concatenate[T, P], Any]
+type KeyFactory[T, **P] = Callable[P, Ordering[T]]
+type Render[C] = Callable[[Any, bool, Nulls], C | tuple[C, ...]]
+
+NULLS: tuple[Nulls, ...] = get_args(Nulls.__value__)
+
+
+@dataclass(frozen=True, slots=True)
+class Key[T]:
+    """One sort key: what to sort by, the direction, and where `None` values go."""
+
+    name: str
+    value: Callable[[T], Any]
+    descending: bool = False
+    nulls: Nulls = "last"
+
+    def __post_init__(self) -> None:
+        if self.nulls not in NULLS:
+            msg = f"Invalid nulls {self.nulls!r}. Valid values: {', '.join(NULLS)}"
+
+            raise InvalidKeyError(msg)
+
+    def __str__(self) -> str:
+        direction = "~" if self.descending else ""
+
+        nulls = " nulls first" if self.nulls == "first" else ""
+
+        return f"{direction}{self.name}{nulls}"
+
+
+@dataclass(frozen=True, slots=True)
+class Ordering[T]:
+    """Keys applied left to right. Calling it returns a new sorted list.
+
+    Each key is a stable sort pass, run from the last key to the first, so
+    directions can be mixed for any comparable type, strings and dates included.
+
+    Example:
+    ```python
+    >>> @key
+    ... def length(word: str) -> int:
+    ...     return len(word)
+    >>> @key
+    ... def alphabetical(word: str) -> str:
+    ...     return word
+    >>> ordering = ~length() >> alphabetical()
+    >>> ordering
+    Ordering(~length >> alphabetical)
+    >>> ordering(["fig", "apple", "kiwi", "plum", "date"])
+    ['apple', 'date', 'kiwi', 'plum', 'fig']
+    >>> (~ordering)(["fig", "apple", "kiwi", "plum", "date"])
+    ['fig', 'plum', 'kiwi', 'date', 'apple']
+
+    ```
+
+    """
+
+    keys: tuple[Key[T], ...]
+
+    def __call__(self, items: Iterable[T], /) -> list[T]:
+        return reduce(_sort_by, reversed(self.keys), list(items))
+
+    def __rshift__(self, other: "Ordering[T]", /) -> "Ordering[T]":
+        match other:
+            case Ordering(keys=keys):
+                return Ordering((*self.keys, *keys))
+            case _:
+                return NotImplemented
+
+    def __invert__(self) -> "Ordering[T]":
+        # `nulls` is kept: whoever set it chose where nulls go on purpose.
+        return Ordering(tuple(replace(k, descending=not k.descending) for k in self.keys))
+
+    def nulls(self, where: Nulls, /) -> "Ordering[T]":
+        """Return a copy where `None` values of every key sort `"first"` or `"last"`.
+
+        Example:
+        ```python
+        >>> @key
+        ... def rank(item: dict[str, int | None]) -> int | None:
+        ...     return item["rank"]
+        >>> items = [{"rank": 2}, {"rank": None}, {"rank": 1}]
+        >>> rank()(items)
+        [{'rank': 1}, {'rank': 2}, {'rank': None}]
+        >>> rank().nulls("first")(items)
+        [{'rank': None}, {'rank': 1}, {'rank': 2}]
+
+        ```
+
+        """
+        return Ordering(tuple(replace(k, nulls=where) for k in self.keys))
+
+    def clauses[C](self, subject: object, render: Render[C], /) -> tuple[C, ...]:
+        """Return ORM `order_by` clauses, one or more per key.
+
+        Each key function is called with `subject` (usually the model class, so
+        it returns a column) and the result goes to `render(expression,
+        descending, nulls)`. A tuple returned by `render` is flattened, for
+        databases without `NULLS FIRST/LAST` that need two clauses per key.
+
+        Example:
+        ```python
+        >>> class Table:
+        ...     name = "name_column"
+        >>> @key
+        ... def name(subject) -> str:
+        ...     return subject.name
+        >>> render = lambda column, descending, nulls: f"{column} {'DESC' if descending else 'ASC'}"
+        >>> (~name()).clauses(Table, render)
+        ('name_column DESC',)
+
+        ```
+
+        """
+        rendered = [
+            # The key function is typed for instances; here it is given the model class.
+            render(cast("Callable[[object], Any]", k.value)(subject), k.descending, k.nulls)
+            for k in self.keys
+        ]
+
+        return tuple(
+            clause
+            for item in rendered
+            for clause in (cast("tuple[C, ...]", item) if isinstance(item, tuple) else (item,))
+        )
+
+    def __repr__(self) -> str:
+        return f"Ordering({' >> '.join(map(str, self.keys))})"
+
+
+def key[T, **P](fn: KeyFn[T, P], /, *, name: str | None = None) -> KeyFactory[T, P]:
+    """Turn a `(subject, *args, **kwargs) -> sort value` function into a key factory.
+
+    Arguments are checked against the function signature when the factory is
+    called, so a mistake fails while the ordering is built, not while it sorts.
+
+    Args:
+        fn: The key function; its first positional parameter receives the subject.
+        name: The key name shown in `repr`; defaults to the function name.
+
+    Raises:
+        InvalidKeyError: If `fn` does not accept the subject positionally.
+        KeyArgumentError: Raised by the factory for arguments `fn` does not accept.
+
+    Example:
+    ```python
+    >>> @key
+    ... def distance(n: int, target: int) -> int:
+    ...     return abs(n - target)
+    >>> distance(10)([3, 12, 9, 20])
+    [9, 12, 3, 20]
+    >>> distance()
+    Traceback (most recent call last):
+    ...
+    pyordering.exceptions.KeyArgumentError: Key 'distance' got invalid arguments: missing ...
+
+    ```
+
+    """
+    key_name = name or getattr(fn, "__name__", repr(fn))
+
+    arguments = _arguments_signature(fn, key_name)
+
+    @wraps(fn)
+    def factory(*args: P.args, **kwargs: P.kwargs) -> Ordering[T]:
+        try:
+            bound = arguments.bind(*args, **kwargs)
+        except TypeError as error:
+            msg = f"Key '{key_name}' got invalid arguments: {error}"
+
+            raise KeyArgumentError(msg) from error
+
+        return Ordering((Key(key_name, lambda subject: fn(subject, *bound.args, **bound.kwargs)),))
+
+    factory.__signature__ = arguments  # type: ignore[attr-defined]
+
+    return factory
+
+
+# ---
+
+
+def _sort_by[T](items: list[T], key: Key[T]) -> list[T]:
+    # Nulls are split off first: `None` does not compare with other values.
+    pairs = [(key.value(item), item) for item in items]
+
+    present = sorted(
+        (pair for pair in pairs if pair[0] is not None),
+        key=itemgetter(0),
+        reverse=key.descending,  # `reverse` keeps the sort stable
+    )
+
+    ordered = [item for _, item in present]
+
+    missing = [item for value, item in pairs if value is None]
+
+    return [*missing, *ordered] if key.nulls == "first" else [*ordered, *missing]
+
+
+def _arguments_signature(fn: Callable[..., Any], name: str) -> Signature:
+    """Return the signature of `fn` without its leading subject parameter."""
+    try:
+        subject, *parameters = signature(fn).parameters.values()
+    except ValueError as error:
+        msg = f"Key '{name}' must accept the subject as its first positional parameter"
+
+        raise InvalidKeyError(msg) from error
+
+    if subject.kind not in (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD):
+        msg = (
+            f"Key '{name}' must accept the subject as its first positional parameter, "
+            f"got {subject.kind.description} parameter '{subject.name}'"
+        )
+
+        raise InvalidKeyError(msg)
+
+    return Signature(parameters)

pyordering/registry.py

@@ -0,0 +1,104 @@
+"""A registry of named keys: the whitelist of fields a JSON ordering may sort by."""
+
+from collections.abc import Callable, Iterator, Mapping
+from types import MappingProxyType
+
+from pyvocabulary import Vocabulary
+
+from .exceptions import InvalidKeyNameError, KeyAlreadyRegisteredError, KeyDoesNotExistError
+from .ordering import KeyFactory, KeyFn, key
+
+
+class OrderingRegistry[T]:
+    """Collect named keys for subjects of type `T`.
+
+    Its visible keys are what an `OrderingCompiler` accepts and what
+    `get_ordering_json_schema` describes; anything else fails at compile time.
+    Hidden keys stay usable from Python but are invisible to both.
+
+    Example:
+    ```python
+    >>> registry = OrderingRegistry[dict[str, int]]()
+    >>> @registry.key()
+    ... def price(item: dict[str, int]) -> int:
+    ...     return item["price"]
+    >>> list(registry.keys)
+    ['price']
+    >>> (~registry["price"]())([{"price": 1}, {"price": 3}])
+    [{'price': 3}, {'price': 1}]
+
+    ```
+
+    """
+
+    __slots__ = ("_keys",)
+
+    def __init__(self) -> None:
+        self._keys: Vocabulary[KeyFactory[T, ...]] = Vocabulary(
+            "key",
+            does_not_exist=KeyDoesNotExistError,
+            already_registered=KeyAlreadyRegisteredError,
+            invalid_name=InvalidKeyNameError,
+        )
+
+    @property
+    def keys(self) -> Mapping[str, KeyFactory[T, ...]]:
+        """A read-only mapping of every visible key factory, by name."""
+        return MappingProxyType(dict(self._keys))
+
+    def __getitem__(self, name: str, /) -> KeyFactory[T, ...]:
+        return self._keys[name]
+
+    def __contains__(self, name: object, /) -> bool:
+        return name in self._keys
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._keys)
+
+    def __len__(self) -> int:
+        return len(self._keys)
+
+    def key[**P](
+        self,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        hidden: bool = False,
+    ) -> Callable[[KeyFn[T, P]], KeyFactory[T, P]]:
+        """Return a decorator registering a key function. See `register`."""
+
+        def decorator(fn: KeyFn[T, P]) -> KeyFactory[T, P]:
+            return self.register(fn, name=name, description=description, hidden=hidden)
+
+        return decorator
+
+    def register[**P](
+        self,
+        fn: KeyFn[T, P],
+        /,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        hidden: bool = False,
+    ) -> KeyFactory[T, P]:
+        """Register `fn` as a key and return its factory.
+
+        Args:
+            fn: The key function; its first positional parameter receives the subject.
+            name: The key name used in JSON and `repr`; defaults to the function name.
+            description: Overrides the function docstring (shown in the JSON Schema).
+            hidden: Keep the key out of lookups, the compiler and the JSON Schema.
+
+        Raises:
+            InvalidKeyNameError: If the name is not a valid Python identifier.
+            KeyAlreadyRegisteredError: If the name is taken.
+            InvalidKeyError: If `fn` does not accept the subject positionally.
+
+        """
+        key_name = name or getattr(fn, "__name__", "")
+
+        factory = key(fn, name=key_name)
+
+        factory.__doc__ = description or fn.__doc__
+
+        return self._keys.add(key_name, factory, hidden=hidden)

pyordering-0.1.2.dist-info/METADATA

@@ -0,0 +1,566 @@
+Metadata-Version: 2.4
+Name: pyordering
+Version: 0.1.2
+Summary: Sort orders as composable values: stars(descending=True) >> price(), definable as JSON.
+Keywords: sorting,ordering,order-by,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/pyordering
+Project-URL: Repository, https://github.com/aaltatan/pyordering
+Project-URL: Issues, https://github.com/aaltatan/pyordering/issues
+Description-Content-Type: text/markdown
+
+# pyordering
+
+Sort orders as composable values. `~stars() >> price() >> name()` is an `Ordering`: keys
+applied left to right that sort lists in memory, compile from JSON, and render to
+SQLAlchemy or Django `order_by` clauses.
+
+```python
+best_first = ~stars() >> price() >> name()
+
+best_first(products)  # a new sorted list
+
+select(Product).order_by(*best_first.clauses(Product, render))  # SQLAlchemy
+
+Product.objects.order_by(*best_first.clauses(Product, render))  # Django
+
+compiler.compile([{"name": "stars", "descending": True}, {"name": "price"}])  # from JSON
+```
+
+| Piece | What it does |
+| --- | --- |
+| [`key`](#quick-start) | Turns a `(subject, ...) -> sort value` function into a factory of one-key orderings |
+| [`Ordering`](#composing-orderings) | Callable: returns a new sorted list. Composes with `>>`, flips with `~`, sets `nulls` |
+| [`OrderingRegistry`](#a-registry-is-the-whitelist) | The named keys a JSON ordering may use, and nothing else |
+| [`OrderingCompiler`](#from-json) | Builds an `Ordering` from JSON, with errors that point at the JSON path |
+| [`get_ordering_json_schema`](#json-schema) | The JSON Schema of that JSON, generated from the key signatures |
+| [`Ordering.clauses`](#sqlalchemy) | ORM `order_by` clauses through a render function you choose; no ORM is imported |
+
+It is part of a family of packages that wrap a callable in an immutable value with an
+algebra: [pyspecification](https://github.com/aaltatan/pyspecification) (`T -> bool`),
+[pyformula](https://github.com/aaltatan/pyformula) (`T -> number`),
+[pyflowstep](https://github.com/aaltatan/pyflowstep) (`T -> T`), and pyordering (`T -> sort key`).
+
+## Installation
+
+```bash
+pip install pyordering
+```
+
+or with uv:
+
+```bash
+uv add pyordering
+```
+
+Python 3.12+. The only runtime dependency is
+[pyvocabulary](https://github.com/aaltatan/pyvocabulary). SQLAlchemy and Django are optional:
+pyordering never imports them.
+
+## Quick start
+
+The examples build on each other. A comment under a line shows its result.
+
+A *key function* takes the subject and returns what to sort by. `@key` turns it into a factory:
+calling the factory returns a one-key `Ordering`.
+
+```python
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from pyordering import key
+
+
+@dataclass(frozen=True)
+class Product:
+    id: int
+    name: str
+    price: Decimal
+    stars: int | None
+    released: date
+
+
+products = [
+    Product(1, "kettle", Decimal("30.00"), 4, date(2024, 3, 1)),
+    Product(2, "toaster", Decimal("25.00"), None, date(2023, 6, 1)),
+    Product(3, "blender", Decimal("30.00"), 5, date(2025, 1, 1)),
+    Product(4, "mixer", Decimal("25.00"), 4, date(2022, 9, 1)),
+    Product(5, "grill", Decimal("80.00"), None, date(2025, 5, 1)),
+]
+
+
+@key
+def price(product: Product) -> Decimal:
+    return product.price
+
+
+@key
+def name(product: Product) -> str:
+    return product.name
+
+
+by_price = price() >> name()
+
+by_price
+# Ordering(price >> name)
+
+[p.name for p in by_price(products)]
+# ['mixer', 'toaster', 'blender', 'kettle', 'grill']
+```
+
+Calling an ordering never changes its input: it takes any iterable and returns a new list.
+
+## Composing orderings
+
+`>>` appends keys: later keys break ties left by earlier ones. `~` flips the direction of every
+key. Directions can be mixed freely, for strings and dates too, because each key is a separate
+stable sort pass, run from the last key to the first.
+
+```python
+@key
+def released(product: Product) -> date:
+    return product.released
+
+
+newest = ~released()
+
+[p.name for p in newest(products)]
+# ['grill', 'blender', 'kettle', 'toaster', 'mixer']
+
+expensive_then_alphabetical = ~price() >> name()
+
+[p.name for p in expensive_then_alphabetical(products)]
+# ['grill', 'blender', 'kettle', 'mixer', 'toaster']
+
+~expensive_then_alphabetical
+# Ordering(price >> ~name)
+```
+
+Orderings are frozen dataclasses: every operator returns a new value, so a base ordering can be
+shared and extended safely.
+
+### Nulls
+
+`None` values do not compare with anything, so each key decides where they go: `"last"` by
+default, in both directions, or `"first"`. `~` keeps that choice, because whoever set it chose
+where nulls go on purpose.
+
+```python
+@key
+def stars(product: Product) -> int | None:
+    return product.stars
+
+
+[(p.name, p.stars) for p in (~stars() >> name())(products)]
+# [('blender', 5), ('kettle', 4), ('mixer', 4), ('grill', None), ('toaster', None)]
+
+unrated_first = stars().nulls("first") >> name()
+
+unrated_first
+# Ordering(stars nulls first >> name)
+
+[(p.name, p.stars) for p in unrated_first(products)]
+# [('grill', None), ('toaster', None), ('kettle', 4), ('mixer', 4), ('blender', 5)]
+
+~unrated_first
+# Ordering(~stars nulls first >> ~name)
+```
+
+`nulls()` applies to every key of the ordering it is called on, so call it on the single key
+you mean, before composing. An invalid value fails right away:
+
+```python
+stars().nulls("middle")
+# raises InvalidKeyError: Invalid nulls 'middle'. Valid values: first, last
+```
+
+### Keys with arguments
+
+Parameters after the subject become arguments of the factory. They are bound when the ordering
+is built, so a wrong argument fails then, not halfway through a sort.
+
+```python
+@key
+def closest_to(product: Product, budget: int, *, penalty_over: int = 1) -> Decimal:
+    """Sort by distance from a budget; going over it can cost more."""
+    difference = product.price - budget
+
+    return difference * penalty_over if difference > 0 else -difference
+
+
+[p.name for p in (closest_to(28, penalty_over=3) >> name())(products)]
+# ['mixer', 'toaster', 'blender', 'kettle', 'grill']
+
+closest_to(budget="28", unknown=1)
+# raises KeyArgumentError: Key 'closest_to' got invalid arguments: got an unexpected keyword argument 'unknown'
+```
+
+### Pagination needs a unique last key
+
+Pages are only stable when no two rows tie on the whole ordering. Otherwise the database (or
+the input order) decides ties, and rows can repeat or vanish between pages. End every paginated
+ordering with a unique key, usually the id:
+
+```python
+@key
+def product_id(product: Product) -> int:
+    return product.id
+
+
+paginated = ~stars() >> price() >> product_id()
+
+pages = [paginated(products)[start : start + 2] for start in (0, 2, 4)]
+
+[[p.id for p in page] for page in pages]
+# [[3, 4], [1, 2], [5]]
+```
+
+## A registry is the whitelist
+
+An `OrderingRegistry` collects named keys. Its visible keys are exactly what the compiler and the
+JSON Schema accept, so a client can never sort by a field you did not register.
+
+```python
+from pyordering import OrderingRegistry
+
+registry = OrderingRegistry[Product]()
+
+for function in (price, name, stars, released):
+    registry.register(function.__wrapped__)
+
+
+@registry.key(name="id")
+def product_id(product: Product) -> int:
+    """The unique tie-breaker for pagination."""
+    return product.id
+
+
+registry.register(closest_to.__wrapped__)
+
+list(registry)
+# ['price', 'name', 'stars', 'released', 'id', 'closest_to']
+
+registry["stars"]() >> registry["id"]()
+# Ordering(stars >> id)
+```
+
+`@registry.key()` takes `name`, `description` (overrides the docstring in the JSON Schema) and
+`hidden=True` (usable from Python, invisible to the compiler and the schema). Names must be
+Python identifiers, and each one can be registered once:
+
+```python
+registry["rating"]
+# raises KeyDoesNotExistError: Key 'rating' does not exist. Available keys: price, name, stars, released, id, closest_to
+```
+
+## From JSON
+
+A JSON ordering is a list of key objects: `name`, and optionally `descending`, `nulls`, `args`
+and `kwargs`.
+
+```python
+from pyordering import OrderingCompiler
+
+compiler = OrderingCompiler(registry.keys)
+
+ordering = compiler.compile(
+    [
+        {"name": "stars", "descending": True, "nulls": "first"},
+        {"name": "closest_to", "args": [28], "kwargs": {"penalty_over": 3}},
+        {"name": "id"},
+    ]
+)
+
+ordering
+# Ordering(~stars nulls first >> closest_to >> id)
+
+[p.name for p in ordering(products)]
+# ['toaster', 'grill', 'blender', 'mixer', 'kettle']
+```
+
+Every problem is reported while compiling, before anything is sorted. The error keeps its type
+and gets a note with the JSON path:
+
+```python
+compiler.compile([{"name": "price"}, {"name": "rating"}])
+# raises KeyDoesNotExistError: Key 'rating' does not exist. Available keys: price, name, stars, released, id, closest_to
+# at $[1].name
+
+compiler.compile([{"name": "price", "direction": "desc"}])
+# raises InvalidOrderingDefinitionError: Invalid ordering at $[0]: unknown 'direction'. Allowed keys: args, descending, kwargs, name, nulls
+
+compiler.compile([{"name": "closest_to"}])
+# raises KeyArgumentError: Key 'closest_to' got invalid arguments: missing a required argument: 'budget'
+# at $[0]
+```
+
+All of them derive from `PyorderingError`.
+
+### A `?sort=` query parameter
+
+pyordering does not parse query strings, but a common shape (`?sort=-stars,price`) maps onto the
+JSON in one comprehension, and the registry still decides what is allowed:
+
+```python
+def parse_sort(value: str) -> list[dict[str, object]]:
+    return [
+        {"name": field.removeprefix("-"), "descending": field.startswith("-")}
+        for field in value.split(",")
+        if field
+    ]
+
+
+compiler.compile(parse_sort("-stars,price") + [{"name": "id"}])
+# Ordering(~stars >> price >> id)
+```
+
+## JSON Schema
+
+`get_ordering_json_schema` describes exactly what the compiler accepts, generated from the key
+signatures and docstrings. Hand it to a form builder, an OpenAPI spec, or an LLM that writes sort
+orders.
+
+```python
+from pyordering import get_ordering_json_schema
+
+schema = get_ordering_json_schema(registry.keys)
+
+schema["type"], [item["properties"]["name"]["const"] for item in schema["items"]["oneOf"]]
+# ('array', ['price', 'name', 'stars', 'released', 'id', 'closest_to'])
+
+closest = schema["items"]["oneOf"][-1]
+
+closest["description"]
+# 'Sort by distance from a budget; going over it can cost more.'
+
+closest["properties"]["args"]["prefixItems"]
+# [{'type': 'integer'}]
+
+closest["properties"]["kwargs"]["properties"]
+# {'budget': {'type': 'integer'}, 'penalty_over': {'type': 'integer', 'default': 1}}
+
+closest["properties"]["descending"], closest["properties"]["nulls"]
+# ({'type': 'boolean', 'default': False}, {'enum': ['first', 'last'], 'type': 'string', 'default': 'last'})
+```
+
+## SQLAlchemy
+
+`ordering.clauses(subject, render)` calls each key function with `subject` and passes the result
+to `render(expression, descending, nulls)`. With the model *class* as the subject, a key like
+`product.price` returns the `Product.price` column, so **the same registry sorts dataclasses,
+loaded rows, and SQL queries**. pyordering imports no ORM; the render function is yours.
+
+```python
+from sqlalchemy import Date, Numeric, String, create_engine, select
+from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class ProductRow(Base):
+    __tablename__ = "products"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(50))
+    price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
+    stars: Mapped[int | None]
+    released: Mapped[date] = mapped_column(Date)
+
+
+def sqlalchemy_render(column, descending, nulls):
+    clause = column.desc() if descending else column.asc()
+
+    return clause.nulls_first() if nulls == "first" else clause.nulls_last()
+
+
+engine = create_engine("sqlite://")
+
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add_all(ProductRow(**vars(p)) for p in products)
+
+    session.commit()
+
+best_first = compiler.compile(
+    [{"name": "stars", "descending": True}, {"name": "price"}, {"name": "id"}]
+)
+
+query = select(ProductRow).order_by(*best_first.clauses(ProductRow, sqlalchemy_render))
+
+print(query)
+# SELECT products.id, products.name, products.price, products.stars, products.released
+# FROM products ORDER BY products.stars DESC NULLS LAST, products.price ASC NULLS LAST, products.id ASC NULLS LAST
+
+with Session(engine) as session:
+    rows = session.scalars(query).all()
+
+[row.name for row in rows]
+# ['blender', 'mixer', 'kettle', 'toaster', 'grill']
+```
+
+The database and memory agree, and the same ordering sorts the loaded rows too:
+
+```python
+[row.name for row in best_first(rows)] == [p.name for p in best_first(products)] == [
+    row.name for row in rows
+]
+# True
+```
+
+A key can return any column expression, such as `func.lower(subject.name)`, as long as the
+expression also works on an instance when you sort in memory, or you only use it for queries.
+
+### MySQL
+
+MySQL has no `NULLS FIRST/LAST`. It sorts `NULL` as the smallest value, so the render function
+returns two clauses per key, the first one sorting by "is null", and `clauses` flattens them:
+
+```python
+from sqlalchemy.dialects import mysql
+
+
+def mysql_render(column, descending, nulls):
+    is_null = column.is_(None) if nulls == "last" else column.is_not(None)
+
+    return is_null, column.desc() if descending else column.asc()
+
+
+query = select(ProductRow.id).order_by(*best_first.clauses(ProductRow, mysql_render))
+
+print(query.compile(dialect=mysql.dialect()))
+# SELECT products.id
+# FROM products ORDER BY products.stars IS NULL, products.stars DESC, products.price IS NULL, products.price ASC, products.id IS NULL, products.id ASC
+```
+
+## Django
+
+The same idea with Django: on the model class, `product.price` is a field descriptor, which the
+render function turns into an `F` expression. Expressions you return yourself, like
+`Lower("name")`, pass through unchanged.
+
+The settings and table creation below stand in for a Django project, so the example runs on its
+own. In a project, the model lives in your app's `models.py`.
+
+```python
+import django
+from django.conf import settings
+
+settings.configure(
+    DATABASES={"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}},
+)
+
+django.setup()
+
+from django.db import connection, models
+
+
+class ProductModel(models.Model):
+    name = models.CharField(max_length=50)
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    stars = models.IntegerField(null=True)
+    released = models.DateField()
+
+    class Meta:
+        app_label = "shop"
+
+
+with connection.schema_editor() as editor:
+    editor.create_model(ProductModel)
+
+ProductModel.objects.bulk_create(ProductModel(**vars(p)) for p in products)
+```
+
+The render function:
+
+```python
+from django.db.models import F
+from django.db.models.query_utils import DeferredAttribute
+
+
+def django_render(expression, descending, nulls):
+    if isinstance(expression, DeferredAttribute):  # `Product.price` on the class
+        expression = F(expression.field.name)
+
+    order = expression.desc if descending else expression.asc
+
+    return order(nulls_first=nulls == "first" or None, nulls_last=nulls == "last" or None)
+
+
+unrated_first = compiler.compile([{"name": "stars", "nulls": "first"}, {"name": "id"}])
+
+queryset = ProductModel.objects.order_by(*unrated_first.clauses(ProductModel, django_render))
+
+print(queryset.query)
+# SELECT ... FROM "shop_productmodel" ORDER BY "shop_productmodel"."stars" ASC NULLS FIRST, "shop_productmodel"."id" ASC NULLS LAST
+
+[product.name for product in queryset]
+# ['toaster', 'grill', 'kettle', 'mixer', 'blender']
+
+[p.name for p in unrated_first(products)]
+# ['toaster', 'grill', 'kettle', 'mixer', 'blender']
+```
+
+Django emulates `NULLS FIRST/LAST` on MySQL by itself, so this render function works there
+unchanged.
+
+In a view, the whitelist and the JSON paths do the validation:
+
+```python
+from django.http import HttpRequest, JsonResponse
+
+from pyordering import PyorderingError
+
+
+def products(request: HttpRequest) -> JsonResponse:
+    try:
+        ordering = compiler.compile(parse_sort(request.GET.get("sort", "")) + [{"name": "id"}])
+    except PyorderingError as error:
+        return JsonResponse(
+            {"error": str(error), "notes": getattr(error, "__notes__", [])}, status=400
+        )
+
+    queryset = ProductModel.objects.order_by(*ordering.clauses(ProductModel, django_render))
+
+    return JsonResponse({"products": list(queryset.values("id", "name"))})
+```
+
+## Reference
+
+```python
+Ordering(keys: tuple[Key[T], ...])
+    ordering(items)                  # -> list[T], a new sorted list
+    ordering >> other                # -> Ordering[T], keys of both
+    ~ordering                        # -> Ordering[T], every direction flipped, nulls kept
+    ordering.nulls("first" | "last") # -> Ordering[T], nulls set on every key
+    ordering.clauses(subject, render) # -> tuple of clauses; render(expression, descending, nulls)
+
+Key(name, value, descending=False, nulls="last")
+
+key(fn, /, *, name=None)            # -> factory(*args, **kwargs) -> Ordering[T]
+OrderingRegistry[T]()               # .key(name=, description=, hidden=), .register(fn, ...), .keys
+OrderingCompiler(keys).compile([...])
+get_ordering_json_schema(keys)
+```
+
+Exceptions, all subclasses of `PyorderingError`: `InvalidKeyError` (bad key function or `nulls`),
+`KeyArgumentError` (arguments the key function does not accept), `InvalidOrderingDefinitionError`
+(wrong JSON shape), `KeyDoesNotExistError`, `KeyAlreadyRegisteredError`, `InvalidKeyNameError`.
+
+## License
+
+GPL-3.0-only.

pyordering-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyordering/__init__.py,sha256=qYV5m7yDJQj6KYCHlWC-HvBxnUFTguLrsU0gIUz8KHQ,1060
+pyordering/compilers.py,sha256=TCe7VXSOLAPFiQzLR_BQiybbtVPXsdSZ8KzgCxeF598,4642
+pyordering/exceptions.py,sha256=dW8HHD-9l2Qv75DLEwsOGx3j1LSD13ux7iT3jG72Wxg,1756
+pyordering/json_schema.py,sha256=xFzI-hH8NhelUgENSPI4MQaOvWOUQcrbpMZXWjpF8SQ,1597
+pyordering/ordering.py,sha256=wX5KaP5V1cODZ3sKNShA6IcgtQHykmXBRoIMAexrZjQ,8526
+pyordering/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyordering/registry.py,sha256=GwAr-YMImu7DwxkTf6h5wQyr5Uxz2hq-gvkuaVukNTs,3463
+pyordering-0.1.2.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+pyordering-0.1.2.dist-info/METADATA,sha256=Zh_As5HkN-m9zOMFjXun9o-F2TJmCuY-G5lgfd8Q4ZE,18740
+pyordering-0.1.2.dist-info/RECORD,,

pyordering-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