blacksheep 0.1.1

Fast HTTP Server/Client microframework for Python asyncio

BlackSheep

Fast HTTP Server/Client microframework for Python asyncio, using Cython, uvloop, and httptools.

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()}')

app.start()

Automatic bindings and dependency injection

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

from blacksheep.server.bindings import (FromJson,
                                        FromHeader,
                                        FromQuery,
                                        FromRoute,
                                        FromServices)

@app.router.put(b'/:d')
async def example(a: FromQuery(List[str]),
                  b: FromServices(Dog),
                  c: FromJson(Cat),
                  d: FromRoute(),
                  e: FromHeader(name='X-Example')):
    pass


@app.router.get(b'/:culture_code/:area')
async def home(request, culture_code, area):
    return text(f'Request for: {culture_code} {area}')

It also supports dependency injection, provided by rodi, a library from the same author, supporting singleton, scoped, and transient life style for activated services.

Strategies to handle authentication and authorization

BlackSheep implements strategies to handle authentication and authorization, using GuardPost, a library from the same author.

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


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


@auth('admin')
@app.router.get(b'/')
async def only_for_admins():
    return None


@auth()
@app.router.get(b'/')
async def only_for_authenticated_users():
    return None

Disclaimer

This project is currently targeting only Linux and CPython: support for Windows and other implementations of Python language are currently out of the scope. However, support for PyPy and Windows is planned for the future.

Objectives

• Clean architecture and source code, following SOLID principles
• Intelligible and easy to learn API, similar to those of many Python web frameworks
• Rich code API, based on Dependency Injection and inspired by ASP.NET Core
• Keep the core package minimal and focused, as much as possible, on features defined in HTTP and HTML standards
• Targeting stateless applications to be deployed in the cloud
• High performance, see results from TechEmpower benchmarks (links in Wiki page)

Server Features

• Routing
• Middlewares
• Built-in support for dependency injection
• Built-in support for multi processing
• Integration with built-in logging module to log access and errors synchronously - this is completely disabled by default
• Chunked encoding through generators (yield syntax)
• Serving static files
• Integration with Jinja2
• Strategy to handle exceptions
• Strategy to handle authentication and authorization
• Handlers normalization
• Support for automatic binding of route and query parameters to request handlers methods calls
• Automatic reload of the application during development, adopted from Werkzeug framework and Flask

Client Features

• HTTP connection pooling
• User friendly handling of SSL contexts (safe by default)
• Support for client side middlewares, enabling clean source code and separation of concerns (logging of different kinds, handling of cookies, etc.)
• Automatic handling of redirects (can be disabled, validates circular redirects and maximum number of redirects - redirects to URN are simply returned to code using the client)
• Automatic handling of cookies (can be disabled, Set-Cookie and Cookie headers)

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))

Note

This project is in beta stage. The reason behind this framework is described in this page of the Wiki: Story.

Documentation

Please refer to the project Wiki.

Public project in Azure DevOps

https://dev.azure.com/robertoprevato/BlackSheep - see here the project in Azure DevOps, with builds and other goodness.