[Python-modules-commits] [aiohttp-cors] 01/03: Import aiohttp-cors_0.5.0.orig.tar.gz
Brandon Weeks
bweeks-guest at moszumanska.debian.org
Mon Jul 24 07:38:03 UTC 2017
This is an automated email from the git hooks/post-receive script.
bweeks-guest pushed a commit to branch master
in repository aiohttp-cors.
commit fb272dbc34b3c0f6ffedd257d9a859c90d1054a2
Author: Brandon Weeks <bweeks at google.com>
Date: Mon Jul 24 00:30:36 2017 -0700
Import aiohttp-cors_0.5.0.orig.tar.gz
---
CHANGES.rst | 58 ++
LICENSE | 202 ++++++
MANIFEST.in | 5 +
PKG-INFO | 556 ++++++++++++++++
README.rst | 474 +++++++++++++
aiohttp_cors.egg-info/PKG-INFO | 556 ++++++++++++++++
aiohttp_cors.egg-info/SOURCES.txt | 31 +
aiohttp_cors.egg-info/dependency_links.txt | 1 +
aiohttp_cors.egg-info/requires.txt | 4 +
aiohttp_cors.egg-info/top_level.txt | 1 +
aiohttp_cors/__about__.py | 28 +
aiohttp_cors/__init__.py | 66 ++
aiohttp_cors/_log.py | 22 +
aiohttp_cors/abc.py | 99 +++
aiohttp_cors/cors_config.py | 411 ++++++++++++
aiohttp_cors/resource_options.py | 153 +++++
aiohttp_cors/urldispatcher_router_adapter.py | 433 ++++++++++++
setup.cfg | 8 +
setup.py | 91 +++
tests/__init__.py | 0
tests/aio_test_base.py | 63 ++
tests/doc/__init__.py | 0
tests/doc/test_basic_usage.py | 106 +++
tests/integration/__init__.py | 0
tests/integration/test_main.py | 844 ++++++++++++++++++++++++
tests/integration/test_page.html | 473 +++++++++++++
tests/integration/test_real_browser.py | 347 ++++++++++
tests/unit/__init__.py | 0
tests/unit/test___about__.py | 29 +
tests/unit/test_cors_config.py | 90 +++
tests/unit/test_resource_options.py | 60 ++
tests/unit/test_urldispatcher_router_adapter.py | 117 ++++
32 files changed, 5328 insertions(+)
diff --git a/CHANGES.rst b/CHANGES.rst
new file mode 100644
index 0000000..e3ba630
--- /dev/null
+++ b/CHANGES.rst
@@ -0,0 +1,58 @@
+CHANGES
+=======
+
+0.5.0 (2016-11-18)
+------------------
+
+- Fix compatibility with aiohttp 1.1
+
+
+0.4.0 (2016-04-04)
+------------------
+
+- Fixed support with new Resources objects introduced in ``aiohttp`` 0.21.0.
+ Minimum supported version of ``aiohttp`` is 0.21.4 now.
+
+- New Resources objects are supported.
+ You can specify default configuration for a Resource and use
+ ``allow_methods`` to explicitly list allowed methods (or ``*`` for all
+ HTTP methods):
+
+ .. code-block:: python
+
+ # Allow POST and PUT requests from "http://client.example.org" origin.
+ hello_resource = cors.add(app.router.add_resource("/hello"), {
+ "http://client.example.org":
+ aiohttp_cors.ResourceOptions(
+ allow_methods=["POST", "PUT"]),
+ })
+ # No need to add POST and PUT routes into CORS configuration object.
+ hello_resource.add_route("POST", handler_post)
+ hello_resource.add_route("PUT", handler_put)
+ # Still you can add additional methods to CORS configuration object:
+ cors.add(hello_resource.add_route("DELETE", handler_delete))
+
+- ``AbstractRouterAdapter`` was completely rewritten to be more Router
+ agnostic.
+
+0.3.0 (2016-02-06)
+------------------
+
+- Rename ``UrlDistatcherRouterAdapter`` to ``UrlDispatcherRouterAdapter``.
+
+- Set maximum supported ``aiohttp`` version to ``0.20.2``, see bug #30 for
+ details.
+
+0.2.0 (2015-11-30)
+------------------
+
+- Move ABCs from ``aiohttp_cors.router_adapter`` to ``aiohttp_cors.abc``.
+
+- Rename ``RouterAdapter`` to ``AbstractRouterAdapter``.
+
+- Fix bug with configuring CORS for named routes.
+
+0.1.0 (2015-11-05)
+------------------
+
+* Initial release.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..8f71f43
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,202 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "{}"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright {yyyy} {name of copyright owner}
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..a9f8435
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,5 @@
+include LICENSE
+include CHANGES.rst
+include README.rst
+recursive-include tests *.py
+include tests/integration/test_page.html
diff --git a/PKG-INFO b/PKG-INFO
new file mode 100644
index 0000000..a469a44
--- /dev/null
+++ b/PKG-INFO
@@ -0,0 +1,556 @@
+Metadata-Version: 1.1
+Name: aiohttp-cors
+Version: 0.5.0
+Summary: CORS support for aiohttp
+Home-page: https://github.com/aio-libs/aiohttp-cors
+Author: Vladimir Rutsky
+Author-email: vladimir at rutsky.org
+License: Apache License, Version 2.0
+Description: CORS support for aiohttp
+ ========================
+
+ ``aiohttp_cors`` library implements
+ `Cross Origin Resource Sharing (CORS) <cors_>`__
+ support for `aiohttp <aiohttp_>`__
+ asyncio-powered asynchronous HTTP server.
+
+ Jump directly to `Usage`_ part to see how to use ``aiohttp_cors``.
+
+ Same-origin policy
+ ==================
+
+ Web security model is tightly connected to
+ `Same-origin policy (SOP) <sop_>`__.
+ In short: web pages cannot *Read* resources which origin
+ doesn't match origin of requested page, but can *Embed* (or *Execute*)
+ resources and have limited ability to *Write* resources.
+
+ Origin of a page is defined in the `Standard <cors_>`__ as tuple
+ ``(schema, host, port)``
+ (there is a notable exception with Internet Explorer: it doesn't use port to
+ define origin, but uses it's own
+ `Security Zones <https://msdn.microsoft.com/en-us/library/ms537183.aspx>`__).
+
+ Can *Embed* means that resource from other origin can be embedded into
+ the page,
+ e.g. by using ``<script src="...">``, ``<img src="...">``,
+ ``<iframe src="...">``.
+
+ Cannot *Read* means that resource from other origin *source* cannot be
+ obtained by page
+ (*source* — any information that would allow to reconstruct resource).
+ E.g. the page can *Embed* image with ``<img src="...">``,
+ but it can't get information about specific pixels, so page can't reconstruct
+ original image
+ (though some information from the other resource may still be leaked:
+ e.g. the page can read embedded image dimensions).
+
+ Limited ability to *Write* means, that the page can send POST requests to
+ other origin with limited set of ``Content-Type`` values and headers.
+
+ Restriction to *Read* resource from other origin is related to authentication
+ mechanism that is used by browsers:
+ when browser reads (downloads) resource he automatically sends all security
+ credentials that user previously authorized for that resource
+ (e.g. cookies, HTTP Basic Authentication).
+
+ For example, if *Read* would be allowed and user is authenticated
+ in some internet banking,
+ malicious page would be able to embed internet banking page with ``iframe``
+ (since authentication is done by the browser it may be embedded as if
+ user is directly navigated to internet banking page),
+ then read user private information by reading *source* of the embedded page
+ (which may be not only source code, but, for example,
+ screenshot of the embedded internet banking page).
+
+ Cross-origin resource sharing
+ =============================
+
+ `Cross-origin Resource Sharing (CORS) <cors_>`__ allows to override
+ SOP for specific resources.
+
+ In short, CORS works in the following way.
+
+ When page ``https://client.example.com`` request (*Read*) resource
+ ``https://server.example.com/resource`` that have other origin,
+ browser implicitly appends ``Origin: https://client.example.com`` header
+ to the HTTP request,
+ effectively requesting server to give read permission for
+ the resource to the ``https://client.example.com`` page::
+
+ GET /resource HTTP/1.1
+ Origin: https://client.example.com
+ Host: server.example.com
+
+ If server allows access from the page to the resource, it responds with
+ resource with ``Access-Control-Allow-Origin: https://client.example.com``
+ HTTP header
+ (optionally allowing exposing custom server headers to the page and
+ enabling use of the user credentials on the server resource)::
+
+ Access-Control-Allow-Origin: https://client.example.com
+ Access-Control-Allow-Credentials: true
+ Access-Control-Expose-Headers: X-Server-Header
+
+ Browser checks, if server responded with proper
+ ``Access-Control-Allow-Origin`` header and accordingly allows or denies
+ access for the obtained resource to the page.
+
+ CORS specification designed in a way that servers that are not aware
+ of CORS will not expose any additional information, except allowed by the
+ SOP.
+
+ To request resources with custom headers or using custom HTTP methods
+ (e.g. ``PUT``, ``DELETE``) that are not allowed by SOP,
+ CORS-enabled browser first send *preflight request* to the
+ resource using ``OPTIONS`` method, in which he queries access to the resource
+ with specific method and headers::
+
+ OPTIONS / HTTP/1.1
+ Origin: https://client.example.com
+ Access-Control-Request-Method: PUT
+ Access-Control-Request-Headers: X-Client-Header
+
+ CORS-enabled server responds is requested method is allowed and which of
+ the specified headers are allowed::
+
+ Access-Control-Allow-Origin: https://client.example.com
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Methods: PUT
+ Access-Control-Allow-Headers: X-Client-Header
+ Access-Control-Max-Age: 3600
+
+ Browser checks response to preflight request, and, if actual request allowed,
+ does actual request.
+
+ Installation
+ ============
+
+ You can install ``aiohttp_cors`` as a typical Python library from PyPI or
+ from git:
+
+ .. code-block:: bash
+
+ $ pip install aiohttp_cors
+
+ Note that ``aiohttp_cors`` requires versions of Python >= 3.4.1 and
+ ``aiohttp`` >= 0.21.4.
+
+ Usage
+ =====
+
+ To use ``aiohttp_cors`` you need to configure the application and
+ enable CORS on
+ `resources and routes <https://aiohttp.readthedocs.org/en/stable/web.html#resources-and-routes>`__
+ that you want to expose:
+
+ .. code-block:: python
+
+ import asyncio
+ from aiohttp import web
+ import aiohttp_cors
+
+ @asyncio.coroutine
+ def handler(request):
+ return web.Response(
+ text="Hello!",
+ headers={
+ "X-Custom-Server-Header": "Custom data",
+ })
+
+ app = web.Application()
+
+ # `aiohttp_cors.setup` returns `aiohttp_cors.CorsConfig` instance.
+ # The `cors` instance will store CORS configuration for the
+ # application.
+ cors = aiohttp_cors.setup(app)
+
+ # To enable CORS processing for specific route you need to add
+ # that route to the CORS configuration object and specify its
+ # CORS options.
+ resource = cors.add(app.router.add_resource("/hello"))
+ route = cors.add(
+ resource.add_route("GET", handler), {
+ "http://client.example.org": aiohttp_cors.ResourceOptions(
+ allow_credentials=True,
+ expose_headers=("X-Custom-Server-Header",),
+ allow_headers=("X-Requested-With", "Content-Type"),
+ max_age=3600,
+ )
+ })
+
+ Each route has it's own CORS configuration passed in ``CorsConfig.add()``
+ method.
+
+ CORS configuration is a mapping from origins to options for that origins.
+
+ In the example above CORS is configured for the resource under path ``/hello``
+ and HTTP method ``GET``, and in the context of CORS:
+
+ * This resource will be available using CORS only to
+ ``http://client.example.org`` origin.
+
+ * Passing of credentials to this resource will be allowed.
+
+ * The resource will expose to the client ``X-Custom-Server-Header``
+ server header.
+
+ * The client will be allowed to pass ``X-Requested-With`` and
+ ``Content-Type`` headers to the server.
+
+ * Preflight requests will be allowed to be cached by client for ``3600``
+ seconds.
+
+ Resource will be available only to the explicitly specified origins.
+ You can specify "all other origins" using special ``*`` origin:
+
+ .. code-block:: python
+
+ cors.add(route, {
+ "*":
+ aiohttp_cors.ResourceOptions(allow_credentials=False),
+ "http://client.example.org":
+ aiohttp_cors.ResourceOptions(allow_credentials=True),
+ })
+
+ Here the resource specified by ``route`` will be available to all origins with
+ disallowed credentials passing, and with allowed credentials passing only to
+ ``http://client.example.org``.
+
+ By default ``ResourceOptions`` will be constructed without any allowed CORS
+ options.
+ This means, that resource will be available using CORS to specified origin,
+ but client will not be allowed to send either credentials,
+ or send non-simple headers, or read from server non-simple headers.
+
+ To enable sending or receiving all headers you can specify special value
+ ``*`` instead of sequence of headers:
+
+ .. code-block:: python
+
+ cors.add(route, {
+ "http://client.example.org":
+ aiohttp_cors.ResourceOptions(
+ expose_headers="*",
+ allow_headers="*"),
+ })
+
+ You can specify default CORS-enabled resource options using
+ ``aiohttp_cors.setup()``'s ``defaults`` argument:
+
+ .. code-block:: python
+
+ cors = aiohttp_cors.setup(app, defaults={
+ # Allow all to read all CORS-enabled resources from
+ # http://client.example.org.
+ "http://client.example.org": aiohttp_cors.ResourceOptions(),
+ })
+
+ # Enable CORS on routes.
+
+ # According to defaults POST and PUT will be available only to
+ # "http://client.example.org".
+ hello_resource = cors.add(app.router.add_resource("/hello"))
+ cors.add(hello_resource.add_route("POST", handler_post))
+ cors.add(hello_resource.add_route("PUT", handler_put))
+
+ # In addition to "http://client.example.org", GET request will be
+ # allowed from "http://other-client.example.org" origin.
+ cors.add(hello_resource.add_route("GET", handler), {
+ "http://other-client.example.org":
+ aiohttp_cors.ResourceOptions(),
+ })
+
+ # CORS will be enabled only on the resources added to `CorsConfig`,
+ # so following resource will be NOT CORS-enabled.
+ app.router.add_route("GET", "/private", handler)
+
+ Also you can specify default options for resources:
+
+ .. code-block:: python
+
+ # Allow POST and PUT requests from "http://client.example.org" origin.
+ hello_resource = cors.add(app.router.add_resource("/hello"), {
+ "http://client.example.org": aiohttp_cors.ResourceOptions(),
+ })
+ cors.add(hello_resource.add_route("POST", handler_post))
+ cors.add(hello_resource.add_route("PUT", handler_put))
+
+ Resource CORS configuration allows to use ``allow_methods`` option that
+ explicitly specifies list of allowed HTTP methods for origin
+ (or ``*`` for all HTTP methods).
+ By using this option it is not required to add all resource routes to
+ CORS configuration object:
+
+ .. code-block:: python
+
+ # Allow POST and PUT requests from "http://client.example.org" origin.
+ hello_resource = cors.add(app.router.add_resource("/hello"), {
+ "http://client.example.org":
+ aiohttp_cors.ResourceOptions(allow_methods=["POST", "PUT"]),
+ })
+ # No need to add POST and PUT routes into CORS configuration object.
+ hello_resource.add_route("POST", handler_post)
+ hello_resource.add_route("PUT", handler_put)
+ # Still you can add additional methods to CORS configuration object:
+ cors.add(hello_resource.add_route("DELETE", handler_delete))
+
+ Here is an example of how to enable CORS for all origins with all CORS
+ features:
+
+ .. code-block:: python
+
+ cors = aiohttp_cors.setup(app, defaults={
+ "*": aiohttp_cors.ResourceOptions(
+ allow_credentials=True,
+ expose_headers="*",
+ allow_headers="*",
+ )
+ })
+
+ # Add all resources to `CorsConfig`.
+ resource = cors.add(app.router.add_resource("/hello"))
+ cors.add(resource.add_route("GET", handler_get))
+ cors.add(resource.add_route("PUT", handler_put))
+ cors.add(resource.add_route("POST", handler_put))
+ cors.add(resource.add_route("DELETE", handler_delete))
+
+ Old routes API is supported — you can use ``router.add_router`` and
+ ``router.register_route`` as before, though this usage is discouraged:
+
+ .. code-block:: python
+
+ cors.add(
+ app.router.add_route("GET", "/hello", handler), {
+ "http://client.example.org": aiohttp_cors.ResourceOptions(
+ allow_credentials=True,
+ expose_headers=("X-Custom-Server-Header",),
+ allow_headers=("X-Requested-With", "Content-Type"),
+ max_age=3600,
+ )
+ })
+
+ You can enable CORS for all added routes by accessing routes list
+ in the router:
+
+ .. code-block:: python
+
+ # Setup application routes.
+ app.router.add_route("GET", "/hello", handler_get)
+ app.router.add_route("PUT", "/hello", handler_put)
+ app.router.add_route("POST", "/hello", handler_put)
+ app.router.add_route("DELETE", "/hello", handler_delete)
+
+ # Configure default CORS settings.
+ cors = aiohttp_cors.setup(app, defaults={
+ "*": aiohttp_cors.ResourceOptions(
+ allow_credentials=True,
+ expose_headers="*",
+ allow_headers="*",
+ )
+ })
+
+ # Configure CORS on all routes.
+ for route in list(app.router.routes()):
+ cors.add(route)
+
+ Security
+ ========
+
+ TODO: fill this
+
+ Development
+ ===========
+
+ To setup development environment:
+
+ .. code-block:: bash
+
+ # Clone sources repository:
+ git clone https://github.com/aio-libs/aiohttp_cors.git .
+ # Create and activate virtual Python environment:
+ python3 -m venv env
+ source env/bin/activate
+ # Install requirements and aiohttp_cors into virtual environment
+ pip install -r requirements-dev.txt
+
+ To run tests:
+
+ .. code-block:: bash
+
+ tox
+
+ To run only runtime tests in current environment:
+
+ .. code-block:: bash
+
+ py.test
+
+ To run only static code analysis checks:
+
+ .. code-block:: bash
+
+ tox -e check
+
+ Running Selenium tests
+ ----------------------
+
+ To run Selenium tests with Firefox web driver you need to install Firefox.
+
+ To run Selenium tests with Chromium web driver you need to:
+
+ 1. Install Chrome driver. On Ubuntu 14.04 it's in ``chromium-chromedriver``
+ package.
+
+ 2. Either add ``chromedriver`` to PATH or set ``WEBDRIVER_CHROMEDRIVER_PATH``
+ environment variable to ``chromedriver``, e.g. on Ubuntu 14.04
+ ``WEBDRIVER_CHROMEDRIVER_PATH=/usr/lib/chromium-browser/chromedriver``.
+
+ Release process
+ ---------------
+
+ Prerequisites:
+
+ 1. Install fresh versions of setuptools and pip.
+ Install ``wheel`` for building wheels.
+ Install ``twine`` for uploading to PyPI.
+
+ .. code-block:: bash
+
+ pip install -U pip setuptools twine wheel
+
+ 2. Configure PyPI credentials in ``~/.pypirc``.
+
+ To release version ``vA.B.C`` from the current version of ``master`` branch
+ you need to:
+
+ 1. Create local branch ``vA.B.C``.
+ 2. In ``CHANGES.rst`` set release date to today.
+ 3. In ``aiohttp_cors/__about__.py`` change version from ``A.B.Ca0`` to
+ ``A.B.C``.
+ 4. Create pull request with ``vA.B.C`` branch, wait for all checks to
+ successfully finish (Travis and Appveyor).
+ 5. Merge pull request to master.
+ 6. Update and checkout ``master`` branch.
+ 7. Build distribution:
+
+ .. code-block:: bash
+
+ rm -rf build dist; python setup.py sdist bdist_wheel
+
+ 8. Upload new release to PyPI:
+
+ .. code-block:: bash
+
+ twine upload dist/*
+
+ 9. Create and push tag for release version to GitHub:
+
+ .. code-block:: bash
+
+ git tag vA.B.C
+ git push --tags
+
+ 10. Edit release description on GitHub if needed.
+ 11. Announce new release on the *aio-libs* mailing list:
+ https://groups.google.com/forum/#!forum/aio-libs.
+
+ Post release steps:
+
+ 1. In ``CHANGES.rst`` add template for the next release.
+ 2. In ``aiohttp_cors/__about__.py`` change version from ``A.B.C`` to
+ ``A.(B + 1).0a0``.
+
+ Bugs
+ ====
+
+ Please report bugs, issues, feature requests, etc. on
+ `GitHub <https://github.com/aio-libs/aiohttp_cors/issues>`__.
+
+
+ License
+ =======
+
+ Copyright 2015 Vladimir Rutsky <vladimir at rutsky.org>.
+
+ Licensed under the
+ `Apache License, Version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`__,
+ see ``LICENSE`` file for details.
+
+ .. _cors: http://www.w3.org/TR/cors/
+ .. _aiohttp: https://github.com/KeepSafe/aiohttp/
+ .. _sop: https://en.wikipedia.org/wiki/Same-origin_policy
+
+
+ CHANGES
+ =======
+
+ 0.5.0 (2016-11-18)
+ ------------------
+
+ - Fix compatibility with aiohttp 1.1
+
+
+ 0.4.0 (2016-04-04)
+ ------------------
+
+ - Fixed support with new Resources objects introduced in ``aiohttp`` 0.21.0.
+ Minimum supported version of ``aiohttp`` is 0.21.4 now.
+
+ - New Resources objects are supported.
+ You can specify default configuration for a Resource and use
+ ``allow_methods`` to explicitly list allowed methods (or ``*`` for all
+ HTTP methods):
+
+ .. code-block:: python
+
+ # Allow POST and PUT requests from "http://client.example.org" origin.
+ hello_resource = cors.add(app.router.add_resource("/hello"), {
+ "http://client.example.org":
+ aiohttp_cors.ResourceOptions(
+ allow_methods=["POST", "PUT"]),
+ })
+ # No need to add POST and PUT routes into CORS configuration object.
+ hello_resource.add_route("POST", handler_post)
+ hello_resource.add_route("PUT", handler_put)
+ # Still you can add additional methods to CORS configuration object:
+ cors.add(hello_resource.add_route("DELETE", handler_delete))
+
+ - ``AbstractRouterAdapter`` was completely rewritten to be more Router
+ agnostic.
+
+ 0.3.0 (2016-02-06)
+ ------------------
+
+ - Rename ``UrlDistatcherRouterAdapter`` to ``UrlDispatcherRouterAdapter``.
+
+ - Set maximum supported ``aiohttp`` version to ``0.20.2``, see bug #30 for
+ details.
+
+ 0.2.0 (2015-11-30)
+ ------------------
+
+ - Move ABCs from ``aiohttp_cors.router_adapter`` to ``aiohttp_cors.abc``.
+
+ - Rename ``RouterAdapter`` to ``AbstractRouterAdapter``.
+
+ - Fix bug with configuring CORS for named routes.
+
+ 0.1.0 (2015-11-05)
+ ------------------
+
+ * Initial release.
+
+Platform: UNKNOWN
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Development Status :: 3 - Alpha
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..80e00c1
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,474 @@
+CORS support for aiohttp
+========================
+
+``aiohttp_cors`` library implements
+`Cross Origin Resource Sharing (CORS) <cors_>`__
+support for `aiohttp <aiohttp_>`__
+asyncio-powered asynchronous HTTP server.
+
+Jump directly to `Usage`_ part to see how to use ``aiohttp_cors``.
+
+Same-origin policy
+==================
+
+Web security model is tightly connected to
+`Same-origin policy (SOP) <sop_>`__.
+In short: web pages cannot *Read* resources which origin
+doesn't match origin of requested page, but can *Embed* (or *Execute*)
+resources and have limited ability to *Write* resources.
+
+Origin of a page is defined in the `Standard <cors_>`__ as tuple
+``(schema, host, port)``
+(there is a notable exception with Internet Explorer: it doesn't use port to
+define origin, but uses it's own
+`Security Zones <https://msdn.microsoft.com/en-us/library/ms537183.aspx>`__).
+
+Can *Embed* means that resource from other origin can be embedded into
+the page,
+e.g. by using ``<script src="...">``, ``<img src="...">``,
+``<iframe src="...">``.
+
+Cannot *Read* means that resource from other origin *source* cannot be
+obtained by page
+(*source* — any information that would allow to reconstruct resource).
+E.g. the page can *Embed* image with ``<img src="...">``,
+but it can't get information about specific pixels, so page can't reconstruct
+original image
+(though some information from the other resource may still be leaked:
+e.g. the page can read embedded image dimensions).
+
+Limited ability to *Write* means, that the page can send POST requests to
+other origin with limited set of ``Content-Type`` values and headers.
+
+Restriction to *Read* resource from other origin is related to authentication
+mechanism that is used by browsers:
+when browser reads (downloads) resource he automatically sends all security
+credentials that user previously authorized for that resource
+(e.g. cookies, HTTP Basic Authentication).
+
+For example, if *Read* would be allowed and user is authenticated
+in some internet banking,
+malicious page would be able to embed internet banking page with ``iframe``
+(since authentication is done by the browser it may be embedded as if
+user is directly navigated to internet banking page),
+then read user private information by reading *source* of the embedded page
+(which may be not only source code, but, for example,
+screenshot of the embedded internet banking page).
+
+Cross-origin resource sharing
+=============================
+
+`Cross-origin Resource Sharing (CORS) <cors_>`__ allows to override
+SOP for specific resources.
+
+In short, CORS works in the following way.
+
+When page ``https://client.example.com`` request (*Read*) resource
+``https://server.example.com/resource`` that have other origin,
+browser implicitly appends ``Origin: https://client.example.com`` header
+to the HTTP request,
+effectively requesting server to give read permission for
+the resource to the ``https://client.example.com`` page::
+
+ GET /resource HTTP/1.1
+ Origin: https://client.example.com
+ Host: server.example.com
+
+If server allows access from the page to the resource, it responds with
+resource with ``Access-Control-Allow-Origin: https://client.example.com``
+HTTP header
+(optionally allowing exposing custom server headers to the page and
+enabling use of the user credentials on the server resource)::
+
+ Access-Control-Allow-Origin: https://client.example.com
+ Access-Control-Allow-Credentials: true
+ Access-Control-Expose-Headers: X-Server-Header
+
+Browser checks, if server responded with proper
+``Access-Control-Allow-Origin`` header and accordingly allows or denies
+access for the obtained resource to the page.
+
+CORS specification designed in a way that servers that are not aware
+of CORS will not expose any additional information, except allowed by the
+SOP.
+
+To request resources with custom headers or using custom HTTP methods
+(e.g. ``PUT``, ``DELETE``) that are not allowed by SOP,
+CORS-enabled browser first send *preflight request* to the
+resource using ``OPTIONS`` method, in which he queries access to the resource
+with specific method and headers::
+
+ OPTIONS / HTTP/1.1
+ Origin: https://client.example.com
+ Access-Control-Request-Method: PUT
+ Access-Control-Request-Headers: X-Client-Header
+
+CORS-enabled server responds is requested method is allowed and which of
+the specified headers are allowed::
+
+ Access-Control-Allow-Origin: https://client.example.com
... 4549 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/aiohttp-cors.git
More information about the Python-modules-commits
mailing list