https://github.com/Neoteroi/BlackSheep Skip to content Navigation Menu Toggle navigation Sign in * Product + GitHub Copilot Write better code with AI + Security Find and fix vulnerabilities + Actions Automate any workflow + Codespaces Instant dev environments + Issues Plan and track work + Code Review Manage code changes + Discussions Collaborate outside of code + Code Search Find more, search less Explore + All features + Documentation + GitHub Skills + Blog * Solutions By company size + Enterprises + Small and medium teams + Startups By use case + DevSecOps + DevOps + CI/CD + View all use cases By industry + Healthcare + Financial services + Manufacturing + Government + View all industries View all solutions * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners + Executive Insights * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} Neoteroi / BlackSheep Public * Notifications You must be signed in to change notification settings * Fork 79 * Star 1.9k Fast ASGI web framework for Python www.neoteroi.dev/blacksheep/ License MIT license 1.9k stars 79 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 41 * Pull requests 13 * Discussions * Actions * Security * Insights Additional navigation options * Code * Issues * Pull requests * Discussions * Actions * Security * Insights Neoteroi/BlackSheep main BranchesTags [ ] Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 279 Commits .github .github blacksheep blacksheep itests itests tests tests .flake8 .flake8 .gitattributes .gitattributes .gitignore .gitignore .isort.cfg .isort.cfg CHANGELOG.md CHANGELOG.md CODE_OF_CONDUCT.md CODE_OF_CONDUCT.md LICENSE LICENSE MANIFEST.in MANIFEST.in Makefile Makefile README.md README.md blacksheep.svg blacksheep.svg pyproject.toml pyproject.toml pytest.ini pytest.ini requirements.txt requirements.txt setup.py setup.py View all files Repository files navigation * README * Code of conduct * MIT license Build pypi versions codecov 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. 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: versions 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, 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(): ... Since version 1.2.1, BlackSheep implements: * 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()) Supported platforms and runtimes * Python: all versions included in the build matrix * 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. About Fast ASGI web framework for Python www.neoteroi.dev/blacksheep/ Topics python http framework web server http-server asyncio asgi blacksheep Resources Readme License MIT license Code of conduct Code of conduct Activity Custom properties Stars 1.9k stars Watchers 30 watching Forks 79 forks Report repository Releases 60 v2.0.6 Latest Jan 17, 2024 + 59 releases Packages 0 No packages published Used by 463 * @meoyawn * @airndlab * @lbsx * @ChenyangGao * @vffuunnyy * @Vehnem * @wiserfunding * @metalalive + 455 Contributors 19 * * * * * * * * * * * * * * + 5 contributors Languages * Python 93.8% * Cython 5.5% * HTML 0.3% * Jinja 0.2% * Makefile 0.1% * CSS 0.1% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.