BlackSheep

2.6.2 verified Fri May 01 auth: no python

A fast ASGI web framework for building asynchronous web applications in Python, featuring automatic OpenAPI documentation generation, dependency injection, and built-in HTTP client. Current version 2.6.2, supporting Python 3.10+. Active development with monthly releases on GitHub.

pip install blacksheep

Common errors

error ImportError: cannot import name 'Application' from 'blacksheep' ↓

cause Installed version is older than v2.0 or import path changed.

fix

Upgrade to latest: pip install --upgrade blacksheep. If still failing, use from blacksheep.server import Application for older versions.

error TypeError: 'function' object is not subscriptable ↓

cause Using synchronous handler or missing proper route decorator parentheses.

fix

Ensure handler is async and use @get('/') with parentheses, not @get('/') without calling.

error RuntimeError: You must use `await` on the request body methods ↓

cause Calling Request methods like .json() or .form() without await inside async handler.

fix

Use await request.json() or await request.form().

Warnings

breaking In v2.0+, the Application class no longer takes an 'app' parameter (previously used for wsgi). Use Application() directly. ↓

fix Remove any arguments from Application instantiation.

breaking The 'server' module was reorganized in v2.0. Most classes moved out of blacksheep.server to top-level. Importing from blacksheep.server for Request/Response/Application may fail. ↓

fix Update imports to top-level: from blacksheep import Request, Response, Application.

gotcha Route handlers must be async functions. Using synchronous functions will cause a runtime error or unexpected behavior. ↓

fix Define all handlers with async def.

gotcha When using the built-in HTTP client, ensure the event loop is running. Instantiating blacksheep.client.Client outside an async context may cause deadlocks. ↓

fix Create the client inside an async function or use await client.open_async().

deprecated The 'auth_mode' parameter in JWTBearerAuthentication is deprecated since v2.4.3. Use 'scheme' instead. ↓

fix Replace auth_mode=... with scheme=... in JWTBearerAuthentication constructor.

Imports

Application
wrong
```
from blacksheep.server import Application
```
correct
```
from blacksheep import Application
```
In v2.x, Application is directly exposed from the top-level package. Using blacksheep.server was deprecated.

Request

wrong

from blacksheep.server import Request

correct

from blacksheep import Request

Request and Response are top-level exports since v2.0.

Response
```
from blacksheep import Response
```

get

wrong

from blacksheep import get

correct

from blacksheep.server.routing import get

Route decorators are in routing module, not top-level.

Router

wrong

from blacksheep.routing import Router

correct

from blacksheep.server.routing import Router

Router is under blacksheep.server.routing.

Inject

wrong

from blacksheep import Inject

correct

from blacksheep.server.di import Inject

DI tools are in the blacksheep.server.di submodule.

Quickstart

Minimal BlackSheep app with a single route. Run with uvicorn or hypercorn.

from blacksheep import Application, Request, Response
from blacksheep.server.routing import get

app = Application()

@get('/')
async def home(request: Request) -> str:
    return 'Hello, World!'

# Run using: uvicorn main:app