pyrsql 0.0.2__tar.gz → 0.0.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrsql
-Version: 0.0.2
+Version: 0.0.3
 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
@@ -14,12 +14,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Compilers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: ciso8601>=2.3,<3.0
 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'
@@ -38,13 +38,13 @@ 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-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![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/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
-through a language frontend, semantic binder, logical IR, and pluggable
-backend lowering - making it easy to expose complex query capabilities in
-your API without coupling to a specific ORM or framework.
+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  
@@ -53,9 +53,10 @@ your API without coupling to a specific ORM or framework.
 ## Why pyrsql?
 
 Most API filtering libraries are tightly coupled to one ORM or one framework.
-pyrsql is built as a **compiler pipeline** - parsing, semantic analysis, and
-IR lowering are separate stages. Adding a new ORM backend means implementing
-one interface (`ORM`), not rewriting the parser or query language.
+pyrsql is built as a **compiler pipeline**. Parsing, semantic analysis, and
+backend lowering are separate stages. Adding a new ORM backend means
+implementing one interface (`ORM`), not rewriting the parser or query
+language.
 
 - **ORM-neutral core** - `Query`, `Sort`, `PageRequest` have zero ORM dependencies
 - **Pluggable backends** - implement `compile_query` / `compile_sort` /
@@ -64,6 +65,10 @@ one interface (`ORM`), not rewriting the parser or query language.
 - **Custom operators** - define your own RSQL operators with per-ORM lowering
 - **Field policies** - whitelist, blacklist, aliases at global and per-model level
 - **Type-safe** - strict mypy, Google-style docstrings, immutable value objects
+- **Performance-oriented internals** - immutable `msgspec` models across the
+  core pipeline and configuration objects
+- **Security-oriented request handling** - parser/sort limits, structural
+  allowlists/blocklists, sanitized FastAPI error payloads
 
 ## Quickstart
 
@@ -196,6 +201,15 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
 - Declarative `resource()` with auto-generated OpenAPI examples
 - `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
+- FastAPI semantic and backend integration failures become structured `HTTP 422` payloads
+
+### Concurrency and Validation
+
+- Shared integration 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
 
 ## Documentation
 
@@ -204,12 +218,13 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 | Section | Description |
 |---------|-------------|
 | [Quickstart](https://wskr00.github.io/pyrsql/quickstart/) | One-minute primer |
-| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, custom predicates |
+| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, async flows, custom predicates |
 | [API Reference](https://wskr00.github.io/pyrsql/reference/api/) | Auto-generated from docstrings |
 | [Operators](https://wskr00.github.io/pyrsql/reference/operators/) | Complete operator table |
 | [Options](https://wskr00.github.io/pyrsql/reference/options/) | QueryOptions, SortOptions, JSONOptions |
 | [Architecture](https://wskr00.github.io/pyrsql/explanation/architecture/) | Pipeline, modules, design |
 | [Extensibility](https://wskr00.github.io/pyrsql/explanation/extensibility/) | Adding backends and adapters |
+| [Testing](https://wskr00.github.io/pyrsql/testing/) | Test layers, async, security, free-threaded validation |
 | [Contributing](https://wskr00.github.io/pyrsql/contributing/) | Setup, workflow, standards |
 
 ## Development Principles

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

@@ -3,13 +3,13 @@
 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-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![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/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
-through a language frontend, semantic binder, logical IR, and pluggable
-backend lowering - making it easy to expose complex query capabilities in
-your API without coupling to a specific ORM or framework.
+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  
@@ -18,9 +18,10 @@ your API without coupling to a specific ORM or framework.
 ## Why pyrsql?
 
 Most API filtering libraries are tightly coupled to one ORM or one framework.
-pyrsql is built as a **compiler pipeline** - parsing, semantic analysis, and
-IR lowering are separate stages. Adding a new ORM backend means implementing
-one interface (`ORM`), not rewriting the parser or query language.
+pyrsql is built as a **compiler pipeline**. Parsing, semantic analysis, and
+backend lowering are separate stages. Adding a new ORM backend means
+implementing one interface (`ORM`), not rewriting the parser or query
+language.
 
 - **ORM-neutral core** - `Query`, `Sort`, `PageRequest` have zero ORM dependencies
 - **Pluggable backends** - implement `compile_query` / `compile_sort` /
@@ -29,6 +30,10 @@ one interface (`ORM`), not rewriting the parser or query language.
 - **Custom operators** - define your own RSQL operators with per-ORM lowering
 - **Field policies** - whitelist, blacklist, aliases at global and per-model level
 - **Type-safe** - strict mypy, Google-style docstrings, immutable value objects
+- **Performance-oriented internals** - immutable `msgspec` models across the
+  core pipeline and configuration objects
+- **Security-oriented request handling** - parser/sort limits, structural
+  allowlists/blocklists, sanitized FastAPI error payloads
 
 ## Quickstart
 
@@ -161,6 +166,15 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
 - Declarative `resource()` with auto-generated OpenAPI examples
 - `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
+- FastAPI semantic and backend integration failures become structured `HTTP 422` payloads
+
+### Concurrency and Validation
+
+- Shared integration 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
 
 ## Documentation
 
@@ -169,12 +183,13 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 | Section | Description |
 |---------|-------------|
 | [Quickstart](https://wskr00.github.io/pyrsql/quickstart/) | One-minute primer |
-| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, custom predicates |
+| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, async flows, custom predicates |
 | [API Reference](https://wskr00.github.io/pyrsql/reference/api/) | Auto-generated from docstrings |
 | [Operators](https://wskr00.github.io/pyrsql/reference/operators/) | Complete operator table |
 | [Options](https://wskr00.github.io/pyrsql/reference/options/) | QueryOptions, SortOptions, JSONOptions |
 | [Architecture](https://wskr00.github.io/pyrsql/explanation/architecture/) | Pipeline, modules, design |
 | [Extensibility](https://wskr00.github.io/pyrsql/explanation/extensibility/) | Adding backends and adapters |
+| [Testing](https://wskr00.github.io/pyrsql/testing/) | Test layers, async, security, free-threaded validation |
 | [Contributing](https://wskr00.github.io/pyrsql/contributing/) | Setup, workflow, standards |
 
 ## Development Principles

{pyrsql-0.0.2 → pyrsql-0.0.3}/docs/contributing.md

@@ -23,7 +23,7 @@ uv run pytest                # tests
 - strict mypy type checking
 - ruff for linting and formatting
 - pytest with `unit`, `integration`, `functional`, `performance` layers
-- ORM-neutral core - zero ORM imports in `pyrsql.core`, `pyrsql.ir`, `pyrsql.parsing`, `pyrsql.semantic`
+- ORM-neutral core - zero ORM imports in `pyrsql.core`, `pyrsql.parsing`, `pyrsql.semantic`, `pyrsql.sorting`
 
 ## Test layers
 

pyrsql-0.0.3/docs/explanation/architecture.md

@@ -0,0 +1,245 @@
+# pyrsql Architecture
+
+## Identity
+
+`pyrsql` is a compiler-oriented RSQL query engine. It turns RSQL-like filter
+and sort expressions into ORM-specific statement updates through a staged
+pipeline:
+
+```text
+query text
+-> parsing
+-> selector AST
+-> semantic binding
+-> backend lowering
+-> ORM-specific statement
+```
+
+The core is deliberately ORM-neutral. Adding a new backend means implementing
+the `ORM` interface, not rewriting the parser, selector grammar, or semantic
+rules.
+
+## Purpose
+
+The project is designed around four major responsibilities:
+
+- language frontend: parse text into syntax trees
+- semantic binding: resolve fields, functions, and access policies
+- 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
+adapter is FastAPI.
+
+## Current Pipeline
+
+More concretely, the runtime flow looks like this:
+
+```text
+RSQL string
+-> parsing AST
+-> selector nodes
+-> SemanticBinder / SortBinder
+-> Query / Sort / PageRequest application
+-> SQLAlchemyORM lowering
+-> SQLAlchemy Select
+```
+
+For pagination-only flows, `PageRequest` goes directly to backend lowering.
+
+## Module Boundaries
+
+The project is split into these main modules:
+
+- `parsing`
+- `selector`
+- `semantic`
+- `sorting`
+- `core`
+- `orms`
+- `adapters`
+- `integrations`
+- `api`
+
+### `parsing`
+
+Owns:
+
+- source spans
+- tokens
+- parser AST
+- parser limits
+- parse diagnostics and errors
+
+### `selector`
+
+Owns selector syntax only:
+
+- `FieldSelector`
+- `LiteralSelector`
+- `FunctionSelector`
+
+It does not own semantic meaning.
+
+### `semantic`
+
+Owns semantic binding:
+
+- field policy checks
+- function policy checks
+- field mapping
+- semantic diagnostics and errors
+- normalization for backend lowering
+
+### `sorting`
+
+Owns sort syntax and sort binding.
+
+### `core`
+
+Owns user-facing ORM-agnostic objects:
+
+- `Query`, `Sort`, `PageRequest`
+- `QueryOptions`, `SortOptions`
+- `FieldPolicySet`, `ProcedureAccessPolicy`
+- `CustomPredicateDefinition`
+- `ValueConverterRegistry`, `FieldValueConverterSet`
+- `JSONOptions`, `JSONSortScalarType`
+- `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.
+
+### `orms`
+
+Owns backend lowering.
+
+Current production backend:
+
+- `orms.sqlalchemy`
+
+Its job is:
+
+- consume normalized query, sort, and page objects
+- resolve model metadata
+- coerce values
+- lower to SQLAlchemy statements
+
+It should not redo semantic interpretation already handled upstream.
+
+For PostgreSQL JSON/JSONB lowering, the current design separates:
+
+- whole-document JSON predicates
+- nested JSON path predicates
+- JSON sort extraction rules
+
+This keeps the backend close to SQLAlchemy and PostgreSQL primitives instead of
+forcing every JSON case through one generic lowering path.
+
+### `adapters`
+
+Own framework-level request and error adaptation.
+
+Current adapter:
+
+- `adapters.fastapi`
+
+It is responsible for:
+
+- extracting query params
+- building `RequestCriteria`
+- translating pyrsql failures into framework-native HTTP errors
+- adding OpenAPI metadata
+
+### `integrations`
+
+Own stack-specific orchestration across adapter + backend.
+
+Current integration:
+
+- `integrations.fastapi.sqlalchemy`
+
+It is responsible for:
+
+- request criteria application helpers
+- route-ready dependencies
+- declarative resource configuration
+- stack-specific DX
+
+### `api`
+
+Owns the smallest public helper surface:
+
+- `parse(...)`
+- `compile(...)`
+- `apply(...)`
+
+## Extensibility
+
+### Adding a new ORM backend
+
+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: ...
+```
+
+Each method receives one ORM-neutral core object and returns a compiled object
+with an `apply(target, model)` method.
+
+### Adding a new framework adapter
+
+Implement `pyrsql.adapters.*` to extract query parameters from requests and
+translate pyrsql failures into framework-native HTTP responses.
+
+The FastAPI adapter is the reference implementation.
+
+## Design Principles
+
+The project follows:
+
+- object-oriented design
+- SOLID
+- strong typing
+- backend-independent core semantics
+- performance-oriented data modeling
+- explicit concurrency boundaries
+
+### Practical interpretation
+
+- semantic work should happen before the ORM backend
+- ORMs should do lowering, not semantic analysis
+- adapters should do transport adaptation, not query semantics
+- integrations should provide DX, not execution frameworks
+
+## Performance Direction
+
+The project uses `msgspec` where it improves compactness and immutable data
+modeling:
+
+- diagnostics
+- parser/source structures
+- adapter and integration payloads
+- core query/sort/options/value-policy models
+
+Other performance principles:
+
+- cache repeated base statements when safe
+- avoid repeating semantic work in the ORM backend
+- keep shared cache lock scope small in concurrency-sensitive paths
+
+## Async and Free-Threaded Support
+
+These are related but separate concerns:
+
+- async support means generated SQLAlchemy statements work with both `Session`
+  and `AsyncSession`
+- free-threaded support means shared mutable caches are synchronized explicitly
+
+The core query pipeline stays synchronous and ORM-neutral in both cases.

pyrsql-0.0.3/docs/explanation/extensibility.md

@@ -0,0 +1,90 @@
+# Extensibility
+
+`pyrsql` is designed to support multiple ORM backends and framework adapters.
+The core (`pyrsql.core`, `pyrsql.parsing`, `pyrsql.semantic`,
+`pyrsql.sorting`) has zero dependencies on any ORM or framework.
+
+## Adding a new ORM backend
+
+Implement the `ORM` abstract base class:
+
+```python
+from pyrsql.orms.base import ORM, CompiledPageRequest, CompiledQuery, CompiledSort
+
+class MyORM(ORM):
+    @property
+    def name(self) -> str:
+        return "my-orm"
+
+    def compile_query(self, query: Query) -> CompiledQuery:
+        ...
+
+    def compile_sort(self, sort: Sort) -> CompiledSort:
+        ...
+
+    def compile_page_request(self, page_request: PageRequest) -> CompiledPageRequest:
+        ...
+```
+
+Each `compile_*` method receives one ORM-neutral core object (`Query`, `Sort`,
+or `PageRequest`) and returns a compiled object with an `apply(target, model)`
+method.
+
+The current reference implementation is `SQLAlchemyORM` in
+`pyrsql.orms.sqlalchemy`.
+
+## Adding a new framework adapter
+
+Create a module under `pyrsql.adapters` that:
+
+1. extracts query parameters from requests
+2. builds `RequestCriteria`
+3. translates parse, semantic, and page-validation failures into
+   framework-appropriate error responses
+
+The FastAPI adapter (`pyrsql.adapters.fastapi`) is the reference:
+
+- `FastAPICriteriaConfig` holds public parameter names and defaults
+- `criteria_dependency()` returns a FastAPI dependency callable
+
+## Backend contract in detail
+
+### `CompiledQuery`
+
+```python
+class CompiledQuery(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`.
+
+## Integration layer
+
+Adapters and ORMs can stay independent. The `integrations/` package is where
+stack-specific DX belongs.
+
+For example, `integrations.fastapi.sqlalchemy` is allowed to know both:
+
+- the FastAPI adapter contract
+- the SQLAlchemy backend contract
+
+That is the right place for:
+
+- route-ready dependencies
+- paginated statement bundles
+- OpenAPI example generation tied to SQLAlchemy model metadata
+
+## Planned backends and adapters
+
+- **Django ORM** - compile to Django `QuerySet`
+- **SQLModel** - likely reuse most SQLAlchemy lowering
+- **Flask** - request adapter for `request.args`

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

@@ -34,3 +34,25 @@ stmt = pyrsql.parse("name==demo;age=gt=18").apply(select(User), User, orm=orm)
 - **Field policies** - whitelist, blacklist, aliases (global + per-model)
 - **JSON / JSONB** - PostgreSQL `jsonpath` with structured values and datetime support
 - **Type-safe** - strict mypy, Google-style docstrings, immutable value objects
+- **Async-compatible execution** - generated SQLAlchemy statements work with
+  both `Session` and `AsyncSession`
+- **Free-threaded-safe shared caches** - integration and ORM helper caches are
+  guarded for concurrent access
+- **Security-oriented request handling** - parser/sort limits, structural
+  allowlists/blocklists, and sanitized FastAPI error payloads
+
+## 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
+
+## Next steps
+
+- [Quickstart](quickstart.md)
+- [FastAPI Adapter](usage/fastapi.md)
+- [FastAPI + SQLAlchemy](usage/fastapi-sqlalchemy.md)
+- [Async Flows](usage/async.md)
+- [Architecture](explanation/architecture.md)

pyrsql-0.0.3/docs/quickstart.md

@@ -0,0 +1,143 @@
+# Quickstart
+
+## Install
+
+```bash
+pip install pyrsql                    # core only
+pip install pyrsql[sqlalchemy]        # with SQLAlchemy
+pip install pyrsql[fastapi]           # with FastAPI
+pip install pyrsql[fastapi,sqlalchemy]  # both
+```
+
+## Filter
+
+```python
+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("score=bt=(10,20)")      # BETWEEN
+Query.parse("name==demo;age=gt=18")  # AND
+Query.parse("name==demo,age=gt=18")  # OR
+```
+
+## Sort
+
+```python
+from pyrsql import Sort
+
+Sort.parse("name")              # ascending
+Sort.parse("name,desc")         # descending
+Sort.parse("name,asc;company.name,desc")  # multi-field
+```
+
+## Paginate
+
+```python
+from pyrsql import PageRequest
+
+PageRequest.of(0, 25)   # first page, 25 items
+PageRequest.of(2, 25)   # third page, 25 items
+```
+
+## SQLAlchemy
+
+```python
+from pyrsql import PageRequest, Query, Sort
+from pyrsql.orms.sqlalchemy import SQLAlchemyORM
+from sqlalchemy import select
+
+orm = SQLAlchemyORM()
+
+stmt = select(User)
+stmt = Query.parse("name==demo;company.name==acme*").apply(
+    stmt,
+    User,
+    orm=orm,
+)
+stmt = Sort.parse("name,asc;company.name,desc").apply(stmt, User, orm=orm)
+stmt = PageRequest.of(0, 25).apply(stmt, User, orm=orm)
+```
+
+## FastAPI
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from pyrsql.adapters.fastapi import RequestCriteria, criteria_dependency
+
+app = FastAPI()
+
+@app.get("/items")
+def list_items(
+    criteria: Annotated[RequestCriteria, Depends(criteria_dependency())],
+):
+    return {"is_empty": criteria.is_empty}
+```
+
+Query params `filter`, `sort`, `page`, `size` are extracted automatically.
+Parse and page-validation errors become structured `HTTP 400` responses.
+Semantic and backend integration errors become structured `HTTP 422`
+responses.
+
+## FastAPI + SQLAlchemy
+
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(integration.select_dependency(User))],
+):
+    return {"sql": str(stmt)}
+```
+
+Also available:
+
+- `count_select_dependency(...)`
+- `paginated_select_dependency(...)`
+- declarative `resource(...)`
+
+## Async execution
+
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+
+@app.get("/users")
+async def list_users(
+    stmt: Annotated[Any, Depends(integration.select_dependency(User))],
+    session: Annotated[AsyncSession, Depends(get_async_session)],
+):
+    result = await session.scalars(stmt)
+    return result.all()
+```
+
+`pyrsql` builds statements only; your application decides whether to execute
+them through sync or async SQLAlchemy sessions.
+
+## Notes
+
+- `pyrsql` builds statements and criteria objects only. Your application
+  decides whether execution happens through sync or async SQLAlchemy sessions.
+- Shared integration and ORM metadata caches are validated for free-threaded
+  execution.
+- Dedicated async, free-threaded, and security suites are documented in
+  [Testing](testing.md).

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

@@ -36,7 +36,6 @@
 - `pyrsql.integrations.fastapi` - FastAPI + SQLAlchemy (FastAPISQLAlchemyIntegration, FastAPISQLAlchemyResource)
 - `pyrsql.orms.sqlalchemy` - SQLAlchemy backend (SQLAlchemyORM)
 - `pyrsql.core` - ORM-neutral core types and options
-- `pyrsql.ir` - Logical intermediate representation
 - `pyrsql.parsing` - Lexer, parser, operators, limits
 - `pyrsql.selector` - Selector syntax
 - `pyrsql.semantic` - Semantic binding