Skip to main content

Fast web framework and HTTP client for Python asyncio

Project description

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

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.server import Application
from blacksheep.server.responses import text


app = Application()

@app.route("/")
async def home(request):
    return text(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, or 3.9.

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


@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(request, culture_code, area):
    # in this example, both parameters are obtained from routes with
    # matching names
    return text(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():
    ...

Web framework features

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)
  • Ubuntu 18.04
  • Windows 10
  • macOS

Documentation

Please refer to the documentation website.

Communication

BlackSheep community in Gitter.

Project details


Download files

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

Files for blacksheep, version 1.0.9
Filename, size File type Python version Upload date Hashes
Filename, size blacksheep-1.0.9-cp37-cp37m-macosx_10_14_x86_64.whl (1.2 MB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.whl (2.8 MB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp37-cp37m-win_amd64.whl (1.2 MB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp38-cp38-macosx_10_14_x86_64.whl (1.2 MB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl (2.9 MB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp38-cp38-win_amd64.whl (1.2 MB) File type Wheel Python version cp38 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp39-cp39-macosx_10_14_x86_64.whl (1.2 MB) File type Wheel Python version cp39 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.whl (2.8 MB) File type Wheel Python version cp39 Upload date Hashes View
Filename, size blacksheep-1.0.9-cp39-cp39-win_amd64.whl (1.2 MB) File type Wheel Python version cp39 Upload date Hashes View
Filename, size blacksheep-1.0.9.tar.gz (713.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page