querymodelling 0.0.17__tar.gz → 0.0.18__tar.gz

querymodelling-0.0.18/.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: test.py",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/test.py",
+            "cwd": "${workspaceFolder}",
+            "python": "${workspaceFolder}/.venv/bin/python",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            },
+            "console": "integratedTerminal",
+            "justMyCode": false
+        }
+    ]
+}

querymodelling-0.0.18/HISTORY.md

@@ -0,0 +1,64 @@
+Release History
+===============
+
+0.0.13
+----------
+
+-   sql_filter: add typed, nested and generator based SQL filter models
+    (``SqlFilterModel``) with ``and`` / ``or`` / ``not``, typed operators,
+    SQL functions and JSON schema support
+-   sql_query: add typed, generator based SQL query models
+    (``SqlQueryModel``) with ``fields`` (field names, SQL functions,
+    aliases), ``where`` and ``group_by`` incl. typed result models
+-   sql_query: ``group_by`` accepts aliases of ``fields`` and an empty
+    list (no grouping)
+-   sql_query: joins, subqueries (``exists``, ``in``, scalar) and conditions
+    as typed expressions (``{"eq": [a, b]}``), fields are referenced by
+    ``{"model", "field"}``, plain JSON values are constants
+-   sql_query: access rules of models (usage, rows) and fields per user
+    (``SqlModelAccess``, ``SqlFieldAccess``) and query models per user
+    (``SqlQueryFactory``)
+-   sql_query: result models and schemas of validated queries copy the
+    information of the selected fields, functions define their nullability
+    and result field (``Nullability``, ``inherit``, ``describe``)
+
+0.0.12 (2025-10-27)
+
+-   sql: add support for filtering boolean fields
+
+0.0.11 (2025-09-22)
+------------------
+
+-   sql: adding support for query supplements
+
+0.0.8 (2025-03-12)
+------------------
+
+-   redis_om: add support
+
+0.0.6 (2025-03-04)
+------------------
+
+-   sql: remove dot name alias again
+    since they are producing a lot of side effects
+
+0.0.5 (2025-02-28)
+------------------
+
+-   sql: add name field to meta data
+
+0.0.4 (2025-02-11)
+------------------
+
+-   sql: support for enums
+
+0.0.2 (2024-01-15)
+------------------
+
+-   support of dot name alias
+-   use a separate field for each operator
+
+0.0.1 (2024-01-13)
+------------------
+
+-   Birth

{querymodelling-0.0.17 → querymodelling-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querymodelling
-Version: 0.0.17
+Version: 0.0.18
 Summary: build consistent api query models for fastapi
 Author: George Haddad
 Author-email: George Haddad <georgeh87@live.de>
@@ -224,84 +224,236 @@ At least you will need to have the pydantic package installed. Of course it make
 
 ## Example
 
-### Typed SQL filter models
 
-`SqlFilterModel` generates a nested, fully typed filter model (incl. JSON
-schema) from a model and compiles it into a SQLAlchemy where clause.
+### Typed SQL query models
 
-```python
-from sqlmodel import SQLModel, Field, select
-from querymodelling.sql_filter import SqlFilterModel
+`SqlQueryModel` generates a fully typed query model (incl. JSON schema)
+with `joins`, `fields`, `where`, `group_by` and subqueries, which is compiled
+into a SQLAlchemy select statement. Only the registered models can be
+queried.
 
-class ExampleModel(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
-    name: str
-    description: str
+```python
+from sqlmodel import Session
+from querymodelling.sql_query import SqlQueryModel
 
-ExampleFilter = SqlFilterModel(ExampleModel)
+BookQuery = SqlQueryModel(Book, models=[Author, Review])
 
-query = ExampleFilter.model_validate({
-    "and": {
-        "name": {"contains": "wurst", "startswith": "bump"},
-        "description": {"lower": {"contains": "test"}},
-    },
-    "or": [{"id": {"in": [1, 2]}}, {"name": {"length": {"gt": 3}}}],
+query = BookQuery.model_validate({
+    "joins": [
+        {
+            "model": "author",
+            "type": "left",
+            "on": {"eq": [
+                {"model": "book", "field": "author_id"},
+                {"model": "author", "field": "id"}
+            ]}
+        }
+    ],
+    "fields": [
+        {"model": "book", "field": "id"},
+        {"model": "author", "field": "id", "alias": "author_id"},
+        {"lower": {"model": "author", "field": "name"}, "alias": "author_name"}
+    ],
+    "where": {"and": [
+        {"eq": [{"model": "book", "field": "id"}, 123]},
+        {"startswith": [{"model": "author", "field": "name"}, "M"]}
+    ]}
 })
-statement = query.apply_sql(select(ExampleModel))
-# or: select(ExampleModel).where(query.to_sql_expression())
+statement = query.to_select()      # SQLAlchemy select with labeled columns
+rows = query.fetch(session)        # list of typed result rows
+RowModel = query.result_model()    # typed row, without executing the query
+```
+
+```sql
+SELECT book.id AS id, author.id AS author_id, lower(author.name) AS author_name
+FROM book LEFT OUTER JOIN author ON book.author_id = author.id
+WHERE book.id = 123 AND author.name LIKE 'M' || '%'
+```
+
+**One rule:** a plain JSON value (string, number, boolean) is always a
+constant, an object is an expression identified by its keys:
+
+| Object | Expression |
+|---|---|
+| `{"model": "book", "field": "id"}` | field (`"as"` selects a joined instance) |
+| `{"model": "review", "fields": [...], "where": ...}` | subquery (no `field`) |
+| `{"lower": ...}`, `{"eq": [...]}` | function (its only key besides `alias`) |
+| `{"ref": "author_name"}` | alias of `fields` (`group_by` only) |
+
+* **Query**: `model` (defaults to the base model), `as`, `joins`, `fields`
+  (all fields of the queried model if not set), `where`, `group_by`.
+  Subqueries have the same structure.
+* **Joins**: `{"model", "as", "type", "on"}` with `type` `inner` (default),
+  `left` or `full`. `on` may reference the queried model and the previous
+  joins. A model joined twice needs `as`, it is referenced by
+  `{"model": "author", "as": "reviewer", "field": "name"}`. Fields of the
+  outer side of an outer join are `Optional` in the result model.
+* **Conditions** (`where`, `on`) are functions returning `bool`:
+  `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`
+  (`{"in": [x, [1, 2]]}` or `{"in": [x, <subquery>]}`), `contains`,
+  `icontains`, `startswith`, `istartswith`, `endswith`, `iendswith`, `like`,
+  `not_like`, `ilike`, `is_null`, `is_not_null`, `and`, `or`, `not` and
+  `exists` (`{"exists": <subquery>}`).
+* **Functions**: `lower`, `upper`, `trim`, `length`, `concat`, `substring`,
+  `replace`, `abs`, `round`, `ceil`, `floor`, `add`, `sub`, `mul`, `div`,
+  `date`, `year`, `month`, `day`, `hour`, `minute`, `coalesce`, `nullif`,
+  `cast` (`{"cast": [x, "string"]}`) and the aggregates `count`
+  (`{"count": "*"}` counts all rows), `count_distinct`, `sum`, `avg`, `min`,
+  `max`.
+* **Subqueries** used as value or in `in` return exactly one field, its type
+  is the type of the expression. Subqueries may reference the models of the
+  outer queries, inner models shadow outer ones with the same name (use
+  `as`).
+* **Typing**: all expressions are typed per result type, e.g.
+  `{"lower": <int field>}` or `{"eq": [<int field>, "x"]}` are rejected by
+  the JSON schema and the validation.
+* **Grouping**: fields outside of aggregate functions must be part of
+  `group_by`, aggregates must not be nested and are not allowed in `where`,
+  `on` and `group_by`. An empty `group_by` means no grouping.
+* **Limits**: `max_joins` (default 5) per (sub)query and `max_depth`
+  (default 3) of nested subqueries.
+
+```json
+{
+  "joins": [{"model": "author", "type": "left", "on": {"eq": [
+    {"model": "book", "field": "author_id"}, {"model": "author", "field": "id"}
+  ]}}],
+  "fields": [
+    {"lower": {"model": "author", "field": "name"}, "alias": "author_name"},
+    {"count": "*", "alias": "books"},
+    {"model": "review", "fields": [{"avg": {"model": "review", "field": "rating"}}],
+     "where": {"eq": [{"model": "review", "field": "book_id"}, {"model": "book", "field": "id"}]},
+     "alias": "avg_rating"}
+  ],
+  "where": {"exists": {"model": "review", "where": {"eq": [
+    {"model": "review", "field": "book_id"}, {"model": "book", "field": "id"}
+  ]}}},
+  "group_by": [{"ref": "author_name"}, {"model": "book", "field": "id"}]
+}
 ```
 
-* Fields of the filter object are combined with `AND`.
-* `and` / `or` accept an object (its conditions are combined) or a list of
-  objects (each object is combined with `AND`, the list with the operator).
-  `not` negates an object. Everything can be nested.
-* Operators per type (default): `eq`, `ne`, `is_null`, `in`, `not_in`
-  (scalars), `gt`, `gte`, `lt`, `lte`, `between` (numbers, dates, times),
-  `contains`, `icontains`, `startswith`, `istartswith`, `endswith`,
-  `iendswith`, `like`, `not_like`, `ilike` (strings).
-* SQL functions per type (default): `lower`, `upper`, `trim`, `length`
-  (strings), `abs` (numbers), `date`, `year`, `month`, `day`, `hour`,
-  `minute` (dates / times). Functions return a filter of their result type,
-  e.g. `{"name": {"length": {"gt": 3}}}`.
-
-Everything is built from generators and can be extended or restricted:
+Models are registered by their table name (`models=[Author]`) or explicitly
+(`models={"writer": Author}`). `sources` overrides the table of a model,
+`include_fields` / `exclude_fields` restrict the fields (a list for the base
+model or a mapping of model names to lists).
+
+Functions and conditions are provided by generators `(annotation) ->
+Iterable[SqlExpressionFunction]` which are called for every known type:
 
 ```python
-from querymodelling.sql_filter import (
-    SqlOperator, SqlFunction, default_sql_filter_mapping, for_types, without
+from sqlalchemy import Integer, func
+from querymodelling.sql_filter import without
+from querymodelling.sql_query import (
+    Expr, SqlExpressionFunction, default_sql_expression_mapping
 )
 
-def parity(annotation):
-    yield SqlOperator(
-        "even", lambda column, value: (column % 2 == 0) == value,
-        value_type=lambda annotation: bool)
+def instr(annotation):
+    if annotation is str:
+        yield SqlExpressionFunction(
+            "instr", int, (Expr(str), Expr(str)),
+            lambda value, search: func.instr(value, search, type_=Integer()))
 
-mapping = default_sql_filter_mapping(name_prefix="Custom")
-mapping.operator_generators = [
-    without(generator, "like", "ilike")
-    for generator in mapping.operator_generators
+mapping = default_sql_expression_mapping()
+mapping.function_generators = [
+    without(generator, "cast") for generator in mapping.function_generators
 ]
-mapping.add_operators(for_types(parity, int, exclude=(bool,)))
+mapping.add_functions(instr)
 
-ExampleFilter = SqlFilterModel(ExampleModel, mapping=mapping)
+BookQuery = SqlQueryModel(Book, models=[Author], mapping=mapping)
 ```
 
-* operator generators `(annotation) -> Iterable[SqlOperator]`
-* function generators `(annotation) -> Iterable[SqlFunction]`
-* field generators `(context, model, name, field_info, annotation) ->
-  Iterable[SqlFilterField]` (`field_generators=...`, e.g. virtual fields
-  based on SQL expressions)
-* logical generators `(model) -> Iterable[SqlLogicalOperator]`
-  (`logical_generators=...`)
+Argument placeholders are `Expr(*types)` (an expression of the types, any
+type if empty), `Many(type)` (a list or a subquery, see `in`) and `Query()`
+(a subquery, see `exists`). Referenceable fields are provided by reference
+generators (`reference_generators=...`, e.g. virtual fields based on SQL
+expressions).
+
+#### Result schema
 
-The filter can be used within existing query models as well:
+The result of a validated query is known without executing it:
+`query.result_model()` is the typed model of a result row,
+`query.result_schema()` the JSON schema of the result rows
+(`result_schema(many=False)` of a single row).
+
+* Fields copy the information of their source field: type, `title`,
+  `description`, `examples`, `json_schema_extra`, `deprecated` and the
+  constraints (`max_length`, `ge`, ...). They may be `NULL` if their field is
+  optional or on the outer side of an outer join.
+* Constants are of their type and never `NULL`.
+* Functions define their result: `result_type`, `nullable` and
+  `result_field`:
+  * `nullable` (`Nullability`): `PROPAGATE` (default, `NULL` if any argument
+    may be `NULL`), `COALESCE` (if all arguments may be), `ALWAYS` (e.g.
+    `sum`, `avg`, `min`, `max`, `nullif`, `div`) or `NEVER` (e.g. `count`,
+    `is_null`, `exists`), `True` / `False` for always / never.
+  * `result_field`: field information from the arguments, `inherit()` (all
+    of the argument, e.g. `min`, `max`, `nullif`) or `describe()` (only its
+    title and description, e.g. `lower`, `round`, `avg`, `coalesce`).
+    Without a rule the result has no field information.
+* Subqueries are the result of their single field, `NULL` if they may return
+  no row (an aggregate without `group_by` always returns one row).
 
 ```python
-from querymodelling.pydantic import QueryField
-from querymodelling.sql_filter import sql_filter_expression
+SqlExpressionFunction(
+    "initials", str, (Expr(str),), lambda value: func.substr(value, 1, 1),
+    nullable=Nullability.PROPAGATE, result_field=describe(),
+)
+```
+
+#### Access rules
+
+Models and fields can be restricted per access context - any object of the
+application, e.g. the user. Without rules everything is allowed. Rules are
+fixed values or callables `(context) -> flags | bool` receiving the context
+directly, `None` if no context is given. The declarations are generic in the
+type of the context (`None` if not given, `SqlFieldAccess[User]`,
+`SqlQueryFactory[User]`), `SqlModelAccess` also in the model of the rows
+rule (`SqlModelAccess[User, Self]` within the class body, the model defaults
+to `Any`).
+
+```python
+from typing import Annotated, Self
+from querymodelling.sql_query import (
+    INVISIBLE, FieldUsage, ModelUsage, SqlFieldAccess, SqlModelAccess,
+    SqlQueryFactory
+)
+
+class Book(SQLModel, table=True):
+    __sql_access__ = SqlModelAccess[User, Self](
+        # rows of the user's tenant only - in every position
+        rows=lambda user, book: book.tenant_id == user.tenant_id,
+    )
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+    cost: Annotated[float, SqlFieldAccess[User](lambda user: (
+        FieldUsage.ALL if user.is_admin else FieldUsage.AGGREGATE))]
+    tenant_id: Annotated[int, SqlFieldAccess(INVISIBLE)]
+
+class Salary(SQLModel, table=True):
+    __sql_access__ = SqlModelAccess[User](usage=lambda user: user.is_admin)
+    ...
 
-class ExampleQuery(PageQuery, BaseModel):
-    filter: ExampleFilter | None = QueryField(
-        sql_filter_expression, default=None)
+queries = SqlQueryFactory[User](Book, models=[Author, Salary])
+queries.schema(user)                   # JSON schema of the user
+query = queries.validate(data, user)   # validated for the user
+query.fetch(session)                   # rows rules applied for the user
 ```
 
+* Fields: `FieldUsage.SELECT` (`fields`), `FILTER` (`where`, `on`), `GROUP`
+  (`group_by`), `AGGREGATE` (within aggregate functions), `ALL` / `NONE`
+  (`VISIBLE` / `INVISIBLE`), declared by `Annotated[..., SqlFieldAccess(rule)]`
+  or `SqlModelAccess(fields={"name": rule})`.
+* Models: `ModelUsage.QUERY` (queried model), `JOIN`, `SUBQUERY`, declared
+  by `__sql_access__ = SqlModelAccess(usage=rule)`.
+* `rows`: `(context, entity) -> condition` restricts the rows of a model
+  wherever it is used (queried model, joins incl. outer joins, subqueries),
+  the model is replaced by a derived table of the permitted rows.
+* `SqlQueryModel(..., access={"book": SqlModelAccess(...)})` overrides the
+  declared rules, `SqlQueryModel(..., context=user)` evaluates them for a
+  context.
+* Models and fields without any access are removed from the query model and
+  its JSON schema (and are reported as unknown), partial access is checked
+  by the validation. `SqlQueryFactory` caches the query models per
+  permission signature: contexts with the same permissions share them.
+* Partial access may still reveal values: `FILTER` by comparisons,
+  `AGGREGATE` by `min` / `max` of a single row.

querymodelling-0.0.18/README.md

@@ -0,0 +1,243 @@
+# querymodelling
+build consistent api query models for fastapi
+
+## Requirements
+At least you will need to have the pydantic package installed. Of course it make sense to have some kind of service supporting query models like fast api. Currently sql models are implemented - but feel free to create new ones.
+
+## Installation
+
+## Example
+
+
+### Typed SQL query models
+
+`SqlQueryModel` generates a fully typed query model (incl. JSON schema)
+with `joins`, `fields`, `where`, `group_by` and subqueries, which is compiled
+into a SQLAlchemy select statement. Only the registered models can be
+queried.
+
+```python
+from sqlmodel import Session
+from querymodelling.sql_query import SqlQueryModel
+
+BookQuery = SqlQueryModel(Book, models=[Author, Review])
+
+query = BookQuery.model_validate({
+    "joins": [
+        {
+            "model": "author",
+            "type": "left",
+            "on": {"eq": [
+                {"model": "book", "field": "author_id"},
+                {"model": "author", "field": "id"}
+            ]}
+        }
+    ],
+    "fields": [
+        {"model": "book", "field": "id"},
+        {"model": "author", "field": "id", "alias": "author_id"},
+        {"lower": {"model": "author", "field": "name"}, "alias": "author_name"}
+    ],
+    "where": {"and": [
+        {"eq": [{"model": "book", "field": "id"}, 123]},
+        {"startswith": [{"model": "author", "field": "name"}, "M"]}
+    ]}
+})
+statement = query.to_select()      # SQLAlchemy select with labeled columns
+rows = query.fetch(session)        # list of typed result rows
+RowModel = query.result_model()    # typed row, without executing the query
+```
+
+```sql
+SELECT book.id AS id, author.id AS author_id, lower(author.name) AS author_name
+FROM book LEFT OUTER JOIN author ON book.author_id = author.id
+WHERE book.id = 123 AND author.name LIKE 'M' || '%'
+```
+
+**One rule:** a plain JSON value (string, number, boolean) is always a
+constant, an object is an expression identified by its keys:
+
+| Object | Expression |
+|---|---|
+| `{"model": "book", "field": "id"}` | field (`"as"` selects a joined instance) |
+| `{"model": "review", "fields": [...], "where": ...}` | subquery (no `field`) |
+| `{"lower": ...}`, `{"eq": [...]}` | function (its only key besides `alias`) |
+| `{"ref": "author_name"}` | alias of `fields` (`group_by` only) |
+
+* **Query**: `model` (defaults to the base model), `as`, `joins`, `fields`
+  (all fields of the queried model if not set), `where`, `group_by`.
+  Subqueries have the same structure.
+* **Joins**: `{"model", "as", "type", "on"}` with `type` `inner` (default),
+  `left` or `full`. `on` may reference the queried model and the previous
+  joins. A model joined twice needs `as`, it is referenced by
+  `{"model": "author", "as": "reviewer", "field": "name"}`. Fields of the
+  outer side of an outer join are `Optional` in the result model.
+* **Conditions** (`where`, `on`) are functions returning `bool`:
+  `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`
+  (`{"in": [x, [1, 2]]}` or `{"in": [x, <subquery>]}`), `contains`,
+  `icontains`, `startswith`, `istartswith`, `endswith`, `iendswith`, `like`,
+  `not_like`, `ilike`, `is_null`, `is_not_null`, `and`, `or`, `not` and
+  `exists` (`{"exists": <subquery>}`).
+* **Functions**: `lower`, `upper`, `trim`, `length`, `concat`, `substring`,
+  `replace`, `abs`, `round`, `ceil`, `floor`, `add`, `sub`, `mul`, `div`,
+  `date`, `year`, `month`, `day`, `hour`, `minute`, `coalesce`, `nullif`,
+  `cast` (`{"cast": [x, "string"]}`) and the aggregates `count`
+  (`{"count": "*"}` counts all rows), `count_distinct`, `sum`, `avg`, `min`,
+  `max`.
+* **Subqueries** used as value or in `in` return exactly one field, its type
+  is the type of the expression. Subqueries may reference the models of the
+  outer queries, inner models shadow outer ones with the same name (use
+  `as`).
+* **Typing**: all expressions are typed per result type, e.g.
+  `{"lower": <int field>}` or `{"eq": [<int field>, "x"]}` are rejected by
+  the JSON schema and the validation.
+* **Grouping**: fields outside of aggregate functions must be part of
+  `group_by`, aggregates must not be nested and are not allowed in `where`,
+  `on` and `group_by`. An empty `group_by` means no grouping.
+* **Limits**: `max_joins` (default 5) per (sub)query and `max_depth`
+  (default 3) of nested subqueries.
+
+```json
+{
+  "joins": [{"model": "author", "type": "left", "on": {"eq": [
+    {"model": "book", "field": "author_id"}, {"model": "author", "field": "id"}
+  ]}}],
+  "fields": [
+    {"lower": {"model": "author", "field": "name"}, "alias": "author_name"},
+    {"count": "*", "alias": "books"},
+    {"model": "review", "fields": [{"avg": {"model": "review", "field": "rating"}}],
+     "where": {"eq": [{"model": "review", "field": "book_id"}, {"model": "book", "field": "id"}]},
+     "alias": "avg_rating"}
+  ],
+  "where": {"exists": {"model": "review", "where": {"eq": [
+    {"model": "review", "field": "book_id"}, {"model": "book", "field": "id"}
+  ]}}},
+  "group_by": [{"ref": "author_name"}, {"model": "book", "field": "id"}]
+}
+```
+
+Models are registered by their table name (`models=[Author]`) or explicitly
+(`models={"writer": Author}`). `sources` overrides the table of a model,
+`include_fields` / `exclude_fields` restrict the fields (a list for the base
+model or a mapping of model names to lists).
+
+Functions and conditions are provided by generators `(annotation) ->
+Iterable[SqlExpressionFunction]` which are called for every known type:
+
+```python
+from sqlalchemy import Integer, func
+from querymodelling.sql_filter import without
+from querymodelling.sql_query import (
+    Expr, SqlExpressionFunction, default_sql_expression_mapping
+)
+
+def instr(annotation):
+    if annotation is str:
+        yield SqlExpressionFunction(
+            "instr", int, (Expr(str), Expr(str)),
+            lambda value, search: func.instr(value, search, type_=Integer()))
+
+mapping = default_sql_expression_mapping()
+mapping.function_generators = [
+    without(generator, "cast") for generator in mapping.function_generators
+]
+mapping.add_functions(instr)
+
+BookQuery = SqlQueryModel(Book, models=[Author], mapping=mapping)
+```
+
+Argument placeholders are `Expr(*types)` (an expression of the types, any
+type if empty), `Many(type)` (a list or a subquery, see `in`) and `Query()`
+(a subquery, see `exists`). Referenceable fields are provided by reference
+generators (`reference_generators=...`, e.g. virtual fields based on SQL
+expressions).
+
+#### Result schema
+
+The result of a validated query is known without executing it:
+`query.result_model()` is the typed model of a result row,
+`query.result_schema()` the JSON schema of the result rows
+(`result_schema(many=False)` of a single row).
+
+* Fields copy the information of their source field: type, `title`,
+  `description`, `examples`, `json_schema_extra`, `deprecated` and the
+  constraints (`max_length`, `ge`, ...). They may be `NULL` if their field is
+  optional or on the outer side of an outer join.
+* Constants are of their type and never `NULL`.
+* Functions define their result: `result_type`, `nullable` and
+  `result_field`:
+  * `nullable` (`Nullability`): `PROPAGATE` (default, `NULL` if any argument
+    may be `NULL`), `COALESCE` (if all arguments may be), `ALWAYS` (e.g.
+    `sum`, `avg`, `min`, `max`, `nullif`, `div`) or `NEVER` (e.g. `count`,
+    `is_null`, `exists`), `True` / `False` for always / never.
+  * `result_field`: field information from the arguments, `inherit()` (all
+    of the argument, e.g. `min`, `max`, `nullif`) or `describe()` (only its
+    title and description, e.g. `lower`, `round`, `avg`, `coalesce`).
+    Without a rule the result has no field information.
+* Subqueries are the result of their single field, `NULL` if they may return
+  no row (an aggregate without `group_by` always returns one row).
+
+```python
+SqlExpressionFunction(
+    "initials", str, (Expr(str),), lambda value: func.substr(value, 1, 1),
+    nullable=Nullability.PROPAGATE, result_field=describe(),
+)
+```
+
+#### Access rules
+
+Models and fields can be restricted per access context - any object of the
+application, e.g. the user. Without rules everything is allowed. Rules are
+fixed values or callables `(context) -> flags | bool` receiving the context
+directly, `None` if no context is given. The declarations are generic in the
+type of the context (`None` if not given, `SqlFieldAccess[User]`,
+`SqlQueryFactory[User]`), `SqlModelAccess` also in the model of the rows
+rule (`SqlModelAccess[User, Self]` within the class body, the model defaults
+to `Any`).
+
+```python
+from typing import Annotated, Self
+from querymodelling.sql_query import (
+    INVISIBLE, FieldUsage, ModelUsage, SqlFieldAccess, SqlModelAccess,
+    SqlQueryFactory
+)
+
+class Book(SQLModel, table=True):
+    __sql_access__ = SqlModelAccess[User, Self](
+        # rows of the user's tenant only - in every position
+        rows=lambda user, book: book.tenant_id == user.tenant_id,
+    )
+    id: int | None = Field(default=None, primary_key=True)
+    title: str
+    cost: Annotated[float, SqlFieldAccess[User](lambda user: (
+        FieldUsage.ALL if user.is_admin else FieldUsage.AGGREGATE))]
+    tenant_id: Annotated[int, SqlFieldAccess(INVISIBLE)]
+
+class Salary(SQLModel, table=True):
+    __sql_access__ = SqlModelAccess[User](usage=lambda user: user.is_admin)
+    ...
+
+queries = SqlQueryFactory[User](Book, models=[Author, Salary])
+queries.schema(user)                   # JSON schema of the user
+query = queries.validate(data, user)   # validated for the user
+query.fetch(session)                   # rows rules applied for the user
+```
+
+* Fields: `FieldUsage.SELECT` (`fields`), `FILTER` (`where`, `on`), `GROUP`
+  (`group_by`), `AGGREGATE` (within aggregate functions), `ALL` / `NONE`
+  (`VISIBLE` / `INVISIBLE`), declared by `Annotated[..., SqlFieldAccess(rule)]`
+  or `SqlModelAccess(fields={"name": rule})`.
+* Models: `ModelUsage.QUERY` (queried model), `JOIN`, `SUBQUERY`, declared
+  by `__sql_access__ = SqlModelAccess(usage=rule)`.
+* `rows`: `(context, entity) -> condition` restricts the rows of a model
+  wherever it is used (queried model, joins incl. outer joins, subqueries),
+  the model is replaced by a derived table of the permitted rows.
+* `SqlQueryModel(..., access={"book": SqlModelAccess(...)})` overrides the
+  declared rules, `SqlQueryModel(..., context=user)` evaluates them for a
+  context.
+* Models and fields without any access are removed from the query model and
+  its JSON schema (and are reported as unknown), partial access is checked
+  by the validation. `SqlQueryFactory` caches the query models per
+  permission signature: contexts with the same permissions share them.
+* Partial access may still reveal values: `FILTER` by comparisons,
+  `AGGREGATE` by `min` / `max` of a single row.

{querymodelling-0.0.17 → querymodelling-0.0.18}/querymodelling/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.17'
-__version_tuple__ = version_tuple = (0, 0, 17)
+__version__ = version = '0.0.18'
+__version_tuple__ = version_tuple = (0, 0, 18)
 
-__commit_id__ = commit_id = 'g9261b3e64'
+__commit_id__ = commit_id = 'gff99dd942'