Metadata-Version: 2.4
Name: fastapi-ext-pkg
Version: 0.8.0
Summary: A well-tailored utility set for FastAPI.
Author-email: Dotz Developers <devs-dotz@dotz.com>
Project-URL: Repository, https://github.com/DotzInc/fastapi-ext-pkg
Keywords: fastapi,utilities
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Software Development
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: httpx
Provides-Extra: apm
Requires-Dist: elastic-apm<7,>=6.20; extra == "apm"

# FastAPI Extension Package

![Tests](https://github.com/DotzInc/fastapi-ext-pkg/actions/workflows/tests.yml/badge.svg?event=push)
![PyPI - Version](https://img.shields.io/pypi/v/fastapi-ext-pkg)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastapi-ext-pkg)

A well-tailored utility set for FastAPI.

## Requirements

* Python 3.8+

## Installation

To install FastAPI Extension Package, use pip:

```sh
pip install fastapi-ext-pkg
```

## Shared middleware configuration

`configure_middlewares` registers middleware on an existing FastAPI application
before startup. Configure service values centrally while preserving routers and
lifespan:

```python
from fastapi_extras.middlewares import configure_middlewares

configure_middlewares(
    app,
    root_path=settings.ROOT_PATH,
    apm_config=settings.ELASTIC_APM,
    cors={"allow_origins": settings.ALLOW_ORIGINS},
)
```

The default registration order is path removal, trace-header removal, APM,
`extra_middlewares`, CORS, then the garbage collector. Incoming requests traverse it in reverse. Use
`order` to preserve a service-specific order; include every configured name
exactly once. `MiddlewareSpec` defines custom middleware and named `overrides`
for replacement or disabling (`enabled=False`).

Use `root_path=None`, `remove_cloud_trace_headers=False`, `apm_enabled=False`,
or `cors=None` to omit middleware. `garbage_collector=True` registers
`GarbageCollectorMiddleware` as the outermost middleware; it is disabled by
default, and a `garbage_collector` override changes its options. Pass either `apm_config` or `apm_client`.
APM uses the upstream `elasticapm.contrib.starlette.ElasticAPM` by default and
requires the optional `[apm]` dependency. This branch contains no custom APM
implementation. To register another implementation supplied by the caller, pass
`apm_middleware_class`; `apm_options` supplies its constructor options.

## Garbage collector middleware

`GarbageCollectorMiddleware` controls garbage collection without a background loop:

* After the application startup, it freezes the startup objects (`gc.freeze()`), so later
  collections skip them.
* Collections are driven by traffic: one runs after `every_requests` requests (default 5000), or
  when the resident memory reaches `max_rss_mb`, never more often than `min_interval_seconds`
  (default 60) plus a per-instance jitter of up to 20%.
* Each collection runs after the response is sent and, on glibc, calls `malloc_trim` to return
  freed memory to the operating system. This is best effort: fragmented `pymalloc` arenas may
  keep the resident memory high.
* Each collection is logged at INFO level with the collected objects, the duration and the
  resident memory before and after.

```python
from fastapi import FastAPI
from fastapi_extras.middlewares.garbage_collector import GarbageCollectorMiddleware

app = FastAPI()
app.add_middleware(GarbageCollectorMiddleware, max_rss_mb=768)
```
