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


app = Application()

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

Getting started

The documentation offers getting started tutorials:

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

Requirements

Python version 3.7, 3.8, 3.9, or 3.10.

BlackSheep belongs to the category of ASGI web frameworks, so it requires an ASGI HTTP server to run, such as uvicorn, or hypercorn. 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


app = Application()


@dataclass
class CreateCatInput:
    name: str


@app.router.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`
    ...


@app.router.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}"


@app.router.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
    ...


@app.router.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:

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


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


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


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

Since version 1.2.1, BlackSheep implements:

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

Refer to the documentation for more details and examples.

Web framework features

ASGI compatibility
Routing
Request handlers can be defined as functions, or class methods
Middlewares
WebSocket
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(loop):
    async with ClientSession() as client:
        response = await client.get("https://docs.python.org/3/")

        assert response is not None
        text = await response.text()
        print(text)


loop = asyncio.get_event_loop()
loop.run_until_complete(client_example(loop))

Supported platforms and runtimes

Python 3.7 (cpython)
Python 3.8 (cpython)
Python 3.9 (cpython)
Python 3.10 (cpython)
Ubuntu 18.04
Windows 10
macOS

Documentation

Please refer to the documentation website.

Communication

BlackSheep community in Gitter.

Release files for blacksheep 1.2.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blacksheep 1.2.8
File	Size	Uploaded
blacksheep-1.2.8.tar.gz	773.0 kB	Oct 28, 2022	Details

Built distributions (wheels)

Table of built distributions (wheels) for blacksheep 1.2.8
File	Interpreter	ABI	Platform	Reset
blacksheep-1.2.8-cp311-cp311-win_amd64.whl 1.2 MB Oct 28, 2022	CPython 3.11	CPython 3.11	Windows x86-64	Details
blacksheep-1.2.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.6 MB Oct 28, 2022	CPython 3.11	CPython 3.11	Linux glibc 2.17+ x86-64	Details
blacksheep-1.2.8-cp311-cp311-macosx_10_9_universal2.whl 1.8 MB Oct 28, 2022	CPython 3.11	CPython 3.11	macOS 10.9+ universal2 (ARM64, x86-64)	Details
blacksheep-1.2.8-cp310-cp310-win_amd64.whl 1.2 MB Oct 28, 2022	CPython 3.10	CPython 3.10	Windows x86-64	Details
blacksheep-1.2.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.4 MB Oct 28, 2022	CPython 3.10	CPython 3.10	Linux glibc 2.17+ x86-64	Details
blacksheep-1.2.8-cp310-cp310-macosx_10_15_x86_64.whl 1.3 MB Oct 28, 2022	CPython 3.10	CPython 3.10	macOS 10.15+ x86-64	Details
blacksheep-1.2.8-cp39-cp39-win_amd64.whl 1.2 MB Oct 28, 2022	CPython 3.9	CPython 3.9	Windows x86-64	Details
blacksheep-1.2.8-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.5 MB Oct 28, 2022	CPython 3.9	CPython 3.9	Linux glibc 2.17+ x86-64	Details
blacksheep-1.2.8-cp39-cp39-macosx_10_15_x86_64.whl 1.3 MB Oct 28, 2022	CPython 3.9	CPython 3.9	macOS 10.15+ x86-64	Details
blacksheep-1.2.8-cp38-cp38-win_amd64.whl 1.2 MB Oct 28, 2022	CPython 3.8	CPython 3.8	Windows x86-64	Details
blacksheep-1.2.8-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.7 MB Oct 28, 2022	CPython 3.8	CPython 3.8	Linux glibc 2.17+ x86-64	Details
blacksheep-1.2.8-cp38-cp38-macosx_10_15_x86_64.whl 1.3 MB Oct 28, 2022	CPython 3.8	CPython 3.8	macOS 10.15+ x86-64	Details
blacksheep-1.2.8-cp37-cp37m-win_amd64.whl 1.2 MB Oct 28, 2022	CPython 3.7	CPython 3.7 pymalloc	Windows x86-64	Details
blacksheep-1.2.8-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 3.3 MB Oct 28, 2022	CPython 3.7	CPython 3.7 pymalloc	Linux glibc 2.17+ x86-64	Details
blacksheep-1.2.8-cp37-cp37m-macosx_10_15_x86_64.whl 1.3 MB Oct 28, 2022	CPython 3.7	CPython 3.7 pymalloc	macOS 10.15+ x86-64	Details

Total release size: 31.5 MB

Release files / blacksheep-1.2.8.tar.gz

Download URL	blacksheep-1.2.8.tar.gz
Size	773.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`e21167b3d6986933ac5baeedb63dab6b2ffbba41a9dda057b7d117b5fc55fe98`
BLAKE2b-256 checksum How to use checksums	`d06bad69d0a2cb25dc80d78effe8331454611b18b9740c31202ae964b4e1a109`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp311-cp311-win_amd64.whl

Download URL	blacksheep-1.2.8-cp311-cp311-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.11 Windows x86-64
SHA-256 checksum How to use checksums	`86c646da6b842199452c55389e6ac269a5b9ccca9844bca17ccbb718f203892c`
BLAKE2b-256 checksum How to use checksums	`3c7eaa31ac59871d89d16577faf048c69abe7574cd484d982ebd7c36ba01f8d3`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	blacksheep-1.2.8-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.6 MB
Tags	CPython 3.11 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`6d92a9af8845754757f8facdaafae40e6186276abfec8a2967251275f6cfba21`
BLAKE2b-256 checksum How to use checksums	`879c1e0fe40bb6cc3e658cda49dcf02c4bd51b897f55bc0370a28589d731808f`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp311-cp311-macosx_10_9_universal2.whl

Download URL	blacksheep-1.2.8-cp311-cp311-macosx_10_9_universal2.whl
Size	1.8 MB
Tags	CPython 3.11 macOS 10.9+ universal2 (ARM64, x86-64)
SHA-256 checksum How to use checksums	`852a729ba81f65b7b3ec352470ad22595ea9921265ef549f1c17b728c0a7fe4d`
BLAKE2b-256 checksum How to use checksums	`332522b65af7b651401c3ebf10a519e13524749cd8bb332af484f32b2552eeba`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp310-cp310-win_amd64.whl

Download URL	blacksheep-1.2.8-cp310-cp310-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.10 Windows x86-64
SHA-256 checksum How to use checksums	`1d3d456cef07c6d42c33528ce6bed553457d274d5c06094751686e37b722b938`
BLAKE2b-256 checksum How to use checksums	`965a97235293e231569fed6b3bd02a9d286cd05bcc7648da8c75da713297abcd`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	blacksheep-1.2.8-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.4 MB
Tags	CPython 3.10 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`4f22443210040d2b596e6b4ffe755e5ccf4f226c73a39390a924a2350f4478a8`
BLAKE2b-256 checksum How to use checksums	`6a4ddec7fe71810b0d18b2e1cc52d01acded61cc642f2934d345d5c1a60588bc`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp310-cp310-macosx_10_15_x86_64.whl

Download URL	blacksheep-1.2.8-cp310-cp310-macosx_10_15_x86_64.whl
Size	1.3 MB
Tags	CPython 3.10 macOS 10.15+ x86-64
SHA-256 checksum How to use checksums	`6e4e60a058fd644b4b93939b820a2d34327be0f4f7e8fe2274074721588405ee`
BLAKE2b-256 checksum How to use checksums	`703247270b45b77a08dada328a5aa69d3ff74ca0d7c94452a872d14d14859108`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp39-cp39-win_amd64.whl

Download URL	blacksheep-1.2.8-cp39-cp39-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.9 Windows x86-64
SHA-256 checksum How to use checksums	`30234546bc643754562cc3f0f5286c2633317cee914d318f675d8c76b799bb1f`
BLAKE2b-256 checksum How to use checksums	`994acfe2fe0f8bb145393950dfa73c153a9b1730168a8ea8c44a98f2274aaab9`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	blacksheep-1.2.8-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.5 MB
Tags	CPython 3.9 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`17102d29559649fc5aa6a10299d6ed6f9f3c7eb4635c6291b428e591c05ef301`
BLAKE2b-256 checksum How to use checksums	`9496565016099eedae2ae911fa2f03ff993110080225d87febda288cec52113a`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp39-cp39-macosx_10_15_x86_64.whl

Download URL	blacksheep-1.2.8-cp39-cp39-macosx_10_15_x86_64.whl
Size	1.3 MB
Tags	CPython 3.9 macOS 10.15+ x86-64
SHA-256 checksum How to use checksums	`1ec202287ad3b556f16a13c1790de605d902df2019611f93892785c1ce4f4f3d`
BLAKE2b-256 checksum How to use checksums	`d2378947b05e4025e03ce6379cddf0db6122a5ff9cafea6b726d1d59e1051ccd`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp38-cp38-win_amd64.whl

Download URL	blacksheep-1.2.8-cp38-cp38-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.8 Windows x86-64
SHA-256 checksum How to use checksums	`6ff4c639db7f3e3996993e922682cee37113676e453e0bdb76635608d147d06d`
BLAKE2b-256 checksum How to use checksums	`a8280d6859bfb549f469ec1c647b6765000d9fe536e9c7817f460c8268f803ca`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	blacksheep-1.2.8-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.7 MB
Tags	CPython 3.8 Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`cde2bb7ca2494a859d9370e08ad7218cbd7e013471a78dccd86dab60e5d71029`
BLAKE2b-256 checksum How to use checksums	`49f0c87a7b70128b3668f6caca06ba05755d193eee88fe71d1c012247c349e95`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp38-cp38-macosx_10_15_x86_64.whl

Download URL	blacksheep-1.2.8-cp38-cp38-macosx_10_15_x86_64.whl
Size	1.3 MB
Tags	CPython 3.8 macOS 10.15+ x86-64
SHA-256 checksum How to use checksums	`ca439b1226ae542632d72b5b0d2f7fbbfc7b632d52907f33f3abc98b0ded51d1`
BLAKE2b-256 checksum How to use checksums	`b839fecb52a261f385031e873292b5e3f34d97d901e4f7c4240e73a07c7a2f8e`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp37-cp37m-win_amd64.whl

Download URL	blacksheep-1.2.8-cp37-cp37m-win_amd64.whl
Size	1.2 MB
Tags	CPython 3.7 CPython 3.7 pymalloc Windows x86-64
SHA-256 checksum How to use checksums	`bb80dcb441d5c63adc70a6818ad3f5e70ec8a824d351f51c9335ec768e3a673e`
BLAKE2b-256 checksum How to use checksums	`6c5e09ed34bfc9adef5d01745daf52131ef6027ec6771d8595dd49afb08dfde7`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL	blacksheep-1.2.8-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size	3.3 MB
Tags	CPython 3.7 CPython 3.7 pymalloc Linux glibc 2.17+ x86-64
SHA-256 checksum How to use checksums	`085964bb821e9c1e25726e59309fbf98b5a78dbccff0f047b5e57c8d52b4b197`
BLAKE2b-256 checksum How to use checksums	`4052b1937f19ba196a6c2034addf1793765e6504ea573d8e5a3214f53e133022`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`

Release files / blacksheep-1.2.8-cp37-cp37m-macosx_10_15_x86_64.whl

Download URL	blacksheep-1.2.8-cp37-cp37m-macosx_10_15_x86_64.whl
Size	1.3 MB
Tags	CPython 3.7 CPython 3.7 pymalloc macOS 10.15+ x86-64
SHA-256 checksum How to use checksums	`45d152950e4320791dbd0404021d40176d0f8f0915d7b653d9a2b4db2d950c8d`
BLAKE2b-256 checksum How to use checksums	`7b477f8189307470efe4fc8f57604a5a38ef16fb16a57c493e52b0791b7c8e93`
Upload date	Oct 28, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.9.15`