{"id":13419429,"url":"https://github.com/Neoteroi/BlackSheep","last_synced_at":"2025-03-15T05:31:14.698Z","repository":{"id":37317857,"uuid":"158754800","full_name":"Neoteroi/BlackSheep","owner":"Neoteroi","description":"Fast ASGI web framework for Python","archived":false,"fork":false,"pushed_at":"2024-07-29T03:42:37.000Z","size":2296,"stargazers_count":1884,"open_issues_count":50,"forks_count":77,"subscribers_count":29,"default_branch":"main","last_synced_at":"2024-11-24T20:46:24.909Z","etag":null,"topics":["asgi","asyncio","blacksheep","framework","http","http-server","python","server","web"],"latest_commit_sha":null,"homepage":"https://www.neoteroi.dev/blacksheep/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Neoteroi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"RobertoPrevato"}},"created_at":"2018-11-22T22:17:27.000Z","updated_at":"2024-11-24T13:56:34.000Z","dependencies_parsed_at":"2023-02-14T00:16:37.619Z","dependency_job_id":"aac5eb35-5592-4c7c-bd5e-4cf0cb0f5bfe","html_url":"https://github.com/Neoteroi/BlackSheep","commit_stats":{"total_commits":223,"total_committers":12,"mean_commits":"18.583333333333332","dds":"0.12107623318385652","last_synced_commit":"349c3ebcb10527665e90ed7892e70ed111c0e290"},"previous_names":["robertoprevato/blacksheep"],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FBlackSheep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FBlackSheep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FBlackSheep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Neoteroi%2FBlackSheep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Neoteroi","download_url":"https://codeload.github.com/Neoteroi/BlackSheep/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243690114,"owners_count":20331726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asgi","asyncio","blacksheep","framework","http","http-server","python","server","web"],"created_at":"2024-07-30T22:01:15.901Z","updated_at":"2025-03-15T05:31:14.206Z","avatar_url":"https://github.com/Neoteroi.png","language":"Python","readme":"[![Build](https://github.com/Neoteroi/BlackSheep/workflows/Main/badge.svg)](https://github.com/Neoteroi/BlackSheep/actions)\n[![pypi](https://img.shields.io/pypi/v/BlackSheep.svg?color=blue)](https://pypi.org/project/BlackSheep/)\n[![versions](https://img.shields.io/pypi/pyversions/blacksheep.svg)](https://github.com/robertoprevato/blacksheep)\n[![codecov](https://codecov.io/gh/Neoteroi/BlackSheep/branch/master/graph/badge.svg?token=Nzi29L0Eg1)](https://codecov.io/gh/Neoteroi/BlackSheep)\n[![license](https://img.shields.io/github/license/Neoteroi/blacksheep.svg)](https://github.com/Neoteroi/blacksheep/blob/main/LICENSE) [![Join the chat at https://gitter.im/Neoteroi/BlackSheep](https://badges.gitter.im/Neoteroi/BlackSheep.svg)](https://gitter.im/Neoteroi/BlackSheep?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge) [![documentation](https://img.shields.io/badge/📖-docs-purple)](https://www.neoteroi.dev/blacksheep/)\n\n# BlackSheep\nBlackSheep is an asynchronous web framework to build event based web\napplications with Python. It is inspired by\n[Flask](https://palletsprojects.com/p/flask/), [ASP.NET\nCore](https://docs.microsoft.com/en-us/aspnet/core/), and the work by [Yury\nSelivanov](https://magic.io/blog/uvloop-blazing-fast-python-networking/).\n\n\u003cp align=\"left\"\u003e\n  \u003ca href=\"#blacksheep\"\u003e\u003cimg width=\"320\" height=\"271\" src=\"https://www.neoteroi.dev/blacksheep/img/blacksheep.png\" alt=\"Black Sheep\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n```bash\npip install blacksheep\n```\n\n---\n\n```python\nfrom datetime import datetime\n\nfrom blacksheep import Application, get\n\n\napp = Application()\n\n@get(\"/\")\nasync def home():\n    return f\"Hello, World! {datetime.utcnow().isoformat()}\"\n\n```\n\n## Getting started using the CLI ✨\n\nBlackSheep offers a CLI to bootstrap new projects rapidly.\nTo try it, first install the `blacksheep-cli` package:\n\n```bash\npip install blacksheep-cli\n```\n\nThen use the `blacksheep create` command to bootstrap a project\nusing one of the supported templates.\n\n![blacksheep create command](https://gist.githubusercontent.com/RobertoPrevato/38a0598b515a2f7257c614938843b99b/raw/67d15ba337de94c2f50d980a7b8924a747259254/blacksheep-create-demo.gif)\n\nThe CLI includes a help, and supports custom templates, using the\nsame sources supported by `Cookiecutter`.\n\n## Getting started with the documentation\n\nThe documentation offers getting started tutorials:\n* [Getting started:\n  basics](https://www.neoteroi.dev/blacksheep/getting-started/)\n* [Getting started: the MVC project\n  template](https://www.neoteroi.dev/blacksheep/mvc-project-template/)\n\nThese project templates can be used to start new applications faster:\n\n* [MVC project\n  template](https://github.com/Neoteroi/BlackSheepMVC)\n* [Empty project\n  template](https://github.com/Neoteroi/BlackSheepEmptyProject)\n\n## Requirements\n\n[Python](https://www.python.org): any version listed in the project's\nclassifiers. The current list is:\n\n[![versions](https://img.shields.io/pypi/pyversions/blacksheep.svg)](https://github.com/robertoprevato/blacksheep)\n\n\nBlackSheep belongs to the category of\n[ASGI](https://asgi.readthedocs.io/en/latest/) web frameworks, so it requires\nan ASGI HTTP server to run, such as [uvicorn](http://www.uvicorn.org/), or\n[hypercorn](https://pgjones.gitlab.io/hypercorn/). For example, to use it with\nuvicorn:\n\n```bash\n$ pip install uvicorn\n```\n\nTo run an application like in the example above, use the methods provided by\nthe ASGI HTTP Server:\n\n```bash\n# if the BlackSheep app is defined in a file `server.py`\n\n$ uvicorn server:app\n```\n\nTo run for production, refer to the documentation of the chosen ASGI server\n(i.e. for [uvicorn](https://www.uvicorn.org/#running-with-gunicorn)).\n\n## Automatic bindings and dependency injection\nBlackSheep supports automatic binding of values for request handlers, by type\nannotation or by conventions. See [more\nhere](https://www.neoteroi.dev/blacksheep/requests/).\n\n```python\nfrom dataclasses import dataclass\n\nfrom blacksheep import Application, FromJSON, FromQuery, get, post\n\n\napp = Application()\n\n\n@dataclass\nclass CreateCatInput:\n    name: str\n\n\n@post(\"/api/cats\")\nasync def example(data: FromJSON[CreateCatInput]):\n    # in this example, data is bound automatically reading the JSON\n    # payload and creating an instance of `CreateCatInput`\n    ...\n\n\n@get(\"/:culture_code/:area\")\nasync def home(culture_code, area):\n    # in this example, both parameters are obtained from routes with\n    # matching names\n    return f\"Request for: {culture_code} {area}\"\n\n\n@get(\"/api/products\")\ndef get_products(\n    page: int = 1,\n    size: int = 30,\n    search: str = \"\",\n):\n    # this example illustrates support for implicit query parameters with\n    # default values\n    # since the source of page, size, and search is not specified and no\n    # route parameter matches their name, they are obtained from query string\n    ...\n\n\n@get(\"/api/products2\")\ndef get_products2(\n    page: FromQuery[int] = FromQuery(1),\n    size: FromQuery[int] = FromQuery(30),\n    search: FromQuery[str] = FromQuery(\"\"),\n):\n    # this example illustrates support for explicit query parameters with\n    # default values\n    # in this case, parameters are explicitly read from query string\n    ...\n\n```\n\nIt also supports [dependency\ninjection](https://www.neoteroi.dev/blacksheep/dependency-injection/), a\nfeature that provides a consistent and clean way to use dependencies in request\nhandlers.\n\n## Generation of OpenAPI Documentation\n[Generation of OpenAPI Documentation](https://www.neoteroi.dev/blacksheep/openapi/).\n\n## Strategies to handle authentication and authorization\nBlackSheep implements strategies to handle authentication and authorization.\nThese features are documented here:\n\n* [Authentication](https://www.neoteroi.dev/blacksheep/authentication/)\n* [Authorization](https://www.neoteroi.dev/blacksheep/authorization/)\n\n```python\napp.use_authentication()\\\n    .add(ExampleAuthenticationHandler())\n\n\napp.use_authorization()\\\n    .add(AdminsPolicy())\n\n\n@auth(\"admin\")\n@get(\"/\")\nasync def only_for_admins():\n    ...\n\n\n@auth()\n@get(\"/\")\nasync def only_for_authenticated_users():\n    ...\n```\n\nSince version `1.2.1`, BlackSheep implements:\n\n* [Built-in support for OpenID Connect authentication](https://www.neoteroi.dev/blacksheep/authentication/#oidc)\n* [Built-in support for JWT Bearer authentication](https://www.neoteroi.dev/blacksheep/authentication/#jwt-bearer)\n\nMeaning that it is easy to integrate with services such as:\n* [Auth0](https://auth0.com)\n* [Azure Active Directory](https://azure.microsoft.com/en-us/services/active-directory/)\n* [Azure Active Directory B2C](https://docs.microsoft.com/en-us/azure/active-directory-b2c/overview)\n* [Okta](https://www.okta.com)\n\nRefer to the documentation and to [BlackSheep-Examples](https://github.com/Neoteroi/BlackSheep-Examples)\nfor more details and examples.\n\n## Web framework features\n\n* [ASGI compatibility](https://www.neoteroi.dev/blacksheep/asgi/)\n* [Routing](https://www.neoteroi.dev/blacksheep/routing/)\n* Request handlers can be [defined as\n  functions](https://www.neoteroi.dev/blacksheep/request-handlers/), or [class\n  methods](https://www.neoteroi.dev/blacksheep/controllers/)\n* [Middlewares](https://www.neoteroi.dev/blacksheep/middlewares/)\n* [WebSocket](https://www.neoteroi.dev/blacksheep/websocket/)\n* [Server-Sent Events (SSE)](https://www.neoteroi.dev/blacksheep/server-sent-events/)\n* [Built-in support for dependency\n  injection](https://www.neoteroi.dev/blacksheep/dependency-injection/)\n* [Support for automatic binding of route and query parameters to request\n  handlers methods\n  calls](https://www.neoteroi.dev/blacksheep/getting-started/#handling-route-parameters)\n* [Strategy to handle\n  exceptions](https://www.neoteroi.dev/blacksheep/application/#configuring-exceptions-handlers)\n* [Strategy to handle authentication and\n  authorization](https://www.neoteroi.dev/blacksheep/authentication/)\n* [Built-in support for OpenID Connect authentication using OIDC\n  discovery](https://www.neoteroi.dev/blacksheep/authentication/#oidc)\n* [Built-in support for JWT Bearer authentication using OIDC discovery and\n  other sources of\n  JWKS](https://www.neoteroi.dev/blacksheep/authentication/#jwt-bearer)\n* [Handlers\n  normalization](https://www.neoteroi.dev/blacksheep/request-handlers/)\n* [Serving static\n  files](https://www.neoteroi.dev/blacksheep/static-files/)\n* [Integration with\n  Jinja2](https://www.neoteroi.dev/blacksheep/templating/)\n* [Support for serving SPAs that use HTML5 History API for client side\n  routing](https://www.neoteroi.dev/blacksheep/static-files/#how-to-serve-spas-that-use-html5-history-api)\n* [Support for automatic generation of OpenAPI\n  Documentation](https://www.neoteroi.dev/blacksheep/openapi/)\n* [Strategy to handle CORS settings](https://www.neoteroi.dev/blacksheep/cors/)\n* [Sessions](https://www.neoteroi.dev/blacksheep/sessions/)\n* Support for automatic binding of `dataclasses` and\n  [`pydantic`](https://pydantic-docs.helpmanual.io) models to handle the\n  request body payload expected by request handlers\n* [`TestClient` class to simplify testing of applications](https://www.neoteroi.dev/blacksheep/testing/)\n* [Anti Forgery validation](https://www.neoteroi.dev/blacksheep/anti-request-forgery) to protect against Cross-Site Request Forgery (XSRF/CSRF) attacks\n\n## Client features\n\nBlackSheep includes an HTTP Client.\n\n**Example:**\n```python\nimport asyncio\n\nfrom blacksheep.client import ClientSession\n\n\nasync def client_example():\n    async with ClientSession() as client:\n        response = await client.get(\"https://docs.python.org/3/\")\n        text = await response.text()\n        print(text)\n\n\nasyncio.run(client_example())\n```\n\n## Supported platforms and runtimes\n* Python: all versions included in the build matrix\n* Ubuntu\n* Windows 10\n* macOS\n\n## Documentation\nPlease refer to the [documentation website](https://www.neoteroi.dev/blacksheep/).\n\n## Communication\n[BlackSheep community in Gitter](https://gitter.im/Neoteroi/BlackSheep).\n\n## Branches\nThe _main_ branch contains the currently developed version, which is version 2. The _v1_ branch contains version 1 of the web framework, for bugs fixes\nand maintenance.\n","funding_links":["https://github.com/sponsors/RobertoPrevato"],"categories":["Python","HarmonyOS","Application frameworks","Micro-frameworks","Web"],"sub_categories":["Windows Manager","Async"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoteroi%2FBlackSheep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeoteroi%2FBlackSheep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoteroi%2FBlackSheep/lists"}