pyrsql 0.0.3__tar.gz → 0.0.5__tar.gz

{pyrsql-0.0.3 → pyrsql-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrsql
-Version: 0.0.3
+Version: 0.0.5
 Summary: Compiler-oriented RSQL query engine for safe, typed, and extensible Python ORM-backed APIs.
 Keywords: rsql,orm,filter,pagination,sort,sqlalchemy,fastapi,rest
 License-Expression: MIT
@@ -9,7 +9,6 @@ Classifier: Environment :: Web Environment
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -20,11 +19,11 @@ Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Compilers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: msgspec>=0.18,<1.0
-Requires-Dist: typing-extensions>=4.10.0 ; python_full_version < '3.11'
-Requires-Dist: fastapi>=0.110,<1.0 ; extra == 'fastapi'
-Requires-Dist: sqlalchemy>=2.0,<3.0 ; extra == 'sqlalchemy'
-Requires-Python: >=3.10
+Requires-Dist: msgspec>=0.22.0,<1.0
+Requires-Dist: fastapi>=0.150.0,<1.0 ; extra == 'fastapi'
+Requires-Dist: sqlalchemy[asyncio]>=2.1,<3.0 ; extra == 'sqlalchemy'
+Requires-Dist: typing-extensions>=4.10.0 ; extra == 'sqlalchemy'
+Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/wskr00/pyrsql
 Project-URL: Repository, https://github.com/wskr00/pyrsql
 Project-URL: Issues, https://github.com/wskr00/pyrsql/issues
@@ -38,7 +37,7 @@ Description-Content-Type: text/markdown
 A compiler-oriented RSQL query engine for safe, typed, and extensible
 filtering, sorting, and pagination in Python APIs.
 
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
@@ -46,9 +45,14 @@ through a language frontend, semantic binding, and pluggable backend
 lowering - making it easy to expose complex query capabilities in your API
 without coupling to a specific ORM or framework.
 
-**Current backends:** SQLAlchemy 2.0  
-**Current framework adapters:** FastAPI  
-**Planned:** Django ORM, SQLModel, Flask
+For FastAPI applications using SQLAlchemy, the recommended entry point is
+`FastAPISQLAlchemyIntegration`. It provides route-ready dependencies and
+declarative resources; the lower-level query, adapter, and ORM APIs remain
+available when more control is needed.
+
+- **Current backends:** SQLAlchemy 2.1+
+- **Current framework adapters:** FastAPI
+- **Planned:** Django ORM, SQLModel, Flask
 
 ## Why pyrsql?
 
@@ -73,9 +77,41 @@ language.
 ## Quickstart
 
 ```bash
-pip install pyrsql[sqlalchemy]
+pip install pyrsql[fastapi,sqlalchemy]
 ```
 
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+    max_page_size=100,
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
+```
+
+Clients can now use `filter`, `sort`, `page`, and `size` query parameters.
+See [FastAPI + SQLAlchemy](https://wskr00.github.io/pyrsql/usage/fastapi-sqlalchemy/)
+for count, pagination, custom base statements, error behavior, and async use.
+
+### Lower-level SQLAlchemy API
+
+Use the direct API when you do not need a FastAPI route dependency:
+
 ```python
 import pyrsql
 from sqlalchemy import select
@@ -84,13 +120,13 @@ from pyrsql.orms.sqlalchemy import SQLAlchemyORM
 orm = SQLAlchemyORM()
 stmt = select(User)
 
-# Filter: name equals "demo", company name contains "acme"
-stmt = pyrsql.parse("name==demo;company.name==acme*").apply(stmt, User, orm=orm)
+stmt = pyrsql.parse("name==demo;company.name==acme*").apply(
+    stmt,
+    User,
+    orm=orm,
+)
 
-# Sort: by name ascending, then company name descending
 stmt = pyrsql.Sort.parse("name,asc;company.name,desc").apply(stmt, User, orm=orm)
-
-# Paginate: page 0, 25 items per page
 stmt = pyrsql.PageRequest.of(0, 25).apply(stmt, User, orm=orm)
 ```
 
@@ -168,6 +204,9 @@ options = QueryOptions(join_hints={"User.company": JoinHint.LEFT})
 
 ### FastAPI Integration
 
+Use this adapter directly when you need only parsed `RequestCriteria`; for
+SQLAlchemy routes, prefer the integration below.
+
 ```python
 from fastapi import Depends, FastAPI
 from pyrsql.adapters.fastapi import criteria_dependency
@@ -181,10 +220,11 @@ def list_items(criteria = Depends(dependency)):
 ```
 
 - Auto-extracts `filter`, `sort`, `page`, `size` from query params
-- `HTTP 422` with structured diagnostics on parse/semantic errors
+- Structured `HTTP 400` parse errors and `HTTP 422` semantic errors
 - OpenAPI examples from configuration
 - One-based paging support
 - Custom query parameter names
+- Optional repeated sort parameters through `SortParameterFormat.REPEATED`
 
 ### FastAPI + SQLAlchemy Integration
 
@@ -199,7 +239,7 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 ```
 
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
-- Declarative `resource()` with auto-generated OpenAPI examples
+- Declarative `resource()` with auto-generated OpenAPI examples and field policies
 - `applier_dependency` for custom base statements
 - Compatible with both sync `Session` and async `AsyncSession` execution
 - FastAPI parse and page-validation failures become structured `HTTP 400` payloads
@@ -207,7 +247,7 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 
 ### Concurrency and Validation
 
-- Shared integration and ORM metadata caches are protected for free-threaded execution
+- Shared base-select and ORM metadata caches are protected for free-threaded execution
 - Async support is validated for adapter, ORM, and integration flows
 - Dedicated async, free-threaded, and security test suites validate these flows
 
@@ -235,6 +275,10 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 - Strong typing
 - ORM-neutral public API
 
+## Acknowledgements
+
+`pyrsql` was strongly inspired by [Jirutka's `rsql-parser`](https://github.com/jirutka/rsql-parser) and [PerplexHub's `rsql-jpa-specification`](https://github.com/perplexhub/rsql-jpa-specification), especially their RSQL syntax and filtering behavior. I am grateful to their maintainers and contributors for their work.
+
 ## License
 
 [MIT](LICENSE).

{pyrsql-0.0.3 → pyrsql-0.0.5}/README.md

@@ -3,7 +3,7 @@
 A compiler-oriented RSQL query engine for safe, typed, and extensible
 filtering, sorting, and pagination in Python APIs.
 
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
@@ -11,9 +11,14 @@ through a language frontend, semantic binding, and pluggable backend
 lowering - making it easy to expose complex query capabilities in your API
 without coupling to a specific ORM or framework.
 
-**Current backends:** SQLAlchemy 2.0  
-**Current framework adapters:** FastAPI  
-**Planned:** Django ORM, SQLModel, Flask
+For FastAPI applications using SQLAlchemy, the recommended entry point is
+`FastAPISQLAlchemyIntegration`. It provides route-ready dependencies and
+declarative resources; the lower-level query, adapter, and ORM APIs remain
+available when more control is needed.
+
+- **Current backends:** SQLAlchemy 2.1+
+- **Current framework adapters:** FastAPI
+- **Planned:** Django ORM, SQLModel, Flask
 
 ## Why pyrsql?
 
@@ -38,9 +43,41 @@ language.
 ## Quickstart
 
 ```bash
-pip install pyrsql[sqlalchemy]
+pip install pyrsql[fastapi,sqlalchemy]
 ```
 
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+    max_page_size=100,
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
+```
+
+Clients can now use `filter`, `sort`, `page`, and `size` query parameters.
+See [FastAPI + SQLAlchemy](https://wskr00.github.io/pyrsql/usage/fastapi-sqlalchemy/)
+for count, pagination, custom base statements, error behavior, and async use.
+
+### Lower-level SQLAlchemy API
+
+Use the direct API when you do not need a FastAPI route dependency:
+
 ```python
 import pyrsql
 from sqlalchemy import select
@@ -49,13 +86,13 @@ from pyrsql.orms.sqlalchemy import SQLAlchemyORM
 orm = SQLAlchemyORM()
 stmt = select(User)
 
-# Filter: name equals "demo", company name contains "acme"
-stmt = pyrsql.parse("name==demo;company.name==acme*").apply(stmt, User, orm=orm)
+stmt = pyrsql.parse("name==demo;company.name==acme*").apply(
+    stmt,
+    User,
+    orm=orm,
+)
 
-# Sort: by name ascending, then company name descending
 stmt = pyrsql.Sort.parse("name,asc;company.name,desc").apply(stmt, User, orm=orm)
-
-# Paginate: page 0, 25 items per page
 stmt = pyrsql.PageRequest.of(0, 25).apply(stmt, User, orm=orm)
 ```
 
@@ -133,6 +170,9 @@ options = QueryOptions(join_hints={"User.company": JoinHint.LEFT})
 
 ### FastAPI Integration
 
+Use this adapter directly when you need only parsed `RequestCriteria`; for
+SQLAlchemy routes, prefer the integration below.
+
 ```python
 from fastapi import Depends, FastAPI
 from pyrsql.adapters.fastapi import criteria_dependency
@@ -146,10 +186,11 @@ def list_items(criteria = Depends(dependency)):
 ```
 
 - Auto-extracts `filter`, `sort`, `page`, `size` from query params
-- `HTTP 422` with structured diagnostics on parse/semantic errors
+- Structured `HTTP 400` parse errors and `HTTP 422` semantic errors
 - OpenAPI examples from configuration
 - One-based paging support
 - Custom query parameter names
+- Optional repeated sort parameters through `SortParameterFormat.REPEATED`
 
 ### FastAPI + SQLAlchemy Integration
 
@@ -164,7 +205,7 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 ```
 
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
-- Declarative `resource()` with auto-generated OpenAPI examples
+- Declarative `resource()` with auto-generated OpenAPI examples and field policies
 - `applier_dependency` for custom base statements
 - Compatible with both sync `Session` and async `AsyncSession` execution
 - FastAPI parse and page-validation failures become structured `HTTP 400` payloads
@@ -172,7 +213,7 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 
 ### Concurrency and Validation
 
-- Shared integration and ORM metadata caches are protected for free-threaded execution
+- Shared base-select and ORM metadata caches are protected for free-threaded execution
 - Async support is validated for adapter, ORM, and integration flows
 - Dedicated async, free-threaded, and security test suites validate these flows
 
@@ -200,6 +241,10 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 - Strong typing
 - ORM-neutral public API
 
+## Acknowledgements
+
+`pyrsql` was strongly inspired by [Jirutka's `rsql-parser`](https://github.com/jirutka/rsql-parser) and [PerplexHub's `rsql-jpa-specification`](https://github.com/perplexhub/rsql-jpa-specification), especially their RSQL syntax and filtering behavior. I am grateful to their maintainers and contributors for their work.
+
 ## License
 
 [MIT](LICENSE).

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/explanation/architecture.md

@@ -28,7 +28,7 @@ The project is designed around four major responsibilities:
 - backend lowering: turn validated query objects into ORM-specific statements
 - optional framework adapters and integrations: expose the core in HTTP stacks
 
-The current production backend is SQLAlchemy 2.0. The current framework
+The current production backend is SQLAlchemy 2.1+. The current framework
 adapter is FastAPI.
 
 ## Current Pipeline
@@ -108,7 +108,6 @@ Owns user-facing ORM-agnostic objects:
 - `JSONPath`, `JSONPathComparison`
 - `JSONScalarNormalizer`, `JSONScalarValue`
 - `JoinHint`
-- `CompilationResult`, `SortCompilationResult`, `PageCompilationResult`
 
 The `core/json/` package owns JSON-aware comparison models and value
 normalization, keeping JSON semantics ORM-neutral.
@@ -185,9 +184,9 @@ Implement `pyrsql.orms.base.ORM`:
 
 ```python
 class ORM(ABC):
-    def compile_query(self, query: Query) -> CompiledQuery: ...
-    def compile_sort(self, sort: Sort) -> CompiledSort: ...
-    def compile_page_request(self, page_request: PageRequest) -> CompiledPageRequest: ...
+    def compile_query(self, query: Query) -> CompiledArtifact: ...
+    def compile_sort(self, sort: Sort) -> CompiledArtifact: ...
+    def compile_page_request(self, page_request: PageRequest) -> CompiledArtifact: ...
 ```
 
 Each method receives one ORM-neutral core object and returns a compiled object

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/explanation/extensibility.md

@@ -9,20 +9,17 @@ The core (`pyrsql.core`, `pyrsql.parsing`, `pyrsql.semantic`,
 Implement the `ORM` abstract base class:
 
 ```python
-from pyrsql.orms.base import ORM, CompiledPageRequest, CompiledQuery, CompiledSort
+from pyrsql.core.compiler import CompiledArtifact
+from pyrsql.orms.base import ORM
 
 class MyORM(ORM):
-    @property
-    def name(self) -> str:
-        return "my-orm"
-
-    def compile_query(self, query: Query) -> CompiledQuery:
+    def compile_query(self, query: Query) -> CompiledArtifact:
         ...
 
-    def compile_sort(self, sort: Sort) -> CompiledSort:
+    def compile_sort(self, sort: Sort) -> CompiledArtifact:
         ...
 
-    def compile_page_request(self, page_request: PageRequest) -> CompiledPageRequest:
+    def compile_page_request(self, page_request: PageRequest) -> CompiledArtifact:
         ...
 ```
 
@@ -49,23 +46,18 @@ The FastAPI adapter (`pyrsql.adapters.fastapi`) is the reference:
 
 ## Backend contract in detail
 
-### `CompiledQuery`
+### `CompiledArtifact`
 
 ```python
-class CompiledQuery(Protocol):
+class CompiledArtifact(Protocol):
     def apply(self, target: _TargetT, model: type[_ModelT]) -> _TargetT: ...
 ```
 
 Receives an ORM-specific target and model class, then returns the modified
 target with query conditions applied.
 
-### `CompiledSort`
-
-Same contract as `CompiledQuery`, but applies sort ordering.
-
-### `CompiledPageRequest`
-
-Same contract, but applies pagination semantics such as `LIMIT` and `OFFSET`.
+The same contract applies to query, sort, and pagination artifacts such as
+`LIMIT` and `OFFSET`.
 
 ## Integration layer
 

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/index.md

@@ -10,24 +10,42 @@ capabilities in your API without coupling to a specific ORM or framework.
 ## Install
 
 ```bash
-pip install pyrsql[sqlalchemy]
+pip install pyrsql[fastapi,sqlalchemy]
 ```
 
-## First query
+## Recommended: FastAPI + SQLAlchemy
 
 ```python
-import pyrsql
-from sqlalchemy import select
-from pyrsql.orms.sqlalchemy import SQLAlchemyORM
+from typing import Annotated, Any
 
-orm = SQLAlchemyORM()
-stmt = pyrsql.parse("name==demo;age=gt=18").apply(select(User), User, orm=orm)
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
 ```
 
+The integration parses request criteria, applies SQLAlchemy filters/sorting/
+pagination, and exposes a route-ready dependency. It does not execute database
+I/O.
+
 ## Key features
 
 - **ORM-neutral core** - `Query`, `Sort`, `PageRequest` have zero ORM dependencies
-- **Pluggable backends** - SQLAlchemy 2.0 today, Django ORM / SQLModel planned
+- **Pluggable backends** - SQLAlchemy 2.1+ today, Django ORM / SQLModel planned
 - **Pluggable adapters** - FastAPI today, Flask planned
 - **20+ built-in operators** - `==`, `=like=`, `=in=`, `=bt=`, `=nn=`, etc.
 - **Custom operators** - define your own RSQL operators with per-ORM lowering
@@ -43,11 +61,11 @@ stmt = pyrsql.parse("name==demo;age=gt=18").apply(select(User), User, orm=orm)
 
 ## Integration options
 
-- **FastAPI adapter** - parse `filter`, `sort`, `page`, and `size` into
-  `RequestCriteria`
 - **FastAPI + SQLAlchemy integration** - route-ready dependencies,
   declarative `resource()` helpers, count/paginated bundles, and normalized
   backend error translation
+- **FastAPI adapter** - parse `filter`, `sort`, `page`, and `size` into
+  `RequestCriteria` when you need criteria without SQLAlchemy integration
 
 ## Next steps
 

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/quickstart.md

@@ -9,6 +9,44 @@ pip install pyrsql[fastapi]           # with FastAPI
 pip install pyrsql[fastapi,sqlalchemy]  # both
 ```
 
+## Recommended: FastAPI + SQLAlchemy
+
+For a FastAPI application backed by SQLAlchemy, start with the integration.
+It owns the public query contract for one model and gives routes a ready-to-use
+SQLAlchemy statement.
+
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
+```
+
+Clients can use `filter`, `sort`, `page`, and `size`. The integration also
+offers count and paginated dependencies. See [FastAPI + SQLAlchemy](usage/fastapi-sqlalchemy.md)
+for the complete route API.
+
+## Building blocks
+
+The following sections show the lower-level APIs used by the integration. They
+are useful for non-FastAPI applications or when you need direct control.
+
 ## Filter
 
 ```python
@@ -17,7 +55,7 @@ from pyrsql import Query
 Query.parse("name==demo")            # equal
 Query.parse("age=gt=18")             # greater than
 Query.parse("id=in=(1,2,3)")         # IN
-Query.parse("name=like=demo*")       # LIKE
+Query.parse("name=like=demo")        # contains: LIKE '%demo%'
 Query.parse("score=bt=(10,20)")      # BETWEEN
 Query.parse("name==demo;age=gt=18")  # AND
 Query.parse("name==demo,age=gt=18")  # OR
@@ -83,7 +121,7 @@ Parse and page-validation errors become structured `HTTP 400` responses.
 Semantic and backend integration errors become structured `HTTP 422`
 responses.
 
-## FastAPI + SQLAlchemy
+## Direct integration dependency
 
 ```python
 from typing import Annotated, Any

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/reference/api.md

@@ -27,12 +27,11 @@
         - ValueConverterRegistry
         - JoinHint
         - ORM
-        - CompilationResult
         - DEFAULT_JSON_OPTIONS
 
 ## Subpackages
 
-- `pyrsql.adapters.fastapi` - FastAPI adapter (FastAPICriteriaConfig, RequestCriteria, CriteriaDependency)
+- `pyrsql.adapters.fastapi` - FastAPI adapter (FastAPICriteriaConfig, RequestCriteria, CriteriaDependency, SortParameterFormat)
 - `pyrsql.integrations.fastapi` - FastAPI + SQLAlchemy (FastAPISQLAlchemyIntegration, FastAPISQLAlchemyResource)
 - `pyrsql.orms.sqlalchemy` - SQLAlchemy backend (SQLAlchemyORM)
 - `pyrsql.core` - ORM-neutral core types and options

pyrsql-0.0.5/docs/reference/operators.md

@@ -0,0 +1,51 @@
+# Operators
+
+Pyrsql supports the base RSQL comparison operators and the extensions used by
+PerplexHub's JPA specification.
+
+## Comparison operators
+
+| Operator | Aliases | Arity | Description |
+|----------|---------|-------|-------------|
+| `==` | | 1 | Equal |
+| `!=` | | 1 | Not equal |
+| `=gt=` | `>` | 1 | Greater than |
+| `=ge=` | `>=` | 1 | Greater or equal |
+| `=lt=` | `<` | 1 | Less than |
+| `=le=` | `<=` | 1 | Less or equal |
+| `=in=` | | 1..100 | IN (comma-separated args) |
+| `=out=` | | 1..100 | NOT IN |
+| `=like=` | `=ke=` | 1 | Contains match (`LIKE '%value%'`) |
+| `=notlike=` | `=nk=` | 1 | Negated contains match |
+| `=ilike=` | `=ik=` | 1 | Case-insensitive contains match |
+| `=inotlike=` | `=ni=` | 1 | Negated case-insensitive contains match |
+| `=ic=` | `=icase=` | 1 | Case-insensitive equality |
+| `=bt=` | `=between=` | 2 | BETWEEN (exactly 2 args) |
+| `=nb=` | `=notbetween=` | 2 | NOT BETWEEN (exactly 2 args) |
+| `=na=` | `=isnull=`, `=null=` | 0..1 | IS NULL |
+| `=nn=` | `=notnull=`, `=isnotnull=` | 0..1 | IS NOT NULL |
+
+For `=like=`, `=notlike=`, `=ilike=`, and `=inotlike=`, pyrsql surrounds the
+argument with `%` to match anywhere in the value. These operators use SQL
+`LIKE` pattern rules: `%` matches any number of characters, `_` matches one,
+and `*` is literal. The `like_escape_character` option controls SQL pattern
+escaping.
+
+For string-column `==` and `!=`, `*` is the wildcard and any `^` marker
+requests case-insensitive matching. Quoting an argument does not disable these
+markers. Use `=in=(*)` to match a literal asterisk.
+
+## Logical operators
+
+| Operator | Aliases | Description |
+|----------|---------|-------------|
+| `;` | `and` | AND (higher precedence) |
+| `,` | `or` | OR (lower precedence) |
+
+## Sort modifiers
+
+| Modifier | Example | Description |
+|----------|---------|-------------|
+| `asc` | `name,asc` | Ascending (default) |
+| `desc` | `name,desc` | Descending |
+| `ic` | `name,desc,ic` | Ignore case |

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/reference/options.md

@@ -26,6 +26,10 @@
 
 Notes:
 
+- `strict_equality=True` makes string `==` and `!=` compare markers such as
+  `*` and `^` literally; quoting alone does not disable them
+- `like_escape_character` applies to LIKE-based operators, including equality
+  comparisons that contain `*`
 - configuration containers are normalized into immutable views
 - procedure allow/block rules are compiled as regex policies and evaluated with
   `fullmatch`, not partial match

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/testing.md

@@ -134,7 +134,6 @@ shared mutable state.
 
 In `pyrsql`, the main targets are:
 
-- integration dependency caches
 - integration base-statement caches
 - SQLAlchemy model-introspection caches
 - resolver caches

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/usage/fastapi-sqlalchemy.md

@@ -1,6 +1,6 @@
 # FastAPI + SQLAlchemy
 
-## Setup
+## Recommended entry point
 
 ```python
 from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
@@ -21,6 +21,23 @@ The integration works with:
 - synchronous SQLAlchemy execution through `Session`
 - asynchronous SQLAlchemy execution through `AsyncSession`
 
+For routes that expose one stable model contract, prefer a declarative
+resource. It keeps field policies, default ordering, page limits, and OpenAPI
+examples next to the model they describe.
+
+```python
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,desc",
+    max_page_size=50,
+)
+```
+
+Use `FastAPISQLAlchemyIntegration` directly for dynamic models or when a
+service layer needs to build statements outside a route dependency.
+
 ## Route-ready dependencies
 
 ```python
@@ -140,9 +157,8 @@ This avoids leaking raw SQLAlchemy exceptions as `500` responses.
 
 ## Free-threaded behavior
 
-The integration caches dependency callables and base `select(model)` statements
-per model. Those shared caches are published with explicit synchronization for
-free-threaded execution.
+The integration caches base `select(model)` statements per model. That shared
+cache is published with explicit synchronization for free-threaded execution.
 
 ## Async note
 

{pyrsql-0.0.3 → pyrsql-0.0.5}/docs/usage/fastapi.md

@@ -40,6 +40,29 @@ config = FastAPICriteriaConfig(
 dependency = criteria_dependency(config)
 ```
 
+## Repeated sort parameters
+
+The default sort representation uses one semicolon-delimited parameter:
+
+```text
+?sort=name,asc;created_at,desc
+```
+
+To accept one sort field per repeated query parameter, configure the adapter
+with `SortParameterFormat.REPEATED`:
+
+```python
+from pyrsql.adapters.fastapi import SortParameterFormat
+
+config = FastAPICriteriaConfig(
+    sort_parameter_format=SortParameterFormat.REPEATED,
+)
+```
+
+```text
+?sort=name,asc&sort=created_at,desc
+```
+
 ## Class-based dependency
 
 ```python