fastapi-runner 0.0.0__tar.gz

fastapi_runner-0.0.0/.gitignore

@@ -0,0 +1,7 @@
+.*
+/build
+/dist
+!/.github
+!/.gitignore
+!/.pre-commit-config.yaml
+!/.python-version

fastapi_runner-0.0.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: fastapi-runner
+Version: 0.0.0
+Summary: Production-ready uvicorn runner for FastAPI applications
+Author-email: Dave Shawley <daveshawley@gmail.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi~=0.143.0
+Requires-Dist: pydantic-settings~=2.14
+Requires-Dist: pydantic~=2.13
+Description-Content-Type: text/markdown
+
+# fastapi-runner
+
+`fastapi-runner` provides shared FastAPI application setup and a Uvicorn
+application factory. It keeps cross-cutting behavior in a reusable library
+while the application package owns its routes and application-specific
+lifecycle hooks.
+
+This package is a member of the repository's uv workspace, but it is otherwise
+freestanding: its package metadata, source tree, tests, and README are all
+under this directory. It can be built as its own source distribution and wheel
+for a future PyPI release.
+
+## Application discovery
+
+`app_factory()` selects an installed application using the `FASTAPI_RUNNER_APPLICATION`
+environment variable. The value is a Python distribution name, not a module
+path. That distribution must define exactly one `configure` entry point in the
+`fastapi_runner` group and may define a `lifespans` entry point.
+
+For example, an application package can declare:
+
+```toml
+[project.entry-points.fastapi_runner]
+configure = "my_app.app:configure"
+lifespans = "my_app.app:lifespans"
+```
+
+The hooks are called as follows:
+
+- `configure(app)` registers routes and other application-specific behavior.
+- `lifespans()` yields async context-manager hooks for startup and shutdown.
+- Each lifespan hook may accept no arguments or the `FastAPI` application.
+
+Run the generic factory with Uvicorn:
+
+```console
+FASTAPI_RUNNER_APPLICATION=my-app uvicorn \
+  --factory fastapi_runner.entrypoint:app_factory
+```
+
+The distribution named by `FASTAPI_RUNNER_APPLICATION` and `fastapi-runner` must both be
+installed in the environment.
+
+## Creating an application directly
+
+Applications and tests that do not need distribution-based discovery can use
+`create_app()` directly:
+
+```python
+from collections import abc
+
+import fastapi
+import fastapi_runner.entrypoint
+import fastapi_runner.lifespan
+
+
+def configure(app: fastapi.FastAPI) -> None:
+    """Add application-specific behavior."""
+
+
+def lifespans() -> abc.Generator[fastapi_runner.lifespan.LifespanHook]:
+    """Yield the application lifespan hooks."""
+
+
+app = fastapi_runner.entrypoint.create_app(
+    configure=configure,
+    lifespan_generator=lifespans,
+)
+```
+
+Both entry points install the same shared application behavior:
+
+- CORS middleware configured through the `FASTAPI_RUNNER_CORS_` environment prefix;
+- problem-detail responses for HTTP and validation errors;
+- an application state hook for customizing problem-detail bodies;
+- access logging, with the documentation routes excluded by default; and
+- a composable lifespan for application startup and shutdown hooks.
+
+Applications can use `fastapi_runner.lifespan.LifespanMap` as a FastAPI
+dependency to retrieve the value returned by a registered lifespan hook:
+
+```python
+import contextlib
+import typing as t
+
+import fastapi
+
+from fastapi_runner.lifespan import LifespanMap
+
+
+class State:
+    """State that is maintained for the application lifetime."""
+
+
+@contextlib.asynccontextmanager
+async def state_lifespan() -> t.AsyncGenerator[State]:
+    yield State()
+
+
+def get_state(*, lifespan: LifespanMap) -> t.Any:
+    return lifespan.get_state(state_lifespan)
+
+
+def status(*, state: t.Annotated[State, fastapi.Depends(get_state)]) -> State:
+    return state
+```
+
+The application may raise `fastapi_runner.errors.ProblemDetailError` when it
+needs to provide a complete problem-detail document. The default error
+handlers also allow an application to update the generated body through the
+`fastapi_runner_error_updater` callback on `app.state`.
+
+Use `fastapi_runner.middleware.disable_access_log` on an endpoint when its
+requests should not produce an access-log record.
+
+## Deployment
+
+The `dave-shawley/fastapi-builder` image is a suitable base image for deploying
+applications built using `fastapi-runner`. The _packaging/Dockerfile_ contains
+a multi-stage build that uses `fastapi-runner` to build the application and then
+copies the resulting artifacts into a minimal image. You should use a similar
+approach when deploying your application.
+
+The included Dockerfile also includes support for running the application with
+opentelemetry enabled though you will need to configure the exporter. I use
+opentelemetry-instrument to automatically instrument the application process.
+You simply need to include additional instrumentation libraries like
+[opentelemetry-instrumentation-psycopg] and the instrument command will pick it
+up and instrument the process.
+
+[opentelemetry-instrumentation-psycopg]: https://pypi.org/project/opentelemetry-instrumentation-psycopg/
+
+### Logging
+
+The default logging configuration is based on the [Common Logging Format](https://en.wikipedia.org/wiki/Common_Log_Format).
+The `fastapi_runner.middleware.AccessLogMiddleware` uses the logger named
+`api-runner.access` to log access records. I decided to push the field configuration
+into the logging configuration (see packaging/log-config.json) though I may change
+that in the future depending on ergonomics. The current implemention creates a log
+record with he following custom fields that are accessed using `%(name)s` in the
+format record.
+
+| Field              | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `%(bytes_sent)s`   | Number of bytes sent in the response              |
+| `%(client)s`       | Formatted client address                          |
+| `%(duration)s`     | Formatted duration of the request in milliseconds |
+| `%(http_version)s` | HTTP version                                      |
+| `%(method)s`       | HTTP request method                               |
+| `%(path)s`         | Request path                                      |
+| `%(status_code)s`  | Numeric status code or `-`                        |
+| `%(user_agent)s`   | User agent string or `-`                          |
+
+The formatted lines as configured by _packaging/log-config.json_ look like:
+
+```
+2026-10-08 11:44:26,328 WARNING api-runner.access: 192.168.215.1:52540 - "GET /missing HTTP/1.1" 404 22
+```
+
+I moved the date out of the log message so that it fits into the general log format.
+You can customize the message format to fit your needs by adjusting the formatter
+attached to the `api-runner.access` logger.
+
+The `FASTAPI_RUNNER_ACCESS_LOG` environment variable can be set to `no` to disable
+access logging. There is currently no way to change the access logger name.
+
+## Development
+
+From the repository root, the shared justfile provides the normal development
+commands:
+
+```console
+just test
+just analyze
+just format
+```
+
+Run only this library's tests directly when iterating on the package:
+
+```console
+uv run --package fastapi-runner pytest libraries/fastapi-runner/tests -q
+```
+
+Build its release artifacts from the repository root:
+
+```console
+uv build --package=fastapi-runner --sdist --wheel --clear
+```
+
+The artifacts are placed in the repository's `dist/` directory. Publishing is
+intentionally separate from the development recipes so each library can adopt
+its own release and PyPI workflow.

fastapi_runner-0.0.0/README.md

@@ -0,0 +1,192 @@
+# fastapi-runner
+
+`fastapi-runner` provides shared FastAPI application setup and a Uvicorn
+application factory. It keeps cross-cutting behavior in a reusable library
+while the application package owns its routes and application-specific
+lifecycle hooks.
+
+This package is a member of the repository's uv workspace, but it is otherwise
+freestanding: its package metadata, source tree, tests, and README are all
+under this directory. It can be built as its own source distribution and wheel
+for a future PyPI release.
+
+## Application discovery
+
+`app_factory()` selects an installed application using the `FASTAPI_RUNNER_APPLICATION`
+environment variable. The value is a Python distribution name, not a module
+path. That distribution must define exactly one `configure` entry point in the
+`fastapi_runner` group and may define a `lifespans` entry point.
+
+For example, an application package can declare:
+
+```toml
+[project.entry-points.fastapi_runner]
+configure = "my_app.app:configure"
+lifespans = "my_app.app:lifespans"
+```
+
+The hooks are called as follows:
+
+- `configure(app)` registers routes and other application-specific behavior.
+- `lifespans()` yields async context-manager hooks for startup and shutdown.
+- Each lifespan hook may accept no arguments or the `FastAPI` application.
+
+Run the generic factory with Uvicorn:
+
+```console
+FASTAPI_RUNNER_APPLICATION=my-app uvicorn \
+  --factory fastapi_runner.entrypoint:app_factory
+```
+
+The distribution named by `FASTAPI_RUNNER_APPLICATION` and `fastapi-runner` must both be
+installed in the environment.
+
+## Creating an application directly
+
+Applications and tests that do not need distribution-based discovery can use
+`create_app()` directly:
+
+```python
+from collections import abc
+
+import fastapi
+import fastapi_runner.entrypoint
+import fastapi_runner.lifespan
+
+
+def configure(app: fastapi.FastAPI) -> None:
+    """Add application-specific behavior."""
+
+
+def lifespans() -> abc.Generator[fastapi_runner.lifespan.LifespanHook]:
+    """Yield the application lifespan hooks."""
+
+
+app = fastapi_runner.entrypoint.create_app(
+    configure=configure,
+    lifespan_generator=lifespans,
+)
+```
+
+Both entry points install the same shared application behavior:
+
+- CORS middleware configured through the `FASTAPI_RUNNER_CORS_` environment prefix;
+- problem-detail responses for HTTP and validation errors;
+- an application state hook for customizing problem-detail bodies;
+- access logging, with the documentation routes excluded by default; and
+- a composable lifespan for application startup and shutdown hooks.
+
+Applications can use `fastapi_runner.lifespan.LifespanMap` as a FastAPI
+dependency to retrieve the value returned by a registered lifespan hook:
+
+```python
+import contextlib
+import typing as t
+
+import fastapi
+
+from fastapi_runner.lifespan import LifespanMap
+
+
+class State:
+    """State that is maintained for the application lifetime."""
+
+
+@contextlib.asynccontextmanager
+async def state_lifespan() -> t.AsyncGenerator[State]:
+    yield State()
+
+
+def get_state(*, lifespan: LifespanMap) -> t.Any:
+    return lifespan.get_state(state_lifespan)
+
+
+def status(*, state: t.Annotated[State, fastapi.Depends(get_state)]) -> State:
+    return state
+```
+
+The application may raise `fastapi_runner.errors.ProblemDetailError` when it
+needs to provide a complete problem-detail document. The default error
+handlers also allow an application to update the generated body through the
+`fastapi_runner_error_updater` callback on `app.state`.
+
+Use `fastapi_runner.middleware.disable_access_log` on an endpoint when its
+requests should not produce an access-log record.
+
+## Deployment
+
+The `dave-shawley/fastapi-builder` image is a suitable base image for deploying
+applications built using `fastapi-runner`. The _packaging/Dockerfile_ contains
+a multi-stage build that uses `fastapi-runner` to build the application and then
+copies the resulting artifacts into a minimal image. You should use a similar
+approach when deploying your application.
+
+The included Dockerfile also includes support for running the application with
+opentelemetry enabled though you will need to configure the exporter. I use
+opentelemetry-instrument to automatically instrument the application process.
+You simply need to include additional instrumentation libraries like
+[opentelemetry-instrumentation-psycopg] and the instrument command will pick it
+up and instrument the process.
+
+[opentelemetry-instrumentation-psycopg]: https://pypi.org/project/opentelemetry-instrumentation-psycopg/
+
+### Logging
+
+The default logging configuration is based on the [Common Logging Format](https://en.wikipedia.org/wiki/Common_Log_Format).
+The `fastapi_runner.middleware.AccessLogMiddleware` uses the logger named
+`api-runner.access` to log access records. I decided to push the field configuration
+into the logging configuration (see packaging/log-config.json) though I may change
+that in the future depending on ergonomics. The current implemention creates a log
+record with he following custom fields that are accessed using `%(name)s` in the
+format record.
+
+| Field              | Description                                       |
+| ------------------ | ------------------------------------------------- |
+| `%(bytes_sent)s`   | Number of bytes sent in the response              |
+| `%(client)s`       | Formatted client address                          |
+| `%(duration)s`     | Formatted duration of the request in milliseconds |
+| `%(http_version)s` | HTTP version                                      |
+| `%(method)s`       | HTTP request method                               |
+| `%(path)s`         | Request path                                      |
+| `%(status_code)s`  | Numeric status code or `-`                        |
+| `%(user_agent)s`   | User agent string or `-`                          |
+
+The formatted lines as configured by _packaging/log-config.json_ look like:
+
+```
+2026-10-08 11:44:26,328 WARNING api-runner.access: 192.168.215.1:52540 - "GET /missing HTTP/1.1" 404 22
+```
+
+I moved the date out of the log message so that it fits into the general log format.
+You can customize the message format to fit your needs by adjusting the formatter
+attached to the `api-runner.access` logger.
+
+The `FASTAPI_RUNNER_ACCESS_LOG` environment variable can be set to `no` to disable
+access logging. There is currently no way to change the access logger name.
+
+## Development
+
+From the repository root, the shared justfile provides the normal development
+commands:
+
+```console
+just test
+just analyze
+just format
+```
+
+Run only this library's tests directly when iterating on the package:
+
+```console
+uv run --package fastapi-runner pytest libraries/fastapi-runner/tests -q
+```
+
+Build its release artifacts from the repository root:
+
+```console
+uv build --package=fastapi-runner --sdist --wheel --clear
+```
+
+The artifacts are placed in the repository's `dist/` directory. Publishing is
+intentionally separate from the development recipes so each library can adopt
+its own release and PyPI workflow.

fastapi_runner-0.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "fastapi-runner"
+version = "0.0.0"
+description = "Production-ready uvicorn runner for FastAPI applications"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BSD-3-Clause"
+authors = [{ name = "Dave Shawley", email = "daveshawley@gmail.com" }]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["fastapi~=0.143.0", "pydantic~=2.13", "pydantic-settings~=2.14"]
+
+[build-system]
+requires = ["hatchling~=1.32"]
+build-backend = "hatchling.build"

fastapi_runner-0.0.0/src/fastapi_runner/__init__.py

@@ -0,0 +1,4 @@
+from importlib import metadata
+
+version = metadata.version('fastapi-runner')
+del metadata

fastapi_runner-0.0.0/src/fastapi_runner/entrypoint.py

@@ -0,0 +1,192 @@
+import contextlib
+import typing as t
+from collections import abc
+from importlib import metadata
+
+import fastapi.exceptions
+import fastapi.middleware.cors
+import pydantic
+import pydantic_settings
+
+from fastapi_runner import error_handling, errors, lifespan, middleware, types
+
+
+class ApplicationSettings(pydantic_settings.BaseSettings):
+    model_config = {'env_prefix': 'FASTAPI_RUNNER_'}
+    application: str
+    access_log: bool = True
+
+
+class CORSSettings(pydantic_settings.BaseSettings):
+    model_config = {'env_prefix': 'FASTAPI_RUNNER_CORS_'}
+    allow_credentials: bool = False
+    allow_headers: list[str] = []
+    allow_methods: list[str] = [
+        'DELETE',
+        'GET',
+        'HEAD',
+        'OPTIONS',
+        'POST',
+        'PUT',
+    ]
+    allow_origins: list[str] = []
+    allow_private_network: bool = False
+    enabled: bool = True
+    expose_headers: list[str] = []
+    max_age: int = 600
+
+
+ConfigHook = abc.Callable[[fastapi.FastAPI], None]
+LifespanGenerator = abc.Callable[[], abc.Generator[lifespan.LifespanHook]]
+
+
+def app_factory() -> fastapi.FastAPI:
+    """Configurable application factory.
+
+    Use this function with `uvicorn` as a factory to create an
+    application instance based on the `APPLICATION` environment
+    variable. It identifies the python distribution to import.
+    The distribution configures `fastapi_runner` entry points
+    named `configure` and (optionally) `lifespans` that match
+    the `ConfigHook` and `LifespanGenerator` types.
+    """
+    settings = _get_application_settings()
+    try:
+        distribution = metadata.distribution(settings.application)
+    except metadata.PackageNotFoundError:
+        raise errors.ApplicationConfigurationError(
+            f'APPLICATION={settings.application!r} does not identify an '
+            'installed Python distribution'
+        ) from None
+
+    configure, lifespan_generator = _load_hooks(distribution)
+
+    return create_app(
+        configure=configure,
+        lifespan_generator=lifespan_generator,
+        enable_access_log=settings.access_log,
+    )
+
+
+def create_app(
+    *,
+    configure: ConfigHook | None = None,
+    lifespan_generator: LifespanGenerator | None = None,
+    enable_access_log: bool = True,
+) -> fastapi.FastAPI:
+    """Create a FastAPI application instance using hooks
+
+    This method creates an application instance using the supplied
+    hooks. In addition to setting up a composable lifespan, the
+    CORS and access logging middlewares are installed and several
+    error handlers are configured.
+
+    Args:
+        configure: A hook that configures the application.
+        lifespan_generator: A generator that yields lifespan hooks.
+        enable_access_log: Enable the access logging middleware?
+
+    Returns:
+        A FastAPI application instance.
+    """
+
+    span = lifespan.Lifespan()
+    if lifespan_generator is not None:
+        for hook in lifespan_generator():
+            span.add_lifespan(hook)
+
+    app = fastapi.FastAPI(lifespan=span, telemetry={'auto_configure': False})
+
+    cors_settings = CORSSettings()
+    if cors_settings.enabled:
+        app.add_middleware(
+            fastapi.middleware.cors.CORSMiddleware,
+            allow_credentials=cors_settings.allow_credentials,
+            allow_headers=cors_settings.allow_headers,
+            allow_methods=cors_settings.allow_methods,
+            allow_origins=cors_settings.allow_origins,
+            allow_private_network=cors_settings.allow_private_network,
+            expose_headers=cors_settings.expose_headers,
+            max_age=cors_settings.max_age,
+        )
+
+    # Overrideable to customize error document creation.
+    state = t.cast('types.AppStateShape', app.state)
+    state.fastapi_runner_error_updater = None
+
+    # Add custom error handlers for specific exception
+    # types BEFORE invoking the application level configure
+    # so that the app can replace, override, whatever.
+    app.add_exception_handler(
+        fastapi.exceptions.RequestValidationError,
+        error_handling.validation_error_handler,
+    )
+
+    # Let the application configure its routes
+    if configure is not None:
+        configure(app)
+
+    # Add the problem details translator last to ensure that
+    # unexpected exceptions are translated.
+    app.add_exception_handler(
+        fastapi.exceptions.HTTPException,
+        error_handling.problem_details_translator,
+    )
+
+    # The AccessLogMiddleware should ALWAYS be added last
+    if enable_access_log:
+        app.add_middleware(
+            middleware.AccessLogMiddleware,
+            ignored_paths=('/docs', '/openapi.json', '/redoc'),
+        )
+
+    return app
+
+
+def _get_application_settings() -> ApplicationSettings:
+    """Retrieve the application settings or fail with a useful message."""
+    try:
+        return ApplicationSettings()
+    except pydantic.ValidationError as error:
+        prefix = ApplicationSettings.model_config['env_prefix']
+        missing = set[str]()
+        invalid = set[str]()
+        for e in error.errors():
+            if e['type'] == 'missing':
+                missing.add(str(e['loc'][0]))
+            else:
+                invalid.add(str(e['loc'][0]))
+        if missing:
+            names = ' '.join(f'{prefix}{name.upper()}' for name in missing)
+            raise errors.ApplicationConfigurationError(
+                f'Missing required environment variables: {names}'
+            ) from None
+        if invalid:
+            names = ' '.join(f'{prefix}{name.upper()}' for name in invalid)
+            raise errors.ApplicationConfigurationError(
+                f'Invalid environment variables: {names}'
+            ) from None
+        raise errors.ApplicationConfigurationError(
+            'Unknown error loading application settings'
+        ) from None  # pragma: no cover -- paranoia
+
+
+def _load_hooks(
+    distribution: metadata.Distribution,
+) -> tuple[ConfigHook, LifespanGenerator | None]:
+    entry_points = distribution.entry_points.select(group='fastapi_runner')
+    num_eps = len(entry_points.select(name='configure'))
+    if num_eps != 1:
+        raise ValueError(
+            f'Expected exactly one configure entrypoint in fastapi_runner'
+            f' group, but found {num_eps} in {distribution.name!r}'
+        )
+
+    configure = t.cast('ConfigHook', entry_points['configure'].load())
+    lifespan_generator: LifespanGenerator | None = None
+    with contextlib.suppress(KeyError):
+        lifespan_generator = t.cast(
+            'LifespanGenerator', entry_points['lifespans'].load()
+        )
+
+    return configure, lifespan_generator