Metadata-Version: 1.2
Name: Quart-CORS
Version: 0.5.0
Summary: A Quart extension to provide Cross Origin Resource Sharing, access control, support.
Home-page: https://gitlab.com/pgjones/quart-cors/
Author: P G Jones
Author-email: philip.graham.jones@googlemail.com
License: MIT
Description: Quart-CORS
        ==========
        
        |Build Status| |pypi| |python| |license|
        
        Quart-CORS is an extension for `Quart
        <https://gitlab.com/pgjones/quart>`_ to enable and control `Cross
        Origin Resource Sharing <http://www.w3.org/TR/cors/>`_, CORS (also
        known as access control).
        
        CORS is required to share resources in browsers due to the `Same
        Origin Policy <https://en.wikipedia.org/wiki/Same-origin_policy>`_
        which prevents resources being used from a different origin. An origin
        in this case is defined as the scheme, host and port combined and a
        resource corresponds to a path.
        
        In practice the Same Origin Policy means that a browser visiting
        ``http://quart.com`` will prevent the response of ``GET
        http://api.com`` being read. It will also prevent requests such as
        ``POST http://api.com``. Note that CORS applies to browser initiated
        requests, non-browser clients such as ``requests`` are not subject to
        CORS restrictions.
        
        CORS allows a server to indicate to a browser that certain resources
        can be used, contrary to the Same Origin Policy. It does so via
        access-control headers that inform the browser how the resource can be
        used. For GET requests these headers are sent in the response. For
        non-GET requests the browser must ask the server for the
        access-control headers before sending the actual request, it does so
        via a preflight OPTIONS request.
        
        The Same Origin Policy does not apply to WebSockets, and hence there
        is no need for CORS. Instead the server alone is responsible for
        deciding if the WebSocket is allowed and it should do so by inspecting
        the WebSocket-request origin header.
        
        Simple (GET) requests should return CORS headers specifying the
        origins that are allowed to use the resource (response). This can be
        any origin, ``*`` (wildcard), or a list of specific origins. The
        response should also include a CORS header specifying whether
        response-credentials e.g. cookies can be used. Note that if credential
        sharing is allowed the allowed origins must be specific and not a
        wildcard.
        
        Preflight requests should return CORS headers specifying the origins
        allowed to use the resource, the methods and headers allowed to be
        sent in a request to the resource, whether response credentials can be
        used, and finally which response headers can be used.
        
        Note that certain actions are allowed in the Same Origin Policy such
        as embedding e.g. ``<img src="http://api.com/img.gif">`` and simple
        POSTs. For the purposes of this readme though these complications are
        ignored.
        
        The CORS access control response headers are,
        
        ================================ ===========================================================
        Header name                      Meaning
        -------------------------------- -----------------------------------------------------------
        Access-Control-Allow-Origin      Origins that are allowed to use the resource.
        Access-Control-Allow-Credentials Can credentials be shared.
        Access-Control-Allow-Methods     Methods that may be used in requests to the resource.
        Access-Control-Allow-Headers     Headers that may be sent in requests to the resource.
        Access-Control-Expose-Headers    Headers that may be read in the response from the resource.
        Access-Control-Max-Age           Maximum age to cache the CORS headers for the resource.
        ================================ ===========================================================
        
        Quart-CORS uses the same naming (without the Access-Control prefix)
        for it's arguments and settings when they relate to the same meaning.
        
        Usage
        -----
        
        To add CORS access control headers to all of the routes in the
        application, simply apply the ``cors`` function to the application, or
        to a specific blueprint,
        
        .. code-block:: python
        
            app = Quart(__name__)
            app = cors(app, **settings)
        
            blueprint = Blueprint(__name__)
            blueprint = cors(blueprint, **settings)
        
        alternatively if you wish to add CORS selectively by resource, apply
        the ``route_cors`` function to a route, or the ``websocket_cors``
        function to a WebSocket,
        
        .. code-block:: python
        
            @app.route('/')
            @route_cors(**settings)
            async def handler():
                ...
        
            @app.websocket('/')
            @websocket_cors(allow_origin=...)
            async def handler():
                ...
        
        The ``settings`` are these arguments,
        
        ================= ====================================================
        Argument          type
        ----------------- ----------------------------------------------------
        allow_origin      Union[Set[Union[Pattern, str]], Union[Pattern, str]]
        allow_credentials bool
        allow_methods     Union[Set[str], str]
        allow_headers     Union[Set[str], str]
        expose_headers    Union[Set[str], str]
        max_age           Union[int, flot, timedelta]
        ================= ====================================================
        
        which correspond to the CORS headers noted above. Note that all
        settings are optional and defaults can be specified in the application
        configuration,
        
        ============================ ========================
        Configuration key            type
        ---------------------------- ------------------------
        QUART_CORS_ALLOW_ORIGIN      Set[Union[Pattern, str]]
        QUART_CORS_ALLOW_CREDENTIALS bool
        QUART_CORS_ALLOW_METHODS     Set[str]
        QUART_CORS_ALLOW_HEADERS     Set[str]
        QUART_CORS_EXPOSE_HEADERS    Set[str]
        QUART_CORS_MAX_AGE           float
        ============================ ========================
        
        The ``websocket_cors`` decorator only takes an ``allow_origin``
        argument which defines the origins that are allowed to use the
        WebSocket. A WebSocket request from a disallowed origin will be
        responded to with a 400 response.
        
        The ``allow_origin`` origins should be the origin only (no path, query
        strings or fragments) i.e. ``https://quart.com`` not
        ``https://quart.com/``.
        
        Simple examples
        ~~~~~~~~~~~~~~~
        
        To allow an app to be used from any origin (not recommended as it is
        too permissive),
        
        .. code-block:: python
        
            app = Quart(__name__)
            app = cors(app, allow_origin="*")
        
        To allow a route or WebSocket to be used from another specific domain,
        ``https://quart.com``,
        
        .. code-block:: python
        
            @app.route('/')
            @route_cors(allow_origin="https://quart.com")
            async def handler():
                ...
        
            @app.websocket('/')
            @websocket_cors(allow_origin="https://quart.com")
            async def handler():
                ...
        
        To allow a route or WebSocket to be used from any subdomain (but not
        the domain itself) of ``quart.com``,
        
        .. code-block:: python
        
            @app.route('/')
            @route_cors(allow_origin=re.compile(r"https:\/\/.*\.quart\.com"))
            async def handler():
                ...
        
            @app.websocket('/')
            @websocket_cors(allow_origin=re.compile(r"https:\/\/.*\.quart\.com"))
            async def handler():
                ...
        
        To allow a JSON POST request to an API route, from ``https://quart.com``,
        
        .. code-block:: python
        
            @app.route('/', methods=["POST"])
            @route_cors(
                allow_headers=["content-type"],
                allow_methods=["POST"],
                allow_origin=["https://quart.com"],
            )
            async def handler():
                data = await request.get_json()
                ...
        
        Contributing
        ------------
        
        Quart-CORS is developed on `GitLab
        <https://gitlab.com/pgjones/quart-cors>`_. You are very welcome to
        open `issues <https://gitlab.com/pgjones/quart-cors/issues>`_ or
        propose `merge requests
        <https://gitlab.com/pgjones/quart-cors/merge_requests>`_.
        
        Testing
        ~~~~~~~
        
        The best way to test Quart-CORS is with Tox,
        
        .. code-block:: console
        
            $ pip install tox
            $ tox
        
        this will check the code style and run the tests.
        
        Help
        ----
        
        This README is the best place to start, after that try opening an
        `issue <https://gitlab.com/pgjones/quart-cors/issues>`_.
        
        
        .. |Build Status| image:: https://gitlab.com/pgjones/quart-cors/badges/master/pipeline.svg
           :target: https://gitlab.com/pgjones/quart-cors/commits/master
        
        .. |pypi| image:: https://img.shields.io/pypi/v/quart-cors.svg
           :target: https://pypi.python.org/pypi/Quart-CORS/
        
        .. |python| image:: https://img.shields.io/pypi/pyversions/quart-cors.svg
           :target: https://pypi.python.org/pypi/Quart-CORS/
        
        .. |license| image:: https://img.shields.io/badge/license-MIT-blue.svg
           :target: https://gitlab.com/pgjones/quart-cors/blob/master/LICENSE
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7.0
