Skip to main content

Fast web framework for Python asyncio

Project description

Build pypi versions license Join the chat at https://gitter.im/Neoteroi/BlackSheep documentation

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.

Black Sheep

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.

blacksheep create command

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 runtime, and Socketify or Granian, (see #539 for more information).

Getting started with the documentation

The documentation offers getting started tutorials:

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

Requirements

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

versions

[!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:

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:

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

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

Web framework features

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blacksheep-2.4.0.tar.gz (1.2 MB view details)

Uploaded Source

Built Distributions

blacksheep-2.4.0-py3-none-any.whl (205.6 kB view details)

Uploaded Python 3

blacksheep-2.4.0-cp313-cp313-win_amd64.whl (1.8 MB view details)

Uploaded CPython 3.13Windows x86-64

blacksheep-2.4.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (5.3 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

blacksheep-2.4.0-cp313-cp313-macosx_10_13_universal2.whl (2.4 MB view details)

Uploaded CPython 3.13macOS 10.13+ universal2 (ARM64, x86-64)

blacksheep-2.4.0-cp312-cp312-win_amd64.whl (1.8 MB view details)

Uploaded CPython 3.12Windows x86-64

blacksheep-2.4.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

blacksheep-2.4.0-cp312-cp312-macosx_10_13_universal2.whl (2.4 MB view details)

Uploaded CPython 3.12macOS 10.13+ universal2 (ARM64, x86-64)

blacksheep-2.4.0-cp311-cp311-win_amd64.whl (1.8 MB view details)

Uploaded CPython 3.11Windows x86-64

blacksheep-2.4.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (4.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

blacksheep-2.4.0-cp311-cp311-macosx_10_9_universal2.whl (2.4 MB view details)

Uploaded CPython 3.11macOS 10.9+ universal2 (ARM64, x86-64)

blacksheep-2.4.0-cp310-cp310-win_amd64.whl (1.8 MB view details)

Uploaded CPython 3.10Windows x86-64

blacksheep-2.4.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (4.6 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

blacksheep-2.4.0-cp310-cp310-macosx_10_9_universal2.whl (2.4 MB view details)

Uploaded CPython 3.10macOS 10.9+ universal2 (ARM64, x86-64)

blacksheep-2.4.0-cp39-cp39-win_amd64.whl (1.8 MB view details)

Uploaded CPython 3.9Windows x86-64

blacksheep-2.4.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (4.6 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

blacksheep-2.4.0-cp39-cp39-macosx_10_9_universal2.whl (2.4 MB view details)

Uploaded CPython 3.9macOS 10.9+ universal2 (ARM64, x86-64)

File details

Details for the file blacksheep-2.4.0.tar.gz.

File metadata

  • Download URL: blacksheep-2.4.0.tar.gz
  • Upload date:
  • Size: 1.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0.tar.gz
Algorithm Hash digest
SHA256 7c89b325d0c56cec777e59510e768df91f3353f1bb935ef3af0f96204298ea60
MD5 82ba543ec7162fac57849b5d4978c5b0
BLAKE2b-256 7d4ae399a9852eee367ba066c0a87cbfd51a2e88f4dbff87b39bb264423a4a60

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: blacksheep-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 205.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 289ea075f5f72069b1ccff446843ca495a0e4c8345cf82b738d5435f93bb7080
MD5 c9a8769d492bea2d71220d641c88bfe5
BLAKE2b-256 a659004e6642c0992faaf935a64a5fa6ff20862d1dd54accb9e39e61cead21c1

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: blacksheep-2.4.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 b437273e4dce91aa9bc9ec59ea071247e2cffdd8eff892ada7c93791921adf9a
MD5 e2e8a1b3582b8edccd45b4db9054429f
BLAKE2b-256 bf0c873c2a42c1da433f381671eb67990f0449b74edc752e1406e31e5a97c864

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 e7f8e77bd10ae8421afb42f458805aa49298c585d19595a98e28b31619547378
MD5 dbeb413bb142f2d751587ffd8363f659
BLAKE2b-256 16526d5bb2177b2d61302c264e9f4a901ab2bd650ef104f4685305e5f43c5f68

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp313-cp313-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp313-cp313-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 63703281721ede4800db291cd73552a8e040bf4c969cc4a516d1ee99fa16fbbe
MD5 49b74100054396b59e3f8fd609c2fe85
BLAKE2b-256 6c0a9fd81bd8b57323f0694caffbe020385cbdcc4ad9b191cfcbcb70f725f5a2

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: blacksheep-2.4.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 04b6eac1db03b8197afd96d97090ab0d0d39a2a77e39857dc956a52ce53b5bde
MD5 04f7a17e36e706bea73125ffd0896956
BLAKE2b-256 2322db61329a2c285d36a5eb9aeecd4070380a58251fd710875fefa2ff5a0245

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 9fdd7fb68af936498173d9c5c9e14a9a1218d022c94435d1486b02ff1828c388
MD5 6255882202ac615766139911db09f8ef
BLAKE2b-256 49cbd2cd8719342baf87838a5e57d716c2f0182bfb68c9d0f4eb9a607cb58fb1

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp312-cp312-macosx_10_13_universal2.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp312-cp312-macosx_10_13_universal2.whl
Algorithm Hash digest
SHA256 b970ce9e7eb4673b996802e9f4e25ed44d80034e6b331767fb9e1babbc317d47
MD5 4127b2150623a5bf46842a12f4d9d6cb
BLAKE2b-256 1254dea5d885a5ed32a32df87c5f76d5661d84ca149cfa7f76c8bfbd5d343fc8

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: blacksheep-2.4.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 921c33d80df39e99c30cf2dcd6297c85b356f8eaf9587ad08574f72c194e9147
MD5 e5e3adafb59923fe961657165710a2f9
BLAKE2b-256 2e58bed50bab22721ac61064cb0c2a648f2a4dde1a4f77b69868b34d123e33b7

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 d19e4851c342d58b564cfd90da5b2b1e602dacdfc31e811e6bf0fd60867d613d
MD5 00c4681a7c53750d02605391a0bc7238
BLAKE2b-256 df129a8ceb914f0e9e000dc579879c16da02f6079be65a1136eb96dbe990967d

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp311-cp311-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp311-cp311-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 4d36c1ba54dd04a7698f305e627488bf9aa40950189ea2791a3828769f0b8fe7
MD5 fd6f74ec5614f760110c670990d3642c
BLAKE2b-256 77f99cd05e76ed9dd0049eb9ca7b1de0e5909ef94b354d6c2a5a8c156ccd6ac3

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: blacksheep-2.4.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 e60fbb20abe403b6b1e6a26bc31c81f2fec958d4ff180b6e70168c4475f030b0
MD5 70c91f1b2537356598193708889a9640
BLAKE2b-256 2024ff200d0991b70b33ac8399cd55eee5db65871401b001568e4c6259a281d8

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 86e7a5c72d6ccc9e36ffeef3549fb20f352461ab16fba0804c8b32e977c0136c
MD5 67397b923e67086610031c6f32f08954
BLAKE2b-256 f1d957240c939827c0c95eb2b68a1a29c68e231c37f8b4ebd70a83d74dc27142

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp310-cp310-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp310-cp310-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 de543e45816e1296f5658fc62a5a0685ccd985e32d61ba2347775b335a52ee78
MD5 88ebf4cd85f39d352f5fd1fd456a4b3e
BLAKE2b-256 877e84ef5702d89266ce613d24cf6e52e55a503ba05ce8df946fabb3516104e2

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: blacksheep-2.4.0-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for blacksheep-2.4.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 b434b3a302c9baf72655ad76eaa291b6c4a5c0f00eb84abb158e280593f4885f
MD5 584f4d3a45ca134cae31986d6faff0fe
BLAKE2b-256 90c1e0db4ebec6f9355e51bce084c3b3435c5d6dc9b6de0ff8dd147b76ed82e0

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Algorithm Hash digest
SHA256 4118874dc34cd13e1fc30b2ae946b8d7e1b5e882013d4a987b92021d78dc6e3c
MD5 412b52782c6c64c95cda24ab1933495c
BLAKE2b-256 c6c980537269bfbd70291e7e3eed5317c9b6f69991fcef338e55475d2f528ec1

See more details on using hashes here.

File details

Details for the file blacksheep-2.4.0-cp39-cp39-macosx_10_9_universal2.whl.

File metadata

File hashes

Hashes for blacksheep-2.4.0-cp39-cp39-macosx_10_9_universal2.whl
Algorithm Hash digest
SHA256 629dfb8d8d095db97bf3f717f7c594c28a3f033a866240efc62a8b5373f54acc
MD5 492ab8b649fbd0d168005177f01c58f2
BLAKE2b-256 5bd544a2e37c98d53a43b74f701801c503498457135a620358a900eccaf0bc6b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page