didactic-fastapi 0.1.0__tar.gz

didactic_fastapi-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# dev-only working notes, design drafts, scratch
+notes/
+
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# virtualenvs
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# type-checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# mkdocs build output
+site/
+
+# editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# os
+.DS_Store
+Thumbs.db

didactic_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: didactic-fastapi
+Version: 0.1.0
+Summary: FastAPI integration for didactic Models.
+Author-email: Aaron Steven White <aaronstevenwhite@gmail.com>
+License-Expression: MIT
+Keywords: didactic,fastapi,openapi,panproto
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: didactic
+Requires-Dist: didactic-pydantic
+Requires-Dist: fastapi>=0.115
+Description-Content-Type: text/markdown
+
+# didactic-fastapi
+
+FastAPI integration for `dx.Model` types. Contributes
+`didactic.fastapi` to the namespace package.
+
+## Install
+
+```sh
+pip install didactic-fastapi
+```
+
+The package depends on `didactic`, `didactic-pydantic`, and
+`fastapi>=0.115`.
+
+## Usage
+
+```python
+import didactic.api as dx
+from fastapi import FastAPI
+from didactic.fastapi import as_response, register_validation_handler
+
+
+class User(dx.Model):
+    id: str
+    email: str
+
+
+app = FastAPI()
+register_validation_handler(app)
+
+
+@app.get("/users/{uid}", response_model=as_response(User))
+def get_user(uid: str) -> User:
+    return User(id=uid, email="ada@example.org")
+```
+
+`as_response(model)` returns a `pydantic.BaseModel` subclass
+mirroring the input `dx.Model`. FastAPI uses the result for response
+validation and OpenAPI generation. The conversion is cached per input
+class.
+
+`as_request(model)` is a synonym; use whichever name reads naturally
+in your route signatures.
+
+`register_validation_handler(app)` installs an exception handler so
+that `dx.ValidationError` raised inside a route surfaces as a 422
+response shaped like FastAPI's own validation errors.
+
+## Documentation
+
+See [Guides > FastAPI](https://panproto.dev/didactic/guide/fastapi/)
+for the full integration guide and caveats.
+
+## License
+
+MIT.

didactic_fastapi-0.1.0/README.md

@@ -0,0 +1,56 @@
+# didactic-fastapi
+
+FastAPI integration for `dx.Model` types. Contributes
+`didactic.fastapi` to the namespace package.
+
+## Install
+
+```sh
+pip install didactic-fastapi
+```
+
+The package depends on `didactic`, `didactic-pydantic`, and
+`fastapi>=0.115`.
+
+## Usage
+
+```python
+import didactic.api as dx
+from fastapi import FastAPI
+from didactic.fastapi import as_response, register_validation_handler
+
+
+class User(dx.Model):
+    id: str
+    email: str
+
+
+app = FastAPI()
+register_validation_handler(app)
+
+
+@app.get("/users/{uid}", response_model=as_response(User))
+def get_user(uid: str) -> User:
+    return User(id=uid, email="ada@example.org")
+```
+
+`as_response(model)` returns a `pydantic.BaseModel` subclass
+mirroring the input `dx.Model`. FastAPI uses the result for response
+validation and OpenAPI generation. The conversion is cached per input
+class.
+
+`as_request(model)` is a synonym; use whichever name reads naturally
+in your route signatures.
+
+`register_validation_handler(app)` installs an exception handler so
+that `dx.ValidationError` raised inside a route surfaces as a 422
+response shaped like FastAPI's own validation errors.
+
+## Documentation
+
+See [Guides > FastAPI](https://panproto.dev/didactic/guide/fastapi/)
+for the full integration guide and caveats.
+
+## License
+
+MIT.

didactic_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "didactic-fastapi"
+version = "0.1.0"
+description = "FastAPI integration for didactic Models."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [
+    { name = "Aaron Steven White", email = "aaronstevenwhite@gmail.com" },
+]
+keywords = ["fastapi", "didactic", "openapi", "panproto"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "didactic",
+    "didactic-pydantic",
+    "fastapi>=0.115",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/didactic/fastapi"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/didactic/fastapi"]
+sources = ["src"]

didactic_fastapi-0.1.0/src/didactic/fastapi/__init__.py

@@ -0,0 +1,33 @@
+"""didactic-fastapi: FastAPI integration for didactic Models.
+
+Top-level surface:
+
+[as_request][didactic.fastapi.as_request]
+    Wrap a [didactic.api.Model][didactic.api.Model] as a FastAPI-friendly
+    request body type. Calls
+    [didactic.pydantic.to_pydantic][didactic.pydantic.to_pydantic]
+    under the hood.
+[as_response][didactic.fastapi.as_response]
+    The same conversion for response models. Synonymous with
+    [as_request][didactic.fastapi.as_request]; provided as a
+    separate name so route signatures read naturally.
+[register_validation_handler][didactic.fastapi.register_validation_handler]
+    Install an exception handler that turns
+    [didactic.api.ValidationError][didactic.api.ValidationError] into a 422
+    response shaped like FastAPI's own validation errors.
+"""
+
+from didactic.fastapi._adapter import (
+    as_request,
+    as_response,
+    register_validation_handler,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "as_request",
+    "as_response",
+    "register_validation_handler",
+]

didactic_fastapi-0.1.0/src/didactic/fastapi/_adapter.py

@@ -0,0 +1,100 @@
+"""didactic Model -> FastAPI route adapter.
+
+The adapter is a thin layer over
+[didactic.pydantic.to_pydantic][didactic.pydantic.to_pydantic]: each
+``dx.Model`` is converted to a Pydantic ``BaseModel`` once, cached,
+and reused on every request. The cache is keyed by the source class
+so the conversion only happens once per Model regardless of how many
+routes reference it.
+
+See Also
+--------
+didactic.pydantic.to_pydantic : the underlying converter.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from didactic.pydantic import to_pydantic
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    import didactic.api as dx
+    from fastapi import FastAPI
+
+
+# cache the conversion so each Model maps to the same Pydantic class
+_CACHE: dict[type, type] = {}
+
+
+def as_request[M: dx.Model](model: type[M]) -> type[BaseModel]:
+    """Return the Pydantic adapter for use as a FastAPI request body type.
+
+    Parameters
+    ----------
+    model
+        A [didactic.api.Model][didactic.api.Model] subclass.
+
+    Returns
+    -------
+    type
+        A Pydantic ``BaseModel`` subclass mirroring ``model``'s shape.
+        Cached: subsequent calls with the same ``model`` return the
+        same class.
+    """
+    if model not in _CACHE:
+        _CACHE[model] = to_pydantic(model)
+    return _CACHE[model]
+
+
+def as_response[M: dx.Model](model: type[M]) -> type[BaseModel]:
+    """Synonym of [as_request][didactic.fastapi.as_request].
+
+    Provided as a separate name so route signatures read naturally
+    (``response_model=as_response(User)``).
+    """
+    return as_request(model)
+
+
+def register_validation_handler(app: FastAPI) -> None:
+    """Install a 422 handler for ``dx.ValidationError``.
+
+    Parameters
+    ----------
+    app
+        The FastAPI application to attach the handler to.
+
+    Notes
+    -----
+    The response shape mirrors FastAPI's own validation-error format,
+    so existing clients see no change. didactic's per-error
+    ``loc``/``type``/``msg`` map onto FastAPI's identical names.
+    """
+    import didactic.api as dx_module  # noqa: PLC0415
+    from fastapi import Request  # noqa: PLC0415
+    from fastapi.responses import JSONResponse  # noqa: PLC0415
+
+    # ``_handler`` is registered with the app via the decorator side
+    # effect; the local binding is not used directly afterwards. The
+    # explicit ``del`` makes the intent obvious and silences pyright's
+    # ``reportUnusedFunction`` warning.
+    @app.exception_handler(dx_module.ValidationError)
+    async def _handler(_: Request, exc: dx_module.ValidationError) -> JSONResponse:
+        body = {
+            "detail": [
+                {"loc": list(entry.loc), "msg": entry.msg, "type": entry.type}
+                for entry in exc.entries
+            ],
+        }
+        return JSONResponse(status_code=422, content=body)
+
+    del _handler
+
+
+__all__ = [
+    "as_request",
+    "as_response",
+    "register_validation_handler",
+]