<img src="hawk-logo.png" alt="Hawk" width="400">

<a href="https://github.com/ashimov/Hawk/actions"><img src="https://github.com/ashimov/Hawk/actions/workflows/ci.yml/badge.svg" alt="CI"></a>

<a href="https://github.com/ashimov/Hawk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ashimov/Hawk.svg" alt="License"></a>

<a href="https://github.com/ashimov/Hawk"><img src="https://img.shields.io/badge/coverage-95%25-brightgreen.svg" alt="Coverage"></a>

pip install hawkapi[uvicorn] # Uvicorn ASGI server

pip install hawkapi[pydantic] # Optional Pydantic v2 support

pip install hawkapi[metrics] # Prometheus metrics

pip install hawkapi[logging] # Structured logging (structlog)

pip install hawkapi[grpc] # gRPC support (grpcio + grpcio-reflection)

**Requirements:** Python 3.12+ (3.13 fully supported; experimental free-threaded 3.13t wheels are shipped — see [Free-threaded Python](#free-threaded-python-313)) and msgspec >= 0.19.0.

Side-effect dependencies (auth guards, audit writers) that run before the handler — return values are discarded; `HTTPException` short-circuits the request:

from hawkapi import Depends

async def audit(request): ...

@app.get("/admin", dependencies=[Depends(audit)])

async def admin(): ...

Router-level is also supported: `Router(dependencies=[Depends(audit)])`.

**Auto-inference from return annotation** — `response_model` is inferred automatically when not set explicitly:

@app.get("/users/{id}")

async def get_user(id: int) -> UserOut: # response_model inferred automatically

return await db.get(id)

**Exclusion flags** — strip `None`, unset, or default-value fields from serialized output:

@app.get("/users/{id}", response_model_exclude_none=True, response_model_exclude_unset=True)

async def get_user(id: int) -> UserOut: ...

Flags: `response_model_exclude_none`, `response_model_exclude_unset`, `response_model_exclude_defaults`.

| `RedisCircuitBreakerMiddleware` | Distributed circuit breaker (Redis-backed) |

| `AdaptiveConcurrencyMiddleware` | Adaptive in-flight limit based on latency |

See also: [Bulkhead](#bulkhead) — named async concurrency isolator living in `hawkapi.middleware.bulkhead`.

Fine-grained scope enforcement with OpenAPI `operation.security` reflection:

from hawkapi import OAuth2PasswordBearer, Security, SecurityScopes

oauth2 = OAuth2PasswordBearer(

tokenUrl="token",

scopes={"items:read": "Read items", "items:write": "Write items"},

)

async def current_user(scopes: SecurityScopes, token: str = Security(oauth2)): ...

@app.get("/items", dependencies=[Security(current_user, scopes=["items:read"])])

async def read_items(): ...

Route-level scopes are aggregated into the OpenAPI `operation.security` field automatically.

Use `hawkapi.status` for named HTTP and WebSocket constants (FastAPI parity):

from hawkapi import status

raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)

Both HTTP (`status.HTTP_200_OK`, `status.HTTP_422_UNPROCESSABLE_ENTITY`, …) and WebSocket (`status.WS_1008_POLICY_VIOLATION`, …) constants are available.

Runtime feature flags with zero external dependencies. Providers are swappable without restarting the app:

from hawkapi import HawkAPI, Depends

from hawkapi.flags import StaticFlagProvider, Flags, get_flags, requires_flag

app = HawkAPI(flags=StaticFlagProvider({"new_checkout": True}))

@app.get("/checkout")

async def checkout(flags: Flags = Depends(get_flags)) -> dict:

if await flags.bool("new_checkout", default=False):

return await new_flow()

return await old_flow()

@app.get("/beta/reports")

@requires_flag("beta.reports")

async def beta_reports() -> dict: ...

Providers: `StaticFlagProvider`, `EnvFlagProvider`, `FileFlagProvider` (JSON/TOML/YAML with mtime hot-reload). Use when you need to gate features per environment or roll out incrementally without a deployment. See [docs/guide/feature-flags.md](docs/guide/feature-flags.md).

Thin GraphQL-over-HTTP adapter with GraphiQL UI served to browsers. Zero runtime deps on the default path — `graphql-core` and `strawberry` are imported lazily only when the adapter is used:

from hawkapi.graphql.adapters import from_graphql_core

from graphql import build_schema

schema = build_schema("type Query { hello: String }")

app.mount_graphql("/graphql", executor=from_graphql_core(schema))

Adapters: `from_graphql_core`, `from_strawberry`. Use when you need a GraphQL API alongside REST without adding a separate framework. See [docs/guide/graphql.md](docs/guide/graphql.md).

Thin gRPC integration with ASGI lifespan-tied lifecycle — the gRPC server starts and stops with the app:

from myproto import greeter_pb2_grpc

class Greeter(greeter_pb2_grpc.GreeterServicer):

async def SayHello(self, request, context):

app = context.hawkapi_app # access app state

...

app.mount_grpc(

Greeter(),

add_to_server=greeter_pb2_grpc.add_GreeterServicer_to_server,

port=50051,

reflection=True,

reflection_service_names=["greeter.Greeter"],

)

Built-in `HawkAPIObservabilityInterceptor` adds structured logs and Prometheus metrics to every RPC. TLS via `ssl_credentials=`. Install: `pip install hawkapi[grpc]`. Use when you need gRPC and HTTP APIs from a single process. See [docs/guide/grpc.md](docs/guide/grpc.md).

Named async concurrency isolator — caps simultaneous in-flight requests per named pool to prevent one slow resource from exhausting the entire process:

from hawkapi.middleware.bulkhead import bulkhead

@app.get("/export")

@bulkhead("exports", max_concurrent=4)

async def export(): ...

Context-manager form also supported. Backends: `LocalBulkheadBackend` (default, `asyncio.Semaphore` per name) and `RedisBulkheadBackend` (distributed, hash + lease-TTL). Optional Prometheus metrics. Use when you need hard concurrency caps per operation type. See [docs/guide/bulkhead.md](docs/guide/bulkhead.md).

HawkAPI ships experimental `cp313t-cp313t` wheels built via cibuildwheel for the no-GIL CPython 3.13 free-threaded build (PEP 703):

from hawkapi._threading import FREE_THREADED, maybe_thread_lock, maybe_async_lock

lock = maybe_thread_lock() # real threading.Lock on 3.13t, no-op elsewhere

alock = maybe_async_lock() # real asyncio.Lock on 3.13t, no-op elsewhere

`maybe_thread_lock()` and `maybe_async_lock()` let library code be PEP 703-aware without branching on every call site. Use when running HawkAPI under `python3.13t` for CPU-bound workloads that benefit from true parallelism. See [docs/guide/free-threaded.md](docs/guide/free-threaded.md).

hawkapi diff old_app:app new_app:app

hawkapi changelog old_app:app new_app:app

hawkapi gen-client --app app:app --lang typescript --out ./client

hawkapi gen-client --app app:app --lang python --out ./client

hawkapi migrate path/to/fastapi_project

hawkapi migrate path/to/fastapi_project --dry-run # preview diffs only

hawkapi migrate path/to/fastapi_project --convert-models # also rewrite Pydantic BaseModel → msgspec.Struct

hawkapi migrate path/to/fastapi_project --output ./migrated # write to separate directory

`hawkapi gen-client` generates a zero-dependency client: native `fetch` for TypeScript, msgspec-backed for Python. Source can be a live app (`--app module:attr`) or a saved spec file (`--spec openapi.json`).

`hawkapi migrate` uses AST rewriting (libcst) to replace FastAPI imports, decorators, and patterns with their HawkAPI equivalents. See [docs/guide/migration-from-fastapi.md](docs/guide/migration-from-fastapi.md).

git clone https://github.com/ashimov/Hawk.git

cd Hawk

git clone https://github.com/ashimov/Hawk.git

[`benchmarks/competitive/RESULTS.md`](https://github.com/ashimov/Hawk/blob/main/benchmarks/competitive/RESULTS.md).

repo_url: https://github.com/ashimov/Hawk

repo_name: ashimov/Hawk

Homepage = "https://github.com/ashimov/Hawk"

Repository = "https://github.com/ashimov/Hawk"