BlackSheep

BlackSheep is an asynchronous web framework to build event based web
applications with Python. It is inspired by
Flask, ASP.NET
Core, and the work by Yury
Selivanov.

pip install blacksheep

---

from datetime import datetime

from blacksheep import Application, get


app = Application()

@get("/")
async def home():
    return f"Hello, World! {datetime.utcnow().isoformat()}"

Getting started using the CLI ✨

BlackSheep offers a CLI to bootstrap new projects rapidly.
To try it, first install the blacksheep-cli package:

pip install blacksheep-cli

Then use the blacksheep create command to bootstrap a project
using one of the supported templates.

The CLI includes a help, and supports custom templates, using the
same sources supported by Cookiecutter.

Dependencies

Before version 2.3.1, BlackSheep only supported running with CPython and
always depended on httptools. Starting with version 2.3.1, the framework
supports running on PyPy and makes httptools an
optional dependency. The BlackSheep HTTP Client requires either httptools
(for CPython) or h11 (for PyPy).

For slightly better performance in URL parsing when running on CPython,
it is recommended to install httptools.

[!TIP]

The best performance can be achieved using PyPy and
Socketify (see
#539 for more information).

Getting started with the documentation

The documentation offers getting started tutorials:

• Getting started:
  basics
• Getting started: the MVC project
  template

These project templates can be used to start new applications faster:

• MVC project
  template
• Empty project
  template

Requirements

Python: any version listed in the project’s
classifiers. The current list is:

[!TIP]

Starting from version 2.3.1, BlackSheep supports PyPy, too (PyPy 3.11).
Previous versions of the framework supported only CPython.

BlackSheep belongs to the category of
ASGI web frameworks, so it requires
an ASGI HTTP server to run, such as uvicorn,
hypercorn or
granian.
For example, to use it with uvicorn:

$ pip install uvicorn

To run an application like in the example above, use the methods provided by
the ASGI HTTP Server:

# if the BlackSheep app is defined in a file `server.py`

$ uvicorn server:app

To run for production, refer to the documentation of the chosen ASGI server
(i.e. for uvicorn).

Automatic bindings and dependency injection

BlackSheep supports automatic binding of values for request handlers, by type
annotation or by conventions. See more
here.

from dataclasses import dataclass

from blacksheep import Application, FromJSON, FromQuery, get, post


app = Application()


@dataclass
class CreateCatInput:
    name: str


@post("/api/cats")
async def example(data: FromJSON[CreateCatInput]):
    # in this example, data is bound automatically reading the JSON
    # payload and creating an instance of `CreateCatInput`
    ...


@get("/:culture_code/:area")
async def home(culture_code, area):
    # in this example, both parameters are obtained from routes with
    # matching names
    return f"Request for: {culture_code} {area}"


@get("/api/products")
def get_products(
    page: int = 1,
    size: int = 30,
    search: str = "",
):
    # this example illustrates support for implicit query parameters with
    # default values
    # since the source of page, size, and search is not specified and no
    # route parameter matches their name, they are obtained from query string
    ...


@get("/api/products2")
def get_products2(
    page: FromQuery[int] = FromQuery(1),
    size: FromQuery[int] = FromQuery(30),
    search: FromQuery[str] = FromQuery(""),
):
    # this example illustrates support for explicit query parameters with
    # default values
    # in this case, parameters are explicitly read from query string
    ...

It also supports dependency
injection, a
feature that provides a consistent and clean way to use dependencies in request
handlers.

Generation of OpenAPI Documentation

Generation of OpenAPI Documentation.

Strategies to handle authentication and authorization

BlackSheep implements strategies to handle authentication and authorization.
These features are documented here:

• Authentication
• Authorization

app.use_authentication()\
    .add(ExampleAuthenticationHandler())


app.use_authorization()\
    .add(AdminsPolicy())


@auth("admin")
@get("/")
async def only_for_admins():
    ...


@auth()
@get("/")
async def only_for_authenticated_users():
    ...

BlackSheep provides:

• Built-in support for OpenID Connect authentication
• Built-in support for JWT Bearer authentication

Meaning that it is easy to integrate with services such as:

• Auth0
• Azure Active Directory
• Azure Active Directory B2C
• Okta

Refer to the documentation and to BlackSheep-Examples
for more details and examples.

Web framework features

• ASGI compatibility
• Routing
• Request handlers can be defined as
  functions, or class
  methods
• Middlewares
• WebSocket
• Server-Sent Events (SSE)
• Built-in support for dependency
  injection
• Support for automatic binding of route and query parameters to request
  handlers methods
  calls
• Strategy to handle
  exceptions
• Strategy to handle authentication and
  authorization
• Built-in support for OpenID Connect authentication using OIDC
  discovery
• Built-in support for JWT Bearer authentication using OIDC discovery and
  other sources of
  JWKS
• Handlers
  normalization
• Serving static
  files
• Integration with
  Jinja2
• Support for serving SPAs that use HTML5 History API for client side
  routing
• Support for automatic generation of OpenAPI
  Documentation
• Strategy to handle CORS settings
• Sessions
• Support for automatic binding of dataclasses and
  Pydantic models to handle the
  request body payload expected by request handlers
• TestClient class to simplify testing of applications
• Anti Forgery validation to protect against Cross-Site Request Forgery (XSRF/CSRF) attacks

Client features

BlackSheep includes an HTTP Client.

Example:

import asyncio

from blacksheep.client import ClientSession


async def client_example():
    async with ClientSession() as client:
        response = await client.get("https://docs.python.org/3/")
        text = await response.text()
        print(text)


asyncio.run(client_example())

[!IMPORTANT]

Starting from version 2.3.1, BlackSheep supports PyPy,
too (PyPy 3.11). For this reason, using the client requires an additional
dependency: httptools if using CPython, h11 if using PyPy. This affects
only the blacksheep.client namespace.

Supported platforms and runtimes

• Python: all versions included in the build matrix.
• CPython and PyPy.
• Ubuntu.
• Windows 10.
• macOS.

Documentation

Please refer to the documentation website.

Communication

BlackSheep community in Gitter.

Branches

The main branch contains the currently developed version, which is version 2. The v1 branch contains version 1 of the web framework, for bugs fixes
and maintenance.