querymodelling 0.0.16__tar.gz → 0.0.17__tar.gz

{querymodelling-0.0.16 → querymodelling-0.0.17}/.github/workflows/run-tests.yml

@@ -36,7 +36,7 @@ jobs:
         cache: 'pip'
     - name: Install dependencies
       run: |
-        pip install unittest-xml-reporting
+        pip install unittest-xml-reporting pydantic sqlmodel
     - name: Run tests
       run: |
         python tests

{querymodelling-0.0.16 → querymodelling-0.0.17}/HISTORY.md

@@ -1,6 +1,13 @@
 Release History
 ===============
 
+Unreleased
+----------
+
+-   sql_filter: add typed, nested and generator based SQL filter models
+    (``SqlFilterModel``) with ``and`` / ``or`` / ``not``, typed operators,
+    SQL functions and JSON schema support
+
 0.0.12 (2025-10-27)
 
 -   sql: add support for filtering boolean fields

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querymodelling
-Version: 0.0.16
+Version: 0.0.17
 Summary: build consistent api query models for fastapi
 Author: George Haddad
 Author-email: George Haddad <georgeh87@live.de>
@@ -224,3 +224,84 @@ 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.
+
+```python
+from sqlmodel import SQLModel, Field, select
+from querymodelling.sql_filter import SqlFilterModel
+
+class ExampleModel(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    description: str
+
+ExampleFilter = SqlFilterModel(ExampleModel)
+
+query = ExampleFilter.model_validate({
+    "and": {
+        "name": {"contains": "wurst", "startswith": "bump"},
+        "description": {"lower": {"contains": "test"}},
+    },
+    "or": [{"id": {"in": [1, 2]}}, {"name": {"length": {"gt": 3}}}],
+})
+statement = query.apply_sql(select(ExampleModel))
+# or: select(ExampleModel).where(query.to_sql_expression())
+```
+
+* 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:
+
+```python
+from querymodelling.sql_filter import (
+    SqlOperator, SqlFunction, default_sql_filter_mapping, for_types, without
+)
+
+def parity(annotation):
+    yield SqlOperator(
+        "even", lambda column, value: (column % 2 == 0) == value,
+        value_type=lambda annotation: bool)
+
+mapping = default_sql_filter_mapping(name_prefix="Custom")
+mapping.operator_generators = [
+    without(generator, "like", "ilike")
+    for generator in mapping.operator_generators
+]
+mapping.add_operators(for_types(parity, int, exclude=(bool,)))
+
+ExampleFilter = SqlFilterModel(ExampleModel, 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=...`)
+
+The filter can be used within existing query models as well:
+
+```python
+from querymodelling.pydantic import QueryField
+from querymodelling.sql_filter import sql_filter_expression
+
+class ExampleQuery(PageQuery, BaseModel):
+    filter: ExampleFilter | None = QueryField(
+        sql_filter_expression, default=None)
+```
+

querymodelling-0.0.17/README.md

@@ -0,0 +1,91 @@
+# 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 filter models
+
+`SqlFilterModel` generates a nested, fully typed filter model (incl. JSON
+schema) from a model and compiles it into a SQLAlchemy where clause.
+
+```python
+from sqlmodel import SQLModel, Field, select
+from querymodelling.sql_filter import SqlFilterModel
+
+class ExampleModel(SQLModel, table=True):
+    id: int | None = Field(default=None, primary_key=True)
+    name: str
+    description: str
+
+ExampleFilter = SqlFilterModel(ExampleModel)
+
+query = ExampleFilter.model_validate({
+    "and": {
+        "name": {"contains": "wurst", "startswith": "bump"},
+        "description": {"lower": {"contains": "test"}},
+    },
+    "or": [{"id": {"in": [1, 2]}}, {"name": {"length": {"gt": 3}}}],
+})
+statement = query.apply_sql(select(ExampleModel))
+# or: select(ExampleModel).where(query.to_sql_expression())
+```
+
+* 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:
+
+```python
+from querymodelling.sql_filter import (
+    SqlOperator, SqlFunction, default_sql_filter_mapping, for_types, without
+)
+
+def parity(annotation):
+    yield SqlOperator(
+        "even", lambda column, value: (column % 2 == 0) == value,
+        value_type=lambda annotation: bool)
+
+mapping = default_sql_filter_mapping(name_prefix="Custom")
+mapping.operator_generators = [
+    without(generator, "like", "ilike")
+    for generator in mapping.operator_generators
+]
+mapping.add_operators(for_types(parity, int, exclude=(bool,)))
+
+ExampleFilter = SqlFilterModel(ExampleModel, 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=...`)
+
+The filter can be used within existing query models as well:
+
+```python
+from querymodelling.pydantic import QueryField
+from querymodelling.sql_filter import sql_filter_expression
+
+class ExampleQuery(PageQuery, BaseModel):
+    filter: ExampleFilter | None = QueryField(
+        sql_filter_expression, default=None)
+```
+

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

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