# asgi-cors
[](https://pypi.org/project/asgi-cors/)
[](https://github.com/simonw/asgi-cors/actions/workflows/test.yml)
[](https://github.com/simonw/asgi-cors/releases)
[](https://github.com/simonw/asgi-cors/blob/main/LICENSE)
ASGI middleware for applying CORS headers to an ASGI application.
## Installation
```bash
pip install asgi-cors
```
## Some background on CORS
CORS stands for Cross-Origin Resource Sharing. It is a web standard that allows applications to opt-in to allowing JavaScript running on other domains to make `fetch()` calls that can retrieve data from the application.
See [MDN's CORS article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for more background.
The easiest way to allow scripts running on other domains to access data from an application is to add the following HTTP header:
```
Access-Control-Allow-Origin: *
```
This will allow scripts running on ANY domain to make `fetch()` calls against the application. For public data this is often fine, but there are situations where this may not be what you want to do: one example might be code that runs behind a VPN and needs to allow specific, trusted hosts to load data without opening itself up to every site on the internet.
For these cases, the server needs to inspect the Origin header from the client and return that Origin in the above header. For example, an incoming request from `http://localhost:8000` might be judged as trusted - in which case the application server needs to reply like so:
```
Access-Control-Allow-Origin: http://localhost:8000
```
Note that the `Access-Control-Allow-Origin` header can only return a single value. This means that if you want to allow requests from multiple origins you need to dynamically allowlist those origins and return a different header value depending on the incoming request.
Additionally if specific HTTP methods should be allowed an application should add:
```
Access-Control-Allow-Methods: GET, OPTIONS
```
Here `GET` and `OPTIONS` are allowed.
Similarly specific headers can be allowed:
```
Access-Control-Allow-Headers: content-type, Authorization
```
In this case `content-type` and `Authorization` headers are allowed to be sent to the server in a CORS request.
Verbs other than `GET` (such as `POST`) will trigger a preflight request. This is an `OPTIONS` request that the browser sends to the server to ask if the server will accept the request.
The `access-control-max-age` header can be used to specify how long the results of a preflight request can be cached. This can reduce the number of requests made to the server.
## How to use this middleware
We will assume you have an existing ASGI app, in a variable called `app`.
First, import the `asgi_cors` function:
```python
from asgi_cors import asgi_cors
```
To enable CORS headers for everywhere (by adding the `Access-Control-Allow-Origin: *` header to every request), do this:
```python
app = asgi_cors(app, allow_all=True)
```
If you wish to only allow it from a specific host, use the following:
```python
app = asgi_cors(app, hosts=[
"https://www.example.com"
])
```
Now JavaScript executing on https://www.example.com will be able to call your API. You can test this out by opening up example.com in your browser, opening your browser's devtools console and pasting in the following JavaScript:
```javascript
fetch("https://your-api.com/").then(r => r.json()).then(d => console.log(d))
```
You can include multiple hosts in the list.
If you want to open your application up to requests from a wildcard-defined selection of hosts, use the following:
```python
app = asgi_cors(app, host_wildcards=[
"http://localhost:800*",
"http://*.example.com"
])
```
This will enable access from any JavaScript running on a local host server on ports 8000 through 8009 - or from any subdomain of example.com.
If you need to do something more complicated that cannot be expressed using the `hosts=` or `host_wildcards=` parameters, you can use `callback=` to specify a custom function. For example:
```python
def validate_origin(origin):
return origin.startswith("https://")
app = asgi_cors(app, callback=validate_origin)
```
Your callback function will be passed the `Origin` header that was passed in by the browser. Both regular and async functions are supported.
To add specific allowed headers or methods you can specify them with the `headers=` and `methods=` parameters:
```python
app = asgi_cors(app, methods=[
"GET", "OPTIONS"
], headers=[
"Authorization","content-type"
])
```
To set a `access-control-max-age` header, use the `max_age=` parameter:
```python
app = asgi_cors(app, host_wildcards=["*"], max_age=3600)
```
## Using the middleware as a decorator
If you are defining your ASGI application directly as a function, you can use the `asgi_cors_decorator` function decorator like so:
```python
from asgi_cors import asgi_cors_decorator
@asgi_cors_decorator(allow_all=True)
async def my_asgi_app(scope, receive, send):
# Your app goes here
```
Raw data
{
"_id": null,
"home_page": "https://github.com/simonw/asgi-cors",
"name": "asgi-cors",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Simon Willison",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4b/72/75047bc62e3d1bb2c7bc5cbabf7727b965e6a9130b6e1deac6ab72879c86/asgi-cors-1.0.1.tar.gz",
"platform": null,
"description": "# asgi-cors\n\n[](https://pypi.org/project/asgi-cors/)\n[](https://github.com/simonw/asgi-cors/actions/workflows/test.yml)\n[](https://github.com/simonw/asgi-cors/releases)\n[](https://github.com/simonw/asgi-cors/blob/main/LICENSE)\n\nASGI middleware for applying CORS headers to an ASGI application.\n\n## Installation\n```bash\npip install asgi-cors\n```\n## Some background on CORS\n\nCORS stands for Cross-Origin Resource Sharing. It is a web standard that allows applications to opt-in to allowing JavaScript running on other domains to make `fetch()` calls that can retrieve data from the application.\n\nSee [MDN's CORS article](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for more background.\n\nThe easiest way to allow scripts running on other domains to access data from an application is to add the following HTTP header:\n```\nAccess-Control-Allow-Origin: *\n```\nThis will allow scripts running on ANY domain to make `fetch()` calls against the application. For public data this is often fine, but there are situations where this may not be what you want to do: one example might be code that runs behind a VPN and needs to allow specific, trusted hosts to load data without opening itself up to every site on the internet.\n\nFor these cases, the server needs to inspect the Origin header from the client and return that Origin in the above header. For example, an incoming request from `http://localhost:8000` might be judged as trusted - in which case the application server needs to reply like so:\n```\nAccess-Control-Allow-Origin: http://localhost:8000\n```\nNote that the `Access-Control-Allow-Origin` header can only return a single value. This means that if you want to allow requests from multiple origins you need to dynamically allowlist those origins and return a different header value depending on the incoming request.\n\nAdditionally if specific HTTP methods should be allowed an application should add:\n```\nAccess-Control-Allow-Methods: GET, OPTIONS\n```\nHere `GET` and `OPTIONS` are allowed.\n\nSimilarly specific headers can be allowed:\n```\nAccess-Control-Allow-Headers: content-type, Authorization\n```\nIn this case `content-type` and `Authorization` headers are allowed to be sent to the server in a CORS request.\n\nVerbs other than `GET` (such as `POST`) will trigger a preflight request. This is an `OPTIONS` request that the browser sends to the server to ask if the server will accept the request.\n\nThe `access-control-max-age` header can be used to specify how long the results of a preflight request can be cached. This can reduce the number of requests made to the server.\n\n## How to use this middleware\n\nWe will assume you have an existing ASGI app, in a variable called `app`.\n\nFirst, import the `asgi_cors` function:\n```python\nfrom asgi_cors import asgi_cors\n```\nTo enable CORS headers for everywhere (by adding the `Access-Control-Allow-Origin: *` header to every request), do this:\n```python\napp = asgi_cors(app, allow_all=True)\n```\nIf you wish to only allow it from a specific host, use the following:\n```python\napp = asgi_cors(app, hosts=[\n \"https://www.example.com\"\n])\n```\nNow JavaScript executing on https://www.example.com will be able to call your API. You can test this out by opening up example.com in your browser, opening your browser's devtools console and pasting in the following JavaScript:\n```javascript\nfetch(\"https://your-api.com/\").then(r => r.json()).then(d => console.log(d))\n```\nYou can include multiple hosts in the list.\n\nIf you want to open your application up to requests from a wildcard-defined selection of hosts, use the following:\n```python\napp = asgi_cors(app, host_wildcards=[\n \"http://localhost:800*\",\n \"http://*.example.com\"\n])\n```\nThis will enable access from any JavaScript running on a local host server on ports 8000 through 8009 - or from any subdomain of example.com.\n\nIf you need to do something more complicated that cannot be expressed using the `hosts=` or `host_wildcards=` parameters, you can use `callback=` to specify a custom function. For example:\n```python\ndef validate_origin(origin):\n return origin.startswith(\"https://\")\n\napp = asgi_cors(app, callback=validate_origin)\n```\nYour callback function will be passed the `Origin` header that was passed in by the browser. Both regular and async functions are supported.\n\nTo add specific allowed headers or methods you can specify them with the `headers=` and `methods=` parameters:\n```python\napp = asgi_cors(app, methods=[\n \"GET\", \"OPTIONS\"\n], headers=[\n \"Authorization\",\"content-type\"\n])\n```\nTo set a `access-control-max-age` header, use the `max_age=` parameter:\n\n```python\napp = asgi_cors(app, host_wildcards=[\"*\"], max_age=3600)\n```\n\n## Using the middleware as a decorator\n\nIf you are defining your ASGI application directly as a function, you can use the `asgi_cors_decorator` function decorator like so:\n```python\nfrom asgi_cors import asgi_cors_decorator\n\n\n@asgi_cors_decorator(allow_all=True)\nasync def my_asgi_app(scope, receive, send):\n # Your app goes here\n```\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "ASGI middleware for applying CORS headers to an ASGI application",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/simonw/asgi-cors"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3653d13be6bf9b87ed327de72881bd9e3754789a57446962ff7d7cc1783b5cd",
"md5": "ab04855205dd30caf3650f5d59a9957d",
"sha256": "075ee8359f2056ff8fa9d7751bdaeef30b40cf74040a25ffa3aaba61feca2c61"
},
"downloads": -1,
"filename": "asgi_cors-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab04855205dd30caf3650f5d59a9957d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8483,
"upload_time": "2024-04-12T03:19:55",
"upload_time_iso_8601": "2024-04-12T03:19:55.806205Z",
"url": "https://files.pythonhosted.org/packages/b3/65/3d13be6bf9b87ed327de72881bd9e3754789a57446962ff7d7cc1783b5cd/asgi_cors-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4b7275047bc62e3d1bb2c7bc5cbabf7727b965e6a9130b6e1deac6ab72879c86",
"md5": "d81895957804c985b62defa41b902719",
"sha256": "068a88c824c513573041a4e26b0c2801fcefefe6d59bb470d475a84f59fd498b"
},
"downloads": -1,
"filename": "asgi-cors-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "d81895957804c985b62defa41b902719",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8240,
"upload_time": "2024-04-12T03:19:57",
"upload_time_iso_8601": "2024-04-12T03:19:57.204023Z",
"url": "https://files.pythonhosted.org/packages/4b/72/75047bc62e3d1bb2c7bc5cbabf7727b965e6a9130b6e1deac6ab72879c86/asgi-cors-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-12 03:19:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "simonw",
"github_project": "asgi-cors",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asgi-cors"
}
JSON
