Sanic-CORS
==========
|Build Status| |Latest Version| |Supported Python versions|
|License|
A Sanic extension for handling Cross Origin Resource Sharing (CORS),
making cross-origin AJAX possible. Based on
`flask-cors <https://github.com/corydolphin/flask-cors>`__ by Cory Dolphin.
This package has a simple philosophy, when you want to enable CORS, you
wish to enable it for all use cases on a domain. This means no mucking
around with different allowed headers, methods, etc. By default,
submission of cookies across domains is disabled due to the security
implications, please see the documentation for how to enable
credential'ed requests, and please make sure you add some sort of
`CSRF <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`__
protection before doing so!
**Sept 2022 Notice:**
If you are having unexpected results in Sanic v22.9+, upgrade to Sanic-CORS v2.2.0
**December 2021 Notice:**
If you need compatibility with Sanic v21.12+, upgrade to Sanic-CORS v2.0
**Sept 2021 Notice:**
Please upgrade to Sanic-CORS v1.0.1 if you need compatibility with Sanic v21.9,<21.12
Installation
------------
Install the extension with using pip, or easy\_install.
.. code:: bash
$ pip install -U sanic-cors
Usage
-----
This package exposes a Sanic extension which by default enables CORS support on
all routes, for all origins and methods. It allows parameterization of all
CORS headers on a per-resource level. The package also contains a decorator,
for those who prefer this approach.
Simple Usage
~~~~~~~~~~~~
In the simplest case, initialize the Sanic-Cors extension with default
arguments in order to allow CORS for all domains on all routes.
.. code:: python
from sanic import Sanic
from sanic.response import text
from sanic_cors import CORS, cross_origin
app = Sanic(__name__)
CORS(app)
@app.route("/", methods=['GET', 'OPTIONS'])
def hello_world(request):
return text("Hello, cross-origin-world!")
Resource specific CORS
^^^^^^^^^^^^^^^^^^^^^^
Alternatively, you can specify CORS options on a resource and origin
level of granularity by passing a dictionary as the `resources` option,
mapping paths to a set of options.
.. code:: python
app = Sanic(__name__)
cors = CORS(app, resources={r"/api/*": {"origins": "*"}})
@app.route("/api/v1/users", methods=['GET', 'OPTIONS'])
def list_users(request):
return text("user example")
Route specific CORS via decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This extension also exposes a simple decorator to decorate sanic routes
with. Simply add ``@cross_origin(app)`` below a call to Sanic's
``@app.route(..)`` to allow CORS on a given route.
.. code:: python
@app.route("/", methods=['GET', 'OPTIONS'])
@cross_origin(app)
def hello_world(request):
return text("Hello, cross-origin-world!")
Sanic-Ext Usage
~~~~~~~~~~~~~~~
Sanic-CORS can use Sanic-Ext to load the plugin for you.
(But you need to make sure to disable the built-in sanic-ext CORS support too)
.. code:: python
from sanic import Sanic
from sanic.response import text
from sanic_ext import Extend
from sanic_cors.extension import CORS
app = Sanic(__name__)
CORS_OPTIONS = {"resources": r'/*', "origins": "*", "methods": ["GET", "POST", "HEAD", "OPTIONS"]}
# Disable sanic-ext built-in CORS, and add the Sanic-CORS plugin
Extend(app, extensions=[CORS], config={"CORS": False, "CORS_OPTIONS": CORS_OPTIONS})
@app.route("/", methods=['GET', 'OPTIONS'])
def hello_world(request):
return text("Hello, cross-origin-world!")
Documentation
-------------
For a full list of options, please see the flask-cors
`documentation <http://flask-cors.corydolphin.com/en/latest/api.html#extension>`__.
Preflight Requests
------------------
CORS requests have to send `pre-flight requests <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS#Preflighted_requests_in_CORS>`_
via the options method, Sanic by default only allows the ``GET`` method, in order to
service your CORS requests you must specify ``OPTIONS`` in the methods argument to
your routes decorator.
Sanic-CORS includes an ``automatic_options`` configuration parameter to
allow the plugin handle the ``OPTIONS`` response automatically for you. This is enabled by default, but you
can turn it off if you wish to do your own ``OPTIONS`` response.
.. code:: python
CORS(app, automatic_options=True)
@app.delete('/api/auth')
@auth.login_required
async def auth_logout(request):
auth.logout_user(request)
return json(None, status=OK)
or with the app config key:
.. code:: python
app = Sanic(__name__)
app.config['CORS_AUTOMATIC_OPTIONS'] = True
CORS(app)
@app.delete('/api/auth')
@auth.login_required
async def auth_logout(request):
auth.logout_user(request)
return json(None, status=OK)
or directly on the route with the ``cross_origin`` decorator:
.. code:: python
@app.route('/api/auth', methods={'DELETE','OPTIONS'})
@auth.login_required
@cross_origin(app, automatic_options=True)
async def auth_logout(request):
auth.logout_user(request)
return json(None, status=OK)
Note: For the third example, you must use ``@route()``, rather than
``@delete()`` because you need to enable both ``DELETE`` and ``OPTIONS`` to
work on that route, even though the decorator is handling the ``OPTIONS``
response.
Tests
-----
A simple set of tests is included in ``test/``. To run, install nose,
and simply invoke ``nosetests`` or ``python setup.py test`` to exercise
the tests.
Contributing
------------
Questions, comments or improvements? Please create an issue on
`Github <https://github.com/ashleysommer/sanic-cors>`__. I do my best to
include every contribution proposed in any way that I can.
Credits
-------
This Sanic extension is based upon the `Decorator for the HTTP Access
Control <http://flask.pocoo.org/snippets/56/>`__ written by Armin
Ronacher.
.. |Build Status| image:: https://api.travis-ci.org/ashleysommer/sanic-cors.svg?branch=master
:target: https://travis-ci.org/ashleysommer/sanic-cors
.. |Latest Version| image:: https://img.shields.io/pypi/v/Sanic-Cors.svg
:target: https://pypi.python.org/pypi/Sanic-Cors/
.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/Sanic-Cors.svg
:target: https://img.shields.io/pypi/pyversions/Sanic-Cors.svg
.. |License| image:: http://img.shields.io/:license-mit-blue.svg
:target: https://pypi.python.org/pypi/Sanic-Cors/
Raw data
{
"_id": null,
"home_page": "https://github.com/ashleysommer/sanic-cors",
"name": "Sanic-Cors",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Ashley Sommer",
"author_email": "ashleysommer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b2/b8/fd98a4842e54c1fb3d7b7bc85abbc6d76f79871763eb455a391ddfdb934d/Sanic-Cors-2.2.0.tar.gz",
"platform": "any",
"description": "Sanic-CORS\n==========\n\n|Build Status| |Latest Version| |Supported Python versions|\n|License|\n\nA Sanic extension for handling Cross Origin Resource Sharing (CORS),\nmaking cross-origin AJAX possible. Based on\n`flask-cors <https://github.com/corydolphin/flask-cors>`__ by Cory Dolphin.\n\nThis package has a simple philosophy, when you want to enable CORS, you\nwish to enable it for all use cases on a domain. This means no mucking\naround with different allowed headers, methods, etc. By default,\nsubmission of cookies across domains is disabled due to the security\nimplications, please see the documentation for how to enable\ncredential'ed requests, and please make sure you add some sort of\n`CSRF <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`__\nprotection before doing so!\n\n**Sept 2022 Notice:**\nIf you are having unexpected results in Sanic v22.9+, upgrade to Sanic-CORS v2.2.0\n\n**December 2021 Notice:**\nIf you need compatibility with Sanic v21.12+, upgrade to Sanic-CORS v2.0\n\n**Sept 2021 Notice:**\nPlease upgrade to Sanic-CORS v1.0.1 if you need compatibility with Sanic v21.9,<21.12\n\nInstallation\n------------\n\nInstall the extension with using pip, or easy\\_install.\n\n.. code:: bash\n\n $ pip install -U sanic-cors\n\nUsage\n-----\n\nThis package exposes a Sanic extension which by default enables CORS support on\nall routes, for all origins and methods. It allows parameterization of all\nCORS headers on a per-resource level. The package also contains a decorator,\nfor those who prefer this approach.\n\nSimple Usage\n~~~~~~~~~~~~\n\nIn the simplest case, initialize the Sanic-Cors extension with default\narguments in order to allow CORS for all domains on all routes.\n\n.. code:: python\n\n from sanic import Sanic\n from sanic.response import text\n from sanic_cors import CORS, cross_origin\n\n app = Sanic(__name__)\n CORS(app)\n\n @app.route(\"/\", methods=['GET', 'OPTIONS'])\n def hello_world(request):\n return text(\"Hello, cross-origin-world!\")\n\nResource specific CORS\n^^^^^^^^^^^^^^^^^^^^^^\n\nAlternatively, you can specify CORS options on a resource and origin\nlevel of granularity by passing a dictionary as the `resources` option,\nmapping paths to a set of options.\n\n.. code:: python\n\n app = Sanic(__name__)\n cors = CORS(app, resources={r\"/api/*\": {\"origins\": \"*\"}})\n\n @app.route(\"/api/v1/users\", methods=['GET', 'OPTIONS'])\n def list_users(request):\n return text(\"user example\")\n\nRoute specific CORS via decorator\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis extension also exposes a simple decorator to decorate sanic routes\nwith. Simply add ``@cross_origin(app)`` below a call to Sanic's\n``@app.route(..)`` to allow CORS on a given route.\n\n.. code:: python\n\n @app.route(\"/\", methods=['GET', 'OPTIONS'])\n @cross_origin(app)\n def hello_world(request):\n return text(\"Hello, cross-origin-world!\")\n\nSanic-Ext Usage\n~~~~~~~~~~~~~~~\n\nSanic-CORS can use Sanic-Ext to load the plugin for you.\n(But you need to make sure to disable the built-in sanic-ext CORS support too)\n\n.. code:: python\n\n from sanic import Sanic\n from sanic.response import text\n from sanic_ext import Extend\n from sanic_cors.extension import CORS\n app = Sanic(__name__)\n CORS_OPTIONS = {\"resources\": r'/*', \"origins\": \"*\", \"methods\": [\"GET\", \"POST\", \"HEAD\", \"OPTIONS\"]}\n # Disable sanic-ext built-in CORS, and add the Sanic-CORS plugin\n Extend(app, extensions=[CORS], config={\"CORS\": False, \"CORS_OPTIONS\": CORS_OPTIONS})\n\n @app.route(\"/\", methods=['GET', 'OPTIONS'])\n def hello_world(request):\n return text(\"Hello, cross-origin-world!\")\n\n\nDocumentation\n-------------\n\nFor a full list of options, please see the flask-cors\n`documentation <http://flask-cors.corydolphin.com/en/latest/api.html#extension>`__.\n\nPreflight Requests\n------------------\nCORS requests have to send `pre-flight requests <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS#Preflighted_requests_in_CORS>`_\nvia the options method, Sanic by default only allows the ``GET`` method, in order to\nservice your CORS requests you must specify ``OPTIONS`` in the methods argument to\nyour routes decorator.\n\nSanic-CORS includes an ``automatic_options`` configuration parameter to\nallow the plugin handle the ``OPTIONS`` response automatically for you. This is enabled by default, but you\ncan turn it off if you wish to do your own ``OPTIONS`` response.\n\n.. code:: python\n\n CORS(app, automatic_options=True)\n\n @app.delete('/api/auth')\n @auth.login_required\n async def auth_logout(request):\n auth.logout_user(request)\n return json(None, status=OK)\n\nor with the app config key:\n\n.. code:: python\n\n app = Sanic(__name__)\n app.config['CORS_AUTOMATIC_OPTIONS'] = True\n\n CORS(app)\n\n @app.delete('/api/auth')\n @auth.login_required\n async def auth_logout(request):\n auth.logout_user(request)\n return json(None, status=OK)\n\nor directly on the route with the ``cross_origin`` decorator:\n\n.. code:: python\n\n @app.route('/api/auth', methods={'DELETE','OPTIONS'})\n @auth.login_required\n @cross_origin(app, automatic_options=True)\n async def auth_logout(request):\n auth.logout_user(request)\n return json(None, status=OK)\n\nNote: For the third example, you must use ``@route()``, rather than\n``@delete()`` because you need to enable both ``DELETE`` and ``OPTIONS`` to\nwork on that route, even though the decorator is handling the ``OPTIONS``\nresponse.\n\nTests\n-----\n\nA simple set of tests is included in ``test/``. To run, install nose,\nand simply invoke ``nosetests`` or ``python setup.py test`` to exercise\nthe tests.\n\nContributing\n------------\n\nQuestions, comments or improvements? Please create an issue on\n`Github <https://github.com/ashleysommer/sanic-cors>`__. I do my best to\ninclude every contribution proposed in any way that I can.\n\nCredits\n-------\n\nThis Sanic extension is based upon the `Decorator for the HTTP Access\nControl <http://flask.pocoo.org/snippets/56/>`__ written by Armin\nRonacher.\n\n.. |Build Status| image:: https://api.travis-ci.org/ashleysommer/sanic-cors.svg?branch=master\n :target: https://travis-ci.org/ashleysommer/sanic-cors\n.. |Latest Version| image:: https://img.shields.io/pypi/v/Sanic-Cors.svg\n :target: https://pypi.python.org/pypi/Sanic-Cors/\n.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/Sanic-Cors.svg\n :target: https://img.shields.io/pypi/pyversions/Sanic-Cors.svg\n.. |License| image:: http://img.shields.io/:license-mit-blue.svg\n :target: https://pypi.python.org/pypi/Sanic-Cors/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Sanic extension adding a decorator for CORS support. Based on flask-cors by Cory Dolphin.",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/ashleysommer/sanic-cors"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "19bb749505a2b2580321d778e485bf6dd61fabeb0dc2294205a647242e832b74",
"md5": "2160a8396b1935623d23b884d74f1a11",
"sha256": "c3b133ff1f0bb609a53db35f727f5c371dc4ebeb6be4cc2c37c19dd8b9301115"
},
"downloads": -1,
"filename": "Sanic_Cors-2.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2160a8396b1935623d23b884d74f1a11",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 18336,
"upload_time": "2022-10-07T02:04:18",
"upload_time_iso_8601": "2022-10-07T02:04:18.424869Z",
"url": "https://files.pythonhosted.org/packages/19/bb/749505a2b2580321d778e485bf6dd61fabeb0dc2294205a647242e832b74/Sanic_Cors-2.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b2b8fd98a4842e54c1fb3d7b7bc85abbc6d76f79871763eb455a391ddfdb934d",
"md5": "f50abb1619861b4324b099fe24466a7a",
"sha256": "f8d7515da4c8b837871d422c66314c4b5704396a78894b59c50e26aa72a95873"
},
"downloads": -1,
"filename": "Sanic-Cors-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f50abb1619861b4324b099fe24466a7a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33670,
"upload_time": "2022-10-07T02:04:21",
"upload_time_iso_8601": "2022-10-07T02:04:21.030172Z",
"url": "https://files.pythonhosted.org/packages/b2/b8/fd98a4842e54c1fb3d7b7bc85abbc6d76f79871763eb455a391ddfdb934d/Sanic-Cors-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-10-07 02:04:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ashleysommer",
"github_project": "sanic-cors",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "sanic",
"specs": [
[
">=",
"21.9.3"
]
]
},
{
"name": "packaging",
"specs": [
[
">=",
"21.3"
]
]
}
],
"lcname": "sanic-cors"
}
JSON
