How neoteroi/blacksheep works
Project type and purpose
• BlackSheep is an asynchronous Python web framework (an ASGI library)
plus an optional HTTP client.
• It is not a monolithic application, but a library intended to be embedded
in user code and run under an ASGI server (e.g. uvicorn or hypercorn).
• Key features (from README): routing, middleware pipeline, dependency injection,
authentication/authorization, OpenAPI generation, WebSockets, SSE, static‐file
serving, templating (Jinja2), sessions, plus an HTTP client.
File structure
• Top-level “blacksheep” package subdivided into:
– server: ASGI adapter, application entrypoint, routing, controllers,
authentication (cookie, JWT, OIDC), authorization policies, CORS, CSRF,
compression, dataprotection, diagnostics, files (static/dynamic), headers,
OpenAPI generators (v3, UI), process management, rendering, redirects,
remote forwarding, SSE, WebSocket, responses, security (HSTS), sessions
– client: connection pool, cookies, session, exceptions
– common: async file utilities, type definitions
– settings: DI for JSON/HTML settings
– testing: TestClient, message simulators, helpers
– utils: async helpers, metadata, timing
– Cython/pyx modules (.pxd/.pyx) for performance‐critical code (URL, headers,
messages, scribe, contents, cookies, exceptions)
• Other directories:
– itests: integration test apps and fixtures
– perf: benchmark apps and reporters
– tests: unit tests, example apps and templates
– project config (pyproject.toml, setup.py, Makefile, CI workflows)
Extract architecture insights from README
• Framework sits behind an ASGI server: exposes an ASGI “app” callable.
• On each request: ASGI server → BlackSheep ASGI adapter → middleware pipeline →
routing → controller or handler function → produce Response.
• Automatic parameter binding and DI feed handlers.
• Authentication & authorization plugged as middleware/strategies.
• Static files, OpenAPI docs, SSE/WebSocket, templating are “modules” wired
into the pipeline.
• The client package is a separate component for outbound HTTP calls.
Essential details
• Separate static file serving from controller pipeline.
• Dual nature: an ASGI “server” component and a client library component.
• DI container feeding handler parameters and model binding (JSON, query, path).