pyordering 0.1.2__tar.gz

pyordering-0.1.2/PKG-INFO

@@ -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.