A Flask extension adding a decorator for CORS support
Project description
Flask-CORS
==========
|Build Status| |Latest Version| |Downloads| |Supported Python versions|
|License|
A Flask extension for handling Cross Origin Resource Sharing (CORS),
making cross-origin AJAX possible.
Installation
------------
Install the extension with using pip, or easy\_install.
.. code:: bash
$ pip install -U flask-cors
Usage
-----
This extension enables CORS support either via a decorator, or a Flask
extension. There are three examples shown in the
`examples <https://github.com/wcdolphin/flask-cors/tree/master/examples>`__
directory, showing the major use cases. The suggested configuration is
the
`simple\_example.py <https://github.com/wcdolphin/flask-cors/tree/master/examples/simple_example.py>`__,
or the
`app\_example.py <https://github.com/wcdolphin/flask-cors/tree/master/examples/app_based_example.py>`__.
Simple Usage
~~~~~~~~~~~~
In the simplest case, initialize the Flask-Cors extension with default
arguments in order to allow CORS on all routes.
.. code:: python
app = Flask(__name__)
cors = CORS(app)
@app.route("/")
def helloWorld():
return "Hello, cross-origin-world!"
Resource specific CORS
^^^^^^^^^^^^^^^^^^^^^^
Alternatively, a list of resources and associated settings for CORS can
be supplied, selectively enables CORS support on a set of paths on your
app.
Note: this resources parameter can also be set in your application's
config.
.. code:: python
app = Flask(__name__)
cors = CORS(app, resources={r"/api/*": {"origins": "*"}})
@app.route("/api/v1/users")
def list_users():
return "user example"
Route specific CORS via decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This extension also exposes a simple decorator to decorate flask routes
with. Simply add ``@cross_origin()`` below a call to Flask's
``@app.route(..)`` incanation to accept the default options and allow
CORS on a given route.
.. code:: python
@app.route("/")
@cross_origin() # allow all origins all methods.
def helloWorld():
return "Hello, cross-origin-world!"
Options
~~~~~~~
origins
^^^^^^^
Default : '\*'
The origin, or list of origins to allow requests from. The origin(s) may
be regular expressions, exact origins, or else an asterisk.
methods
^^^^^^^
Default : [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE]
The method or list of methods which the allowed origins are allowed to
access.
headers
^^^^^^^
Default : None
The header or list of header field names which can be used when this
resource is accessed by allowed origins.
expose\_headers
^^^^^^^^^^^^^^^
Default : None
The header or list of headers which are are safe to expose to browsers.
supports\_credentials
^^^^^^^^^^^^^^^^^^^^^
Default : False
Allows users to make authenticated requests. If true, injects the
``Access-Control-Allow-Credentials`` header in responses.
max\_age
^^^^^^^^
Default : None
The maximum time for which this CORS request maybe cached. This value is
set as the ``Access-Control-Max-Age`` header.
send\_wildcard
^^^^^^^^^^^^^^
Default : True
If True, and the origins parameter is ``*``, a wildcard
``Access-Control-Allow-Origin`` header is sent, rather than the
request's ``Origin`` header.
always\_send
^^^^^^^^^^^^
Default : True
If True, CORS headers are sent even if there is no ``Origin`` in the
request's headers.
automatic\_options
^^^^^^^^^^^^^^^^^^
Default : True
| If True, CORS headers will be returned for OPTIONS requests. For use
with cross domain POST requests which preflight OPTIONS requests, you
will need to specifically allow the Content-Type header.
| \*\* Only applicable for use in the decorator\*\*
vary\_header
^^^^^^^^^^^^
Default : True
If True, the header Vary: Origin will be returned as per suggestion by
the W3 implementation guidelines. Setting this header when the
``Access-Control-Allow-Origin`` is dynamically generated (e.g. when
there is more than one allowed origin, and an Origin than '\*' is
returned) informs CDNs and other caches that the CORS headers are
dynamic, and cannot be re-used. If False, the Vary header will never be
injected or altered.
Application-wide options
~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, you can set all parameters **except automatic\_options**
in an app's config object. Setting these at the application level
effectively changes the default value for your application, while still
allowing you to override it on a per-resource basis, either via the CORS
Flask-Extension and regular expressions, or via the ``@cross_origin()``
decorator.
The application-wide configuration options are identical to the keyword
arguments to ``cross_origin``, creatively prefixed with ``CORS_``
- CORS\_ORIGINS
- CORS\_METHODS
- CORS\_HEADERS
- CORS\_EXPOSE\_HEADERS
- CORS\_ALWAYS\_SEND
- CORS\_MAX\_AGE
- CORS\_SEND\_WILDCARD
- CORS\_ALWAYS\_SEND
Using JSON with CORS
~~~~~~~~~~~~~~~~~~~~
When using JSON cross origin, browsers will issue a pre-flight OPTIONS
request for POST requests. In order for browsers to allow POST requests
with a JSON content type, you must allow the Content-Type header. The
simplest way to do this is to simply set the CORS\_HEADERS configuration
value on your application, e.g:
.. code:: python
app.config['CORS_HEADERS'] = 'Content-Type'
Documentation
-------------
For a full list of options, please see the full
`documentation <http://flask-cors.readthedocs.org/en/latest/>`__
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/wcdolphin/flask-cors>`__, tweet at
`@wcdolphin <https://twitter.com/wcdolphin>`__ or send me an email.
Credits
-------
This Flask 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/wcdolphin/flask-cors.svg?branch=master
:target: https://travis-ci.org/wcdolphin/flask-cors
.. |Latest Version| image:: https://pypip.in/version/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |Downloads| image:: https://pypip.in/download/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |Supported Python versions| image:: https://pypip.in/py_versions/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |License| image:: https://pypip.in/license/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
==========
|Build Status| |Latest Version| |Downloads| |Supported Python versions|
|License|
A Flask extension for handling Cross Origin Resource Sharing (CORS),
making cross-origin AJAX possible.
Installation
------------
Install the extension with using pip, or easy\_install.
.. code:: bash
$ pip install -U flask-cors
Usage
-----
This extension enables CORS support either via a decorator, or a Flask
extension. There are three examples shown in the
`examples <https://github.com/wcdolphin/flask-cors/tree/master/examples>`__
directory, showing the major use cases. The suggested configuration is
the
`simple\_example.py <https://github.com/wcdolphin/flask-cors/tree/master/examples/simple_example.py>`__,
or the
`app\_example.py <https://github.com/wcdolphin/flask-cors/tree/master/examples/app_based_example.py>`__.
Simple Usage
~~~~~~~~~~~~
In the simplest case, initialize the Flask-Cors extension with default
arguments in order to allow CORS on all routes.
.. code:: python
app = Flask(__name__)
cors = CORS(app)
@app.route("/")
def helloWorld():
return "Hello, cross-origin-world!"
Resource specific CORS
^^^^^^^^^^^^^^^^^^^^^^
Alternatively, a list of resources and associated settings for CORS can
be supplied, selectively enables CORS support on a set of paths on your
app.
Note: this resources parameter can also be set in your application's
config.
.. code:: python
app = Flask(__name__)
cors = CORS(app, resources={r"/api/*": {"origins": "*"}})
@app.route("/api/v1/users")
def list_users():
return "user example"
Route specific CORS via decorator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This extension also exposes a simple decorator to decorate flask routes
with. Simply add ``@cross_origin()`` below a call to Flask's
``@app.route(..)`` incanation to accept the default options and allow
CORS on a given route.
.. code:: python
@app.route("/")
@cross_origin() # allow all origins all methods.
def helloWorld():
return "Hello, cross-origin-world!"
Options
~~~~~~~
origins
^^^^^^^
Default : '\*'
The origin, or list of origins to allow requests from. The origin(s) may
be regular expressions, exact origins, or else an asterisk.
methods
^^^^^^^
Default : [GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE]
The method or list of methods which the allowed origins are allowed to
access.
headers
^^^^^^^
Default : None
The header or list of header field names which can be used when this
resource is accessed by allowed origins.
expose\_headers
^^^^^^^^^^^^^^^
Default : None
The header or list of headers which are are safe to expose to browsers.
supports\_credentials
^^^^^^^^^^^^^^^^^^^^^
Default : False
Allows users to make authenticated requests. If true, injects the
``Access-Control-Allow-Credentials`` header in responses.
max\_age
^^^^^^^^
Default : None
The maximum time for which this CORS request maybe cached. This value is
set as the ``Access-Control-Max-Age`` header.
send\_wildcard
^^^^^^^^^^^^^^
Default : True
If True, and the origins parameter is ``*``, a wildcard
``Access-Control-Allow-Origin`` header is sent, rather than the
request's ``Origin`` header.
always\_send
^^^^^^^^^^^^
Default : True
If True, CORS headers are sent even if there is no ``Origin`` in the
request's headers.
automatic\_options
^^^^^^^^^^^^^^^^^^
Default : True
| If True, CORS headers will be returned for OPTIONS requests. For use
with cross domain POST requests which preflight OPTIONS requests, you
will need to specifically allow the Content-Type header.
| \*\* Only applicable for use in the decorator\*\*
vary\_header
^^^^^^^^^^^^
Default : True
If True, the header Vary: Origin will be returned as per suggestion by
the W3 implementation guidelines. Setting this header when the
``Access-Control-Allow-Origin`` is dynamically generated (e.g. when
there is more than one allowed origin, and an Origin than '\*' is
returned) informs CDNs and other caches that the CORS headers are
dynamic, and cannot be re-used. If False, the Vary header will never be
injected or altered.
Application-wide options
~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, you can set all parameters **except automatic\_options**
in an app's config object. Setting these at the application level
effectively changes the default value for your application, while still
allowing you to override it on a per-resource basis, either via the CORS
Flask-Extension and regular expressions, or via the ``@cross_origin()``
decorator.
The application-wide configuration options are identical to the keyword
arguments to ``cross_origin``, creatively prefixed with ``CORS_``
- CORS\_ORIGINS
- CORS\_METHODS
- CORS\_HEADERS
- CORS\_EXPOSE\_HEADERS
- CORS\_ALWAYS\_SEND
- CORS\_MAX\_AGE
- CORS\_SEND\_WILDCARD
- CORS\_ALWAYS\_SEND
Using JSON with CORS
~~~~~~~~~~~~~~~~~~~~
When using JSON cross origin, browsers will issue a pre-flight OPTIONS
request for POST requests. In order for browsers to allow POST requests
with a JSON content type, you must allow the Content-Type header. The
simplest way to do this is to simply set the CORS\_HEADERS configuration
value on your application, e.g:
.. code:: python
app.config['CORS_HEADERS'] = 'Content-Type'
Documentation
-------------
For a full list of options, please see the full
`documentation <http://flask-cors.readthedocs.org/en/latest/>`__
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/wcdolphin/flask-cors>`__, tweet at
`@wcdolphin <https://twitter.com/wcdolphin>`__ or send me an email.
Credits
-------
This Flask 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/wcdolphin/flask-cors.svg?branch=master
:target: https://travis-ci.org/wcdolphin/flask-cors
.. |Latest Version| image:: https://pypip.in/version/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |Downloads| image:: https://pypip.in/download/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |Supported Python versions| image:: https://pypip.in/py_versions/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
.. |License| image:: https://pypip.in/license/Flask-Cors/badge.svg
:target: https://pypi.python.org/pypi/Flask-Cors/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Flask-Cors-1.7.4.tar.gz
(15.3 kB
view hashes)
Built Distributions
Flask_Cors-1.7.4-py3-none-any.whl
(10.0 kB
view hashes)
Flask_Cors-1.7.4-py2-none-any.whl
(10.0 kB
view hashes)
Close
Hashes for Flask_Cors-1.7.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3e010865db0275d69285640921253ce15b9678a7b48cd4296c33454c2623dcf |
|
MD5 | 148e733479720a2dfcf05309c24f7c92 |
|
BLAKE2b-256 | 9b00fc666da2576b851c3d57b993b2990ea40550eeb599dd814bc46e71d4a8aa |
Close
Hashes for Flask_Cors-1.7.4-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 08960b5c59c886fbf7225bc2acdc28cc6a2cf5379ec705adcf554da9df9d8dd6 |
|
MD5 | 25708daa10a773dac31d3d28986eb28f |
|
BLAKE2b-256 | c0f5b5a87ff24819d78ddeea1ccb26af017637590015b7a30d78f666209e497b |