neva-fastapi 1.0.0__tar.gz

neva_fastapi-1.0.0/.envrc

@@ -0,0 +1,2 @@
+export VIRTUAL_ENV="$PWD/.venv"
+layout python

neva_fastapi-1.0.0/.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[ocd]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tests / Coverage / Benchmarks
+htmlcov/
+.coverage
+.pytest_cache/
+.benchmarks/
+profiles/
+
+# LLM Contexts
+llm-context.md
+CLAUDE.md

neva_fastapi-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.6
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        args: [--enable-incomplete-feature=TypeForm]
+        additional_dependencies:
+          [dishka>=1.10.0, "fastapi[all]>=0.129.0", pytest>=9.0.2]

neva_fastapi-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

neva_fastapi-1.0.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+## 1.0.0 (2026-05-11)
+
+### 📌➕⬇️➖⬆️ Dependencies
+
+- update neva dep
+
+## 0.2.1 (2026-05-11)
+
+### 🐛🚑️ Fixes
+
+- remove obsolete parameter in rouetr
+
+### 🏷️ Types
+
+- stub + re-exports
+
+## 0.2.0 (2026-05-06)
+
+### 🔧🔨📦️ Configuration, Scripts, Packages
+
+- update perms on build script
+- config commitizen
+
+## 0.1.0 (2026-05-05)

neva_fastapi-1.0.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: neva-fastapi
+Version: 1.0.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: python-neva>=3.1.0

neva_fastapi-1.0.0/neva/fastapi/__init__.py

@@ -0,0 +1,7 @@
+"""FastAPI integration for Neva."""
+
+from neva.fastapi.app import App, Inject
+from neva.fastapi.router import APIRouter
+
+
+__all__ = ["APIRouter", "App", "Inject"]

neva_fastapi-1.0.0/neva/fastapi/app.py

@@ -0,0 +1,102 @@
+"""Main application class.
+
+This module provides the core App class that extends FastAPI with dependency
+injection. DI is handled by the dependency injection container provided by
+the Application class.
+"""
+
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from dishka import FromDishka
+from dishka.integrations.fastapi import FastapiProvider, setup_dishka
+from neva.arch.application import Application
+from neva.arch.service_provider import ServiceProvider
+from neva.support import Result
+from starlette.middleware import Middleware
+from starlette.routing import BaseRoute
+from starlette.types import Lifespan, StatefulLifespan
+
+import fastapi
+
+
+class App(fastapi.FastAPI):
+    """Main application class extending FastAPI."""
+
+    def __init__(
+        self,
+        *,
+        routes: list[BaseRoute] | None = None,
+        middlewares: Sequence[Middleware] | None = None,
+        lifespan: Lifespan["App"] | None = None,
+        config_path: str | Path | None = None,
+    ) -> None:
+        """Initialize the application.
+
+        Args:
+            routes: List of routes to register with the application.
+            middlewares: Sequence of middleware to apply to the application.
+            lifespan: Custom lifespan context manager for application lifecycle.
+            config_path: Path to the configuration directory. Defaults to "./config"
+                relative to the current working directory.
+
+        """
+        self.application: Application = Application(config_path=config_path)
+        self.application.build_container(FastapiProvider())
+
+        config = self.application.config
+
+        super().__init__(
+            debug=config.get("app.debug", type_=bool).unwrap_or(False),  # noqa: FBT003
+            routes=routes,
+            title=config.get("app.title", type_=str).unwrap_or("Neva Application"),
+            version=config.get("app.version", type_=str).unwrap_or("0.1.0"),
+            openapi_url=config.get("app.openapi_url", type_=str).unwrap_or(
+                "/openapi.json"
+            ),
+            docs_url=config.get("app.docs_url", type_=str).unwrap_or("/docs"),
+            redoc_url=config.get("app.redoc_url", type_=str).unwrap_or("/redoc"),
+            lifespan=self.build_lifespan(custom_lifespan=lifespan),
+            middleware=middlewares,
+        )
+
+        setup_dishka(self.application.container, app=self)
+
+    def register(
+        self,
+        provider: type[ServiceProvider],
+    ) -> Result[ServiceProvider, str]:
+        """Registers a service provider with the application.
+
+        Returns:
+            Result containing the registered provider instance or an error message.
+        """
+        return self.application.register(provider=provider)
+
+    def build_lifespan(
+        self,
+        custom_lifespan: Lifespan["App"] | None = None,
+    ) -> StatefulLifespan["App"]:
+        """Builds a lifespan context manager for the application.
+
+        Returns:
+            the lifespan context manager.
+        """
+
+        @asynccontextmanager
+        async def lifespan(
+            app: "App",
+        ) -> AsyncIterator[Mapping[str, Any]]:
+            async with self.application.lifespan():
+                if custom_lifespan is None:
+                    yield {}
+                else:
+                    async with custom_lifespan(app) as state:
+                        yield state if state is not None else {}
+
+        return lifespan
+
+
+Inject = FromDishka

neva_fastapi-1.0.0/neva/fastapi/fixtures.py

@@ -0,0 +1,31 @@
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from neva.fastapi.app import App
+
+
+@pytest.fixture
+def webapp(test_config: Path) -> App:
+    """Pytest fixture for the HTTP Neva app.
+
+    Returns:
+        App: The Neva application instance.
+    """
+    return App(config_path=test_config)
+
+
+@pytest.fixture
+async def http_client(webapp: App) -> AsyncIterator[AsyncClient]:
+    """An async httpx client to test the application.
+
+    Yields:
+        An async httpx client.
+    """
+    async with AsyncClient(
+        transport=ASGITransport(webapp),
+        base_url="http://localhost:8000",
+    ) as client:
+        yield client

neva_fastapi-1.0.0/neva/fastapi/router.py

@@ -0,0 +1,234 @@
+# ruff: noqa: B008
+from collections.abc import Sequence
+from enum import Enum
+from typing import Annotated, Any, Callable, override
+
+from annotated_doc import Doc
+from dishka.integrations.fastapi import DishkaRoute
+from starlette.routing import BaseRoute
+from starlette.types import ASGIApp, Lifespan
+from typing_extensions import deprecated
+
+import fastapi
+from fastapi import Response, params
+from fastapi.datastructures import Default
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+from fastapi.utils import generate_unique_id
+
+
+class APIRouter(fastapi.APIRouter):
+    """A custom router that integrates dependency injection utilities."""
+
+    @override
+    def __init__(
+        self,
+        *,
+        prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
+        tags: Annotated[
+            list[str | Enum] | None,
+            Doc("""
+                    A list of tags to be applied to all the *path operations* in this
+                    router.
+
+                    It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                    Read more about it in the
+                    [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
+                    """),
+        ] = None,
+        dependencies: Annotated[
+            Sequence[params.Depends] | None,
+            Doc("""
+                    A list of dependencies (using `Depends()`) to be applied to all the
+                    *path operations* in this router.
+
+                    Read more about it in the
+                    [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
+                    """),
+        ] = None,
+        default_response_class: Annotated[
+            type[Response],
+            Doc("""
+                    The default response class to be used.
+
+                    Read more in the
+                    [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
+                    """),
+        ] = Default(JSONResponse),
+        responses: Annotated[
+            dict[int | str, dict[str, Any]] | None,
+            Doc("""
+                    Additional responses to be shown in OpenAPI.
+
+                    It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                    Read more about it in the
+                    [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).
+
+                    And in the
+                    [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
+                    """),
+        ] = None,
+        callbacks: Annotated[
+            list[BaseRoute] | None,
+            Doc("""
+                    OpenAPI callbacks that should apply to all *path operations* in this
+                    router.
+
+                    It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                    Read more about it in the
+                    [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
+                    """),
+        ] = None,
+        routes: Annotated[
+            list[BaseRoute] | None,
+            Doc("""
+                    **Note**: you probably shouldn't use this parameter, it is inherited
+                    from Starlette and supported for compatibility.
+
+                    ---
+
+                    A list of routes to serve incoming HTTP and WebSocket requests.
+                    """),
+            deprecated("""
+                    You normally wouldn't use this parameter with FastAPI, it is
+                    inherited from Starlette and supported for compatibility.
+
+                    In FastAPI, you normally would use the *path operation methods*,
+                    like `router.get()`, `router.post()`, etc.
+                    """),
+        ] = None,
+        redirect_slashes: Annotated[
+            bool,
+            Doc("""
+                    Whether to detect and redirect slashes in URLs when the
+                    client inherited doesn't use the same format.
+                    """),
+        ] = True,
+        default: Annotated[
+            ASGIApp | None,
+            Doc("""
+                    Default function handler for this router. Used to handle
+                    404 Not Found errors.
+                    """),
+        ] = None,
+        dependency_overrides_provider: Annotated[
+            Any | None,
+            Doc("""
+                    Only used internally by FastAPI to handle dependency overrides.
+
+                    You shouldn't need to use it. It normally points to the `FastAPI`
+                    app object.
+                    """),
+        ] = None,
+        on_startup: Annotated[
+            Sequence[Callable[[], Any]] | None,
+            Doc("""
+                    A list of startup event handler functions.
+
+                    You should instead use the `lifespan` handlers.
+
+                    Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
+                    """),
+        ] = None,
+        on_shutdown: Annotated[
+            Sequence[Callable[[], Any]] | None,
+            Doc("""
+                    A list of shutdown event handler functions.
+
+                    You should instead use the `lifespan` handlers.
+
+                    Read more in the
+                    [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
+                    """),
+        ] = None,
+        lifespan: Annotated[
+            Lifespan[Any] | None,
+            Doc("""
+                    A `Lifespan` context manager handler. This replaces `startup` and
+                    `shutdown` functions with a single context manager.
+
+                    Read more in the
+                    [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
+                    """),
+        ] = None,
+        deprecated: Annotated[
+            bool | None,
+            Doc("""
+                    Mark all *path operations* in this router as deprecated.
+
+                    It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+                    Read more about it in the
+                    [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
+                    """),
+        ] = None,
+        include_in_schema: Annotated[
+            bool,
+            Doc("""
+                    To include (or not) all the *path operations* in this router in the
+                    generated OpenAPI.
+
+                    This affects the generated OpenAPI (e.g. visible at `/docs`).
+
+                    Read more about it in the
+                    [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
+                    """),
+        ] = True,
+        generate_unique_id_function: Annotated[
+            Callable[[APIRoute], str],
+            Doc("""
+                    Customize the function used to generate unique IDs for the *path
+                    operations* shown in the generated OpenAPI.
+
+                    This is particularly useful when automatically generating clients or
+                    SDKs for your API.
+
+                    Read more about it in the
+                    [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
+                    """),
+        ] = Default(generate_unique_id),
+        strict_content_type: Annotated[
+            bool,
+            Doc("""
+                    Enable strict checking for request Content-Type headers.
+
+                    When `True` (the default), requests with a body that do not include
+                    a `Content-Type` header will **not** be parsed as JSON.
+
+                    This prevents potential cross-site request forgery (CSRF) attacks
+                    that exploit the browser's ability to send requests without a
+                    Content-Type header, bypassing CORS preflight checks. In particular
+                    applicable for apps that need to be run locally (in localhost).
+
+                    When `False`, requests without a `Content-Type` header will have
+                    their body parsed as JSON, which maintains compatibility with
+                    certain clients that don't send `Content-Type` headers.
+
+                    Read more about it in the
+                    [FastAPI docs for Strict Content-Type](https://fastapi.tiangolo.com/advanced/strict-content-type/).
+                    """),
+        ] = Default(True),  # noqa: FBT003 This is inherited from FastAPI
+    ) -> None:
+        super().__init__(
+            prefix=prefix,
+            tags=tags,
+            dependencies=dependencies,
+            default_response_class=default_response_class,
+            responses=responses,
+            callbacks=callbacks,
+            routes=routes,
+            redirect_slashes=redirect_slashes,
+            default=default,
+            dependency_overrides_provider=dependency_overrides_provider,
+            route_class=DishkaRoute,
+            on_startup=on_startup,
+            on_shutdown=on_shutdown,
+            lifespan=lifespan,
+            deprecated=deprecated,
+            include_in_schema=include_in_schema,
+            generate_unique_id_function=generate_unique_id_function,
+            # strict_content_type=strict_content_type,
+        )

neva_fastapi-1.0.0/pyproject.toml

@@ -0,0 +1,76 @@
+[project]
+name = "neva-fastapi"
+dynamic = ["version"]
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["python-neva>=3.1.0"]
+
+[dependency-groups]
+dev = [
+  "bandit>=1.9.2",
+  "commitizen>=4.15.0",
+  "cz-conventional-gitmoji>=0.7.0",
+  "mypy>=1.19.1",
+  "poethepoet>=0.38.0",
+  "polyfactory>=3.1.0",
+  "pre-commit>=4.5.0",
+  "pytest>=9.0.2",
+  "pytest-asyncio>=0.25.3",
+  "pytest-benchmark>=5.2.3",
+  "pytest-cov>=7.0.0",
+  "ruff>=0.15.6",
+]
+
+[build-system]
+requires = ["hatchling", "versioningit"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["neva"]
+
+[tool.hatch.version]
+source = "versioningit"
+
+[tool.hatch.version.format]
+distance = "{base_version}.dev{distance}+{vcs}{rev}"
+dirty = "{version}+dirty"
+distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty"
+
+[tool.commitizen]
+name = "cz_gitmoji"
+version_provider = "scm"
+tag_format = "$version"
+version_scheme = "pep440"
+update_changelog_on_bump = true
+annotated_tag = true
+post_bump_hooks = ["scripts/retag-with-changelog.sh"]
+
+[tool.uv.sources]
+python-neva = { path = "../neva", editable = true }
+
+[tool.basedpyright]
+enableExperimentalFeatures = true
+
+[tool.mypy]
+enable_incomplete_feature = ["TypeForm"]
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+
+[tool.poe.tasks]
+# Code quality
+ruff = "uv run ruff"
+mypy = "uv run mypy"
+lint = "poe ruff check"
+fmt = "poe ruff format"
+tc = "poe mypy ."
+
+# Testing
+test = "pytest"
+test-cov = "poe test --cov=neva --cov-report=term-missing"
+test-full = "poe test-cov tests/"

neva_fastapi-1.0.0/ruff.toml

@@ -0,0 +1,42 @@
+target-version = "py312"
+line-length = 88
+
+[lint]
+select = [
+  "FAST",
+  "ANN",
+  "ASYNC",
+  "S",
+  "FBT",
+  "B",
+  "A",
+  "C4",
+  "DTZ",
+  "ISC",
+  "ICN",
+  "SIM",
+  "SLOT",
+  "I",
+  "E",
+  "W",
+  "DOC",
+  "D",
+  "F",
+  "RUF",
+]
+preview = true
+ignore = [
+  "D100",   # Allow missing docstrings in public modules
+  "D107",   # Allow missing docstrings in __init__
+  "RUF029",
+]
+
+[lint.per-file-ignores]
+"tests/*" = ["D", "S101"]
+
+[lint.isort]
+force-single-line = false
+lines-after-imports = 2
+
+[lint.pydocstyle]
+convention = "google"

neva_fastapi-1.0.0/scripts/retag-with-changelog.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env sh
+set -e
+
+TAG="${CZ_POST_CURRENT_VERSION}"
+
+# Generate the changelog section for this version only
+CHANGELOG=$(cz changelog "${CZ_POST_CURRENT_VERSION}" --dry-run |
+  sed 's/^### *//' |
+  sed 's/^## *//' |
+  sed 's/\*\*//g' |
+  sed 's/`//g' |
+  sed 's/\[.\+\](\(.\+\))/\1/g')
+
+# Replace the tag cz just created with an annotated one carrying the changelog
+git tag -d "$TAG"
+git tag -a "$TAG" -m "$CHANGELOG"

neva_fastapi-1.0.0/tests/config/app.py

@@ -0,0 +1,6 @@
+config = {
+    "title": "TestApp",
+    "openapi_url": None,
+    "debug": 0,
+    "environment": "testing",
+}

neva_fastapi-1.0.0/tests/conftest.py

@@ -0,0 +1 @@
+pytest_plugins = ["neva.fastapi.fixtures"]

neva_fastapi-1.0.0/tests/test_fixture.py

@@ -0,0 +1,15 @@
+from pathlib import Path
+
+from neva.testing import TestCase
+from pytest import fixture
+
+from neva.fastapi.app import App
+
+
+class TestWebApp(TestCase):
+    @fixture
+    def test_config(self, tmp_path: Path) -> Path:
+        return Path(__file__).parent / "config"
+
+    def test_webapp(self, webapp: App) -> None:
+        assert isinstance(webapp, App)