fastapi-restly 0.7.0__tar.gz → 0.9.0__tar.gz

{fastapi_restly-0.7.0/fastapi_restly.egg-info → fastapi_restly-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-restly
-Version: 0.7.0
+Version: 0.9.0
 Summary: A REST Framework for FastAPI
 Author-email: Rutger Prins <rutgerprins@gmail.com>
 License-Expression: MIT
@@ -29,30 +29,42 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: alembic>=1.15.2
 Requires-Dist: fastapi>=0.115.0
-Requires-Dist: orjson>=3.10.18
 Requires-Dist: pydantic>=2.11.0
 Requires-Dist: pydantic-settings>=2.9.1
 Requires-Dist: sqlalchemy[asyncio]>=2.0.22
 Provides-Extra: standard
 Requires-Dist: fastapi[standard]>=0.115.0; extra == "standard"
 Provides-Extra: testing
+Requires-Dist: asgi-lifespan>=2.1.0; extra == "testing"
 Requires-Dist: httpx>=0.27.0; extra == "testing"
+Requires-Dist: httpx2>=2.0.0; extra == "testing"
 Requires-Dist: pytest>=8.3.5; extra == "testing"
 Requires-Dist: pytest-asyncio>=0.24.0; extra == "testing"
 Dynamic: license-file
 
-# FastAPI-Restly
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rjprins/fastapi-restly/main/docs/_static/fr-wordmark.svg" alt="FastAPI-Restly" width="664">
+</p>
 
-[![CI](https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml)
-[![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)](https://github.com/rjprins/fastapi-restly/blob/main/pyproject.toml)
-[![License](https://img.shields.io/github/license/rjprins/fastapi-restly)](https://github.com/rjprins/fastapi-restly/blob/main/LICENSE)
-[![Coverage](https://www.fastapi-restly.org/coverage/badge.svg)](https://www.fastapi-restly.org/coverage/)
+<p align="center">
+  <a href="https://pypi.org/project/fastapi-restly/"><img src="https://img.shields.io/pypi/v/fastapi-restly" alt="PyPI"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml"><img src="https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/blob/main/pyproject.toml"><img src="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" alt="Python"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rjprins/fastapi-restly" alt="License"></a>
+  <a href="https://www.fastapi-restly.org/coverage/"><img src="https://www.fastapi-restly.org/coverage/badge.svg" alt="Coverage"></a>
+</p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rjprins/fastapi-restly/main/docs/_static/restly-cat-white-bg.png" alt="FastAPI-Restly logo" width="200">
+  <a href="https://codespaces.new/rjprins/fastapi-restly?quickstart=1"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces"></a>
 </p>
 
-**Build maintainable REST APIs on FastAPI, SQLAlchemy 2.0, and Pydantic v2 — with real class-based views.**
+<p align="center">
+  Try FastAPI-Restly in your browser: the badge above opens a GitHub Codespace with the dev environment installed, ready to run a live example API.
+</p>
+
+<p align="center">
+  <strong>Build maintainable REST APIs on FastAPI, SQLAlchemy 2.0, and Pydantic v2 — with real class-based views.</strong>
+</p>
 
 > **Status:** public beta release ([changelog](https://github.com/rjprins/fastapi-restly/blob/main/CHANGELOG.md)).
 >
@@ -77,30 +89,28 @@ Its class-based views are real Python classes: use inheritance, mixins, and
 method overrides to share behavior across resources.
 
 - **Class-based views**: group endpoints on Python classes with inheritance and method overrides.
-- **REST endpoints in minutes**: use `View` for custom resources, or `AsyncRestView` / `RestView` for generated CRUD.
+- **REST endpoints in minutes**: use `View` for custom endpoint groups, or `AsyncRestView` / `RestView` for generated CRUD.
 - **Incremental adoption**: use Restly per resource; drop to ordinary FastAPI when needed — see [Existing Project Integration](https://www.fastapi-restly.org/howto_existing_project.html).
 - **Class-level dependencies**: declare shared dependencies once and read their values from `self`.
 - **Explicit override points**: change the route shell, request handler, or business verb.
 - **Filtering, pagination, sorting**: get schema-derived list parameters.
-- **Field control**: `ReadOnly` / `WriteOnly` markers, plus foreign-key validation through `IDRef[...]`.
-- **React Admin ready**: `AsyncReactAdminView` speaks `ra-data-simple-rest`.
+- **Field control**: `ReadOnly` / `WriteOnly` markers, plus foreign-key validation through `MustExist[...]`.
+- **React Admin ready**: `AsyncReactAdminView` / `ReactAdminView` speak `ra-data-simple-rest`.
 - **App utilities**: SQLAlchemy engine/session setup, exception handlers, and test fixtures.
 
-Coming from another CRUD generator? See
-[How Restly compares](https://www.fastapi-restly.org/about.html#how-restly-compares).
-
 ## Quickstart
 
 FastAPI-Restly turns a SQLAlchemy model into a class-based CRUD resource.
-(To make it fully runnable, add dev table creation — see
-[Getting Started](https://www.fastapi-restly.org/getting_started.html).)
+This example is complete and runnable; it creates SQLite tables at startup for
+local development. Use Alembic migrations in production.
 
 ```python
+from contextlib import asynccontextmanager
+
 import fastapi_restly as fr
 from fastapi import FastAPI
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
-app = FastAPI()
 fr.configure(async_database_url="sqlite+aiosqlite:///app.db")
 
 class Base(DeclarativeBase):
@@ -113,6 +123,13 @@ class User(Base):
     name: Mapped[str]
     email: Mapped[str]
 
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    await fr.db.async_create_all(Base)  # dev tables; use Alembic in production
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
 @fr.include_view(app)
 class UserView(fr.AsyncRestView):
     prefix = "/users"
@@ -131,6 +148,10 @@ DELETE /users/{id}   # delete one user
 
 Restly generates the Pydantic schemas automatically.
 
+The Quickstart uses plain SQLAlchemy on purpose — Restly doesn't hide it. In
+real projects you'll usually inherit `fr.IDBase` for models and `fr.IDSchema`
+for schemas, which supply the `id` for you; both appear in the examples below.
+
 ### Not just CRUD
 
 `View` is the same class-based machinery without the generated routes — use it
@@ -150,7 +171,7 @@ class AuthView(fr.View):
     async def logout(self) -> None: ...
 ```
 
-And because views truly subclass, the biggest everyday win takes four lines:
+And because views truly subclass, the biggest everyday win takes only a few lines:
 declare your app's request context once on a base view, and read it from
 `self` everywhere — instead of re-declaring the same `Depends` parameters on
 every function in the project:
@@ -170,7 +191,6 @@ resource, and `RestView` plus custom `@fr.post` methods for CRUD with actions.
 
 Why a `View` over a bare `APIRouter`?
 
-- Shared dependencies are typed attributes you read from `self` (`self.session`, `self.current_user`).
 - Prefix, tags, responses, and dependencies are declared once on the class.
 - Views compose: inheritance and mixins share behavior across endpoint groups.
 - One registration call (`fr.include_view`) per class, bindable to any app or router.
@@ -239,7 +259,7 @@ Use **auto-schema** for prototypes and internal tools. Use an **explicit schema*
 List endpoints expose a stable URL parameter dialect generated from the response schema:
 
 ```bash
-GET /users/?name=John&age__gte=21
+GET /users/?name=John&created_at__gte=2024-01-01
 GET /users/?email__icontains=example
 GET /users/?sort=-created_at&page=2&page_size=10
 ```
@@ -247,8 +267,10 @@ GET /users/?sort=-created_at&page=2&page_size=10
 Parameter keys use the **response schema's public names**, including dotted
 relation paths; unknown keys are rejected with `422`.
 
-Pagination is opt-in: omitting `page_size` returns every matching row. For
-public endpoints, set `default_page_size` and `max_page_size` on the view:
+Pagination is on by default: list endpoints wrap rows in a `data` envelope and
+cap each page at `default_page_size` (50). Clients page with `?page=` and
+`?page_size=`. Tune the default and set a `max_page_size` ceiling on public
+endpoints:
 
 ```python
 class UserView(fr.AsyncRestView):
@@ -272,8 +294,8 @@ class UserRead(fr.IDSchema):
 
 ### Relationship handling
 
-Validate relationships on create and update with `fr.IDRef[...]`.
-Restly passes either the foreign key (`customer_id`) or the related object (`Customer`) to SQLAlchemy, depending on the model constructor.
+Validate a foreign-key column on create and update with `fr.MustExist[int, Model]`.
+It keeps the plain id (`customer_id`) and checks the referenced row exists; declare the relationship (`customer`) separately when you also want the nested object.
 
 ```python
 class Order(fr.IDBase):
@@ -281,7 +303,7 @@ class Order(fr.IDBase):
     customer: Mapped[Customer] = relationship()
 
 class OrderRead(fr.IDSchema):
-    customer_id: fr.IDRef[Customer]
+    customer_id: fr.MustExist[int, Customer]
     customer: fr.ReadOnly[CustomerRead]
 ```
 
@@ -315,8 +337,9 @@ class UploadView(fr.AsyncRestView):
 
 ### React Admin integration
 
-Use `AsyncReactAdminView` for a [react-admin](https://marmelab.com/react-admin/)
-backend compatible with [`ra-data-simple-rest`](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest):
+Use `AsyncReactAdminView` (or `ReactAdminView` for a sync stack) for a
+[react-admin](https://marmelab.com/react-admin/) backend compatible with
+[`ra-data-simple-rest`](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest):
 
 ```python
 @fr.include_view(app)
@@ -340,21 +363,35 @@ class UserView(fr.AsyncRestView):
     exclude_routes = (fr.ViewRoute.DELETE,)
 ```
 
-### Pagination metadata
+### List response envelope
+
+List endpoints return a `data` envelope with pagination metadata:
+
+```json
+{"data": [...], "total_count": 123, "page": 1, "page_size": 50, "total_pages": 3}
+```
+
+Set `paginated = False` to return every matching row in a bare `data` envelope
+(no cap, no metadata):
 
 ```python
 @fr.include_view(app)
-class UserView(fr.AsyncRestView):
-    prefix = "/users"
-    model = User
-    include_pagination_metadata = True
-    # Response: {"items": [...], "total": N, "page": 1, "page_size": 100, "total_pages": N, ...}
+class TagView(fr.AsyncRestView):
+    prefix = "/tags"
+    model = Tag
+    paginated = False
+    # Response: {"data": [...]}
 ```
 
+For a different response shape, replace `get_many_endpoint` with a matching
+`response_model`; use `to_listing_response()` inside the replacement when you
+want to reuse the default serialization and page-metadata calculation.
+
 ## Testing
 
 `fastapi_restly.pytest_fixtures` provides client and session fixtures with
-savepoint-based isolation. The testing extra auto-loads them as a pytest plugin.
+savepoint-based isolation. Restly registers them as a pytest plugin
+automatically whenever it and pytest are installed.
 
 Install the testing extra when consuming FastAPI-Restly as a package:
 
@@ -379,7 +416,8 @@ def test_create_and_fetch_user(restly_client):
     assert data["name"] == "John"
 ```
 
-Pass `assert_status_code=None` to skip the assertion and inspect the response yourself.
+Pass `assert_status_code=None` to relax the check to any success status (2xx/3xx).
+To inspect an error response, assert its exact code instead (e.g. `assert_status_code=422`).
 
 ## Configuration
 

{fastapi_restly-0.7.0 → fastapi_restly-0.9.0}/README.md

@@ -1,15 +1,26 @@
-# FastAPI-Restly
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rjprins/fastapi-restly/main/docs/_static/fr-wordmark.svg" alt="FastAPI-Restly" width="664">
+</p>
 
-[![CI](https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml)
-[![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)](https://github.com/rjprins/fastapi-restly/blob/main/pyproject.toml)
-[![License](https://img.shields.io/github/license/rjprins/fastapi-restly)](https://github.com/rjprins/fastapi-restly/blob/main/LICENSE)
-[![Coverage](https://www.fastapi-restly.org/coverage/badge.svg)](https://www.fastapi-restly.org/coverage/)
+<p align="center">
+  <a href="https://pypi.org/project/fastapi-restly/"><img src="https://img.shields.io/pypi/v/fastapi-restly" alt="PyPI"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml"><img src="https://github.com/rjprins/fastapi-restly/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/blob/main/pyproject.toml"><img src="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" alt="Python"></a>
+  <a href="https://github.com/rjprins/fastapi-restly/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rjprins/fastapi-restly" alt="License"></a>
+  <a href="https://www.fastapi-restly.org/coverage/"><img src="https://www.fastapi-restly.org/coverage/badge.svg" alt="Coverage"></a>
+</p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rjprins/fastapi-restly/main/docs/_static/restly-cat-white-bg.png" alt="FastAPI-Restly logo" width="200">
+  <a href="https://codespaces.new/rjprins/fastapi-restly?quickstart=1"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces"></a>
 </p>
 
-**Build maintainable REST APIs on FastAPI, SQLAlchemy 2.0, and Pydantic v2 — with real class-based views.**
+<p align="center">
+  Try FastAPI-Restly in your browser: the badge above opens a GitHub Codespace with the dev environment installed, ready to run a live example API.
+</p>
+
+<p align="center">
+  <strong>Build maintainable REST APIs on FastAPI, SQLAlchemy 2.0, and Pydantic v2 — with real class-based views.</strong>
+</p>
 
 > **Status:** public beta release ([changelog](https://github.com/rjprins/fastapi-restly/blob/main/CHANGELOG.md)).
 >
@@ -34,30 +45,28 @@ Its class-based views are real Python classes: use inheritance, mixins, and
 method overrides to share behavior across resources.
 
 - **Class-based views**: group endpoints on Python classes with inheritance and method overrides.
-- **REST endpoints in minutes**: use `View` for custom resources, or `AsyncRestView` / `RestView` for generated CRUD.
+- **REST endpoints in minutes**: use `View` for custom endpoint groups, or `AsyncRestView` / `RestView` for generated CRUD.
 - **Incremental adoption**: use Restly per resource; drop to ordinary FastAPI when needed — see [Existing Project Integration](https://www.fastapi-restly.org/howto_existing_project.html).
 - **Class-level dependencies**: declare shared dependencies once and read their values from `self`.
 - **Explicit override points**: change the route shell, request handler, or business verb.
 - **Filtering, pagination, sorting**: get schema-derived list parameters.
-- **Field control**: `ReadOnly` / `WriteOnly` markers, plus foreign-key validation through `IDRef[...]`.
-- **React Admin ready**: `AsyncReactAdminView` speaks `ra-data-simple-rest`.
+- **Field control**: `ReadOnly` / `WriteOnly` markers, plus foreign-key validation through `MustExist[...]`.
+- **React Admin ready**: `AsyncReactAdminView` / `ReactAdminView` speak `ra-data-simple-rest`.
 - **App utilities**: SQLAlchemy engine/session setup, exception handlers, and test fixtures.
 
-Coming from another CRUD generator? See
-[How Restly compares](https://www.fastapi-restly.org/about.html#how-restly-compares).
-
 ## Quickstart
 
 FastAPI-Restly turns a SQLAlchemy model into a class-based CRUD resource.
-(To make it fully runnable, add dev table creation — see
-[Getting Started](https://www.fastapi-restly.org/getting_started.html).)
+This example is complete and runnable; it creates SQLite tables at startup for
+local development. Use Alembic migrations in production.
 
 ```python
+from contextlib import asynccontextmanager
+
 import fastapi_restly as fr
 from fastapi import FastAPI
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
-app = FastAPI()
 fr.configure(async_database_url="sqlite+aiosqlite:///app.db")
 
 class Base(DeclarativeBase):
@@ -70,6 +79,13 @@ class User(Base):
     name: Mapped[str]
     email: Mapped[str]
 
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    await fr.db.async_create_all(Base)  # dev tables; use Alembic in production
+    yield
+
+app = FastAPI(lifespan=lifespan)
+
 @fr.include_view(app)
 class UserView(fr.AsyncRestView):
     prefix = "/users"
@@ -88,6 +104,10 @@ DELETE /users/{id}   # delete one user
 
 Restly generates the Pydantic schemas automatically.
 
+The Quickstart uses plain SQLAlchemy on purpose — Restly doesn't hide it. In
+real projects you'll usually inherit `fr.IDBase` for models and `fr.IDSchema`
+for schemas, which supply the `id` for you; both appear in the examples below.
+
 ### Not just CRUD
 
 `View` is the same class-based machinery without the generated routes — use it
@@ -107,7 +127,7 @@ class AuthView(fr.View):
     async def logout(self) -> None: ...
 ```
 
-And because views truly subclass, the biggest everyday win takes four lines:
+And because views truly subclass, the biggest everyday win takes only a few lines:
 declare your app's request context once on a base view, and read it from
 `self` everywhere — instead of re-declaring the same `Depends` parameters on
 every function in the project:
@@ -127,7 +147,6 @@ resource, and `RestView` plus custom `@fr.post` methods for CRUD with actions.
 
 Why a `View` over a bare `APIRouter`?
 
-- Shared dependencies are typed attributes you read from `self` (`self.session`, `self.current_user`).
 - Prefix, tags, responses, and dependencies are declared once on the class.
 - Views compose: inheritance and mixins share behavior across endpoint groups.
 - One registration call (`fr.include_view`) per class, bindable to any app or router.
@@ -196,7 +215,7 @@ Use **auto-schema** for prototypes and internal tools. Use an **explicit schema*
 List endpoints expose a stable URL parameter dialect generated from the response schema:
 
 ```bash
-GET /users/?name=John&age__gte=21
+GET /users/?name=John&created_at__gte=2024-01-01
 GET /users/?email__icontains=example
 GET /users/?sort=-created_at&page=2&page_size=10
 ```
@@ -204,8 +223,10 @@ GET /users/?sort=-created_at&page=2&page_size=10
 Parameter keys use the **response schema's public names**, including dotted
 relation paths; unknown keys are rejected with `422`.
 
-Pagination is opt-in: omitting `page_size` returns every matching row. For
-public endpoints, set `default_page_size` and `max_page_size` on the view:
+Pagination is on by default: list endpoints wrap rows in a `data` envelope and
+cap each page at `default_page_size` (50). Clients page with `?page=` and
+`?page_size=`. Tune the default and set a `max_page_size` ceiling on public
+endpoints:
 
 ```python
 class UserView(fr.AsyncRestView):
@@ -229,8 +250,8 @@ class UserRead(fr.IDSchema):
 
 ### Relationship handling
 
-Validate relationships on create and update with `fr.IDRef[...]`.
-Restly passes either the foreign key (`customer_id`) or the related object (`Customer`) to SQLAlchemy, depending on the model constructor.
+Validate a foreign-key column on create and update with `fr.MustExist[int, Model]`.
+It keeps the plain id (`customer_id`) and checks the referenced row exists; declare the relationship (`customer`) separately when you also want the nested object.
 
 ```python
 class Order(fr.IDBase):
@@ -238,7 +259,7 @@ class Order(fr.IDBase):
     customer: Mapped[Customer] = relationship()
 
 class OrderRead(fr.IDSchema):
-    customer_id: fr.IDRef[Customer]
+    customer_id: fr.MustExist[int, Customer]
     customer: fr.ReadOnly[CustomerRead]
 ```
 
@@ -272,8 +293,9 @@ class UploadView(fr.AsyncRestView):
 
 ### React Admin integration
 
-Use `AsyncReactAdminView` for a [react-admin](https://marmelab.com/react-admin/)
-backend compatible with [`ra-data-simple-rest`](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest):
+Use `AsyncReactAdminView` (or `ReactAdminView` for a sync stack) for a
+[react-admin](https://marmelab.com/react-admin/) backend compatible with
+[`ra-data-simple-rest`](https://github.com/marmelab/react-admin/tree/master/packages/ra-data-simple-rest):
 
 ```python
 @fr.include_view(app)
@@ -297,21 +319,35 @@ class UserView(fr.AsyncRestView):
     exclude_routes = (fr.ViewRoute.DELETE,)
 ```
 
-### Pagination metadata
+### List response envelope
+
+List endpoints return a `data` envelope with pagination metadata:
+
+```json
+{"data": [...], "total_count": 123, "page": 1, "page_size": 50, "total_pages": 3}
+```
+
+Set `paginated = False` to return every matching row in a bare `data` envelope
+(no cap, no metadata):
 
 ```python
 @fr.include_view(app)
-class UserView(fr.AsyncRestView):
-    prefix = "/users"
-    model = User
-    include_pagination_metadata = True
-    # Response: {"items": [...], "total": N, "page": 1, "page_size": 100, "total_pages": N, ...}
+class TagView(fr.AsyncRestView):
+    prefix = "/tags"
+    model = Tag
+    paginated = False
+    # Response: {"data": [...]}
 ```
 
+For a different response shape, replace `get_many_endpoint` with a matching
+`response_model`; use `to_listing_response()` inside the replacement when you
+want to reuse the default serialization and page-metadata calculation.
+
 ## Testing
 
 `fastapi_restly.pytest_fixtures` provides client and session fixtures with
-savepoint-based isolation. The testing extra auto-loads them as a pytest plugin.
+savepoint-based isolation. Restly registers them as a pytest plugin
+automatically whenever it and pytest are installed.
 
 Install the testing extra when consuming FastAPI-Restly as a package:
 
@@ -336,7 +372,8 @@ def test_create_and_fetch_user(restly_client):
     assert data["name"] == "John"
 ```
 
-Pass `assert_status_code=None` to skip the assertion and inspect the response yourself.
+Pass `assert_status_code=None` to relax the check to any success status (2xx/3xx).
+To inspect an error response, assert its exact code instead (e.g. `assert_status_code=422`).
 
 ## Configuration
 

{fastapi_restly-0.7.0 → fastapi_restly-0.9.0}/fastapi_restly/__init__.py

@@ -20,6 +20,7 @@ from .schemas import (
     BaseSchema,
     IDRef,
     IDSchema,
+    MustExist,
     ReadOnly,
     TimestampsSchemaMixin,
     WriteOnly,
@@ -51,7 +52,9 @@ from .views import (
 
 try:
     __version__ = _version("fastapi-restly")
-except _PackageNotFoundError:  # pragma: no cover - only possible from an unpackaged tree
+except (
+    _PackageNotFoundError
+):  # pragma: no cover - only possible from an unpackaged tree
     __version__ = "0+unknown"
 
 # Public API surface for fastapi-restly.
@@ -78,6 +81,7 @@ __all__ = [
     "BaseSchema",
     "IDRef",
     "IDSchema",
+    "MustExist",
     "ReadOnly",
     "WriteOnly",
     "TimestampsSchemaMixin",
@@ -100,3 +104,13 @@ __all__ = [
     "patch",
     "delete",
 ]
+
+
+def __getattr__(name: str):
+    # ``fr.testing`` on demand: importing it eagerly would drag the HTTP test
+    # client (and httpx) into every production import of fastapi_restly.
+    if name == "testing":
+        import fastapi_restly.testing as testing_module
+
+        return testing_module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{fastapi_restly-0.7.0 → fastapi_restly-0.9.0}/fastapi_restly/_exception_handlers.py

@@ -15,8 +15,8 @@ registering their own handler for ``IntegrityError`` *before* the framework
 gets a chance to install one.
 
 The detail-message extraction is best-effort: it understands the most common
-PostgreSQL SQLSTATE codes (via psycopg's ``orig.pgcode``) and the SQLite
-error-message conventions. For unrecognised dialects/messages we fall back
+PostgreSQL SQLSTATE codes (via ``orig.sqlstate`` / ``orig.pgcode``) and the
+SQLite error-message conventions. For unrecognised dialects/messages we fall back
 to a generic conflict message that includes a truncated version of the
 underlying error text.
 """
@@ -61,11 +61,13 @@ _PG_SQLSTATE_DETAILS: dict[str, str] = {
 def _extract_postgres_detail(orig: Any) -> str | None:
     """Return a user-facing detail message for a Postgres-driver error.
 
-    Looks at ``orig.pgcode`` (set by psycopg / psycopg2 / asyncpg-via-psycopg)
-    and, when available, ``orig.diag.constraint_name`` /
-    ``orig.diag.column_name`` to enrich the message.
+    Reads the SQLSTATE code and, when psycopg's ``orig.diag`` is present, its
+    ``constraint_name`` / ``column_name`` to enrich the message. The attribute
+    holding the code differs by driver: psycopg 3 exposes ``sqlstate``, psycopg 2
+    exposes ``pgcode`` -- read whichever is present. Reading only ``pgcode``
+    silently degraded every psycopg 3 error to the generic fallback.
     """
-    pgcode = getattr(orig, "pgcode", None)
+    pgcode = getattr(orig, "sqlstate", None) or getattr(orig, "pgcode", None)
     if not pgcode:
         return None
 
@@ -125,7 +127,8 @@ def _build_integrity_detail(exc: IntegrityError) -> str:
 
     Best-effort across dialects:
 
-    * PostgreSQL — switches on ``exc.orig.pgcode`` (SQLSTATE class 23).
+    * PostgreSQL — switches on the SQLSTATE code (``exc.orig.sqlstate`` /
+      ``pgcode``, class 23).
     * SQLite — pattern-matches ``str(exc.orig)`` against known prefixes.
     * Anything else — returns a generic fallback that includes a truncated
       copy of the original error text so the body is still useful for
@@ -189,6 +192,47 @@ def register_default_exception_handlers(app: FastAPI) -> None:
 
     app.add_exception_handler(IntegrityError, integrity_error_handler)
     setattr(app.state, _HANDLERS_INSTALLED_FLAG, True)
+    _register_on_built_stack(app)
+
+
+def _register_on_built_stack(app: FastAPI) -> None:
+    """Also register on an application that has already been called.
+
+    Starlette builds its middleware stack on the first call and the stack caches
+    the handler map, so a view registered after that would leave this handler out
+    and an ``IntegrityError`` would surface as a 500. Entering a test client to
+    run the lifespan is enough to build it.
+
+    Reach the ``ExceptionMiddleware`` already in the stack rather than discarding
+    the stack to force a rebuild: rebuilding constructs every user middleware
+    again, dropping whatever state the live instances hold, and it would briefly
+    disarm Starlette's own "cannot add middleware after startup" check.
+    """
+    stack = getattr(app, "middleware_stack", None)
+    if stack is None:
+        return
+
+    from starlette.middleware.exceptions import ExceptionMiddleware
+
+    node: Any = stack
+    while node is not None:
+        if isinstance(node, ExceptionMiddleware):
+            node.add_exception_handler(IntegrityError, integrity_error_handler)
+            return
+        node = getattr(node, "app", None)
+
+    import warnings
+
+    # A middleware that stores its wrapped app under another name ends the walk.
+    # Rare, but the alternative is unexplained 500s on late-registered views.
+    warnings.warn(
+        "Restly could not reach Starlette's ExceptionMiddleware on the built "
+        "middleware stack: a middleware in the chain does not expose its "
+        "wrapped app as `.app`. Views registered after the application first "
+        "ran will surface IntegrityError as a 500 rather than a 409.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
 
 
 __all__ = ["integrity_error_handler", "register_default_exception_handlers"]