aiohttp-cors

Common errors

• AttributeError: 'CORS' object has no attribute 'add'

  cause This error occurs when attempting to use the 'add' method on a 'CORS' object, which does not have such a method.
  fix Ensure that you are using the correct methods provided by the 'aiohttp-cors' library, such as 'setup' and 'add' on the 'CorsConfig' object returned by 'setup'.

• ImportError: cannot import name 'CORS' from 'aiohttp_cors'

  cause This error occurs when trying to import 'CORS' directly from 'aiohttp_cors', which does not expose a 'CORS' class.
  fix Import 'setup' from 'aiohttp_cors' and use it to configure CORS in your application.

• TypeError: setup() missing 1 required positional argument: 'app'

  cause This error occurs when calling 'setup()' without passing the 'app' instance as an argument.
  fix Pass your 'app' instance to the 'setup()' function: 'cors = aiohttp_cors.setup(app)'.

• TypeError: add() missing 1 required positional argument: 'route'

  cause This error occurs when calling 'add()' without passing a route to be configured for CORS.
  fix Ensure you pass the route to the 'add()' method: 'cors.add(app.router.add_route("GET", "/path", handler))'.

• AttributeError: 'Resource' object has no attribute 'add_route'

  cause This error occurs when attempting to call 'add_route' on a 'Resource' object, which does not have such a method.
  fix Use 'app.router.add_route' to add routes before configuring CORS.

Warnings

• breaking aiohttp-cors has strict compatibility requirements with `aiohttp` and `Python` versions. As of v0.8.0, it requires `aiohttp>=3.9` and `Python>=3.9`. Earlier versions of aiohttp-cors were compatible with older aiohttp and Python versions, but upgrading both libraries simultaneously is often necessary.
  Fix: Always check the `aiohttp-cors` `CHANGES.rst` or `setup.py` for precise `aiohttp` and `Python` version requirements when upgrading or setting up. Upgrade `aiohttp` and `Python` versions as needed.
• gotcha CORS configuration must be explicitly applied to each route or resource you wish to expose. Simply initializing `aiohttp_cors.setup(app)` does not automatically enable CORS on all your application's routes.
  Fix: After `aiohttp_cors.setup(app, defaults=...)`, you must use `cors.add(app.router.add_resource(...))` or `cors.add(route)` for individual routes. If you want to enable CORS for all existing routes, iterate over `app.router.routes()` and call `cors.add(route)` for each.
• deprecated The use of `asyncio.coroutine` decorators for handlers is deprecated in Python 3.5+ in favor of `async def` syntax. While `aiohttp-cors` itself supports this, ensure your application handlers use modern async/await syntax.
  Fix: Refactor `asyncio.coroutine` decorated functions to use `async def` syntax for better readability and alignment with modern Python best practices. For example, `@asyncio.coroutine def my_handler(...)` becomes `async def my_handler(...)`.
• breaking In `aiohttp-cors` v0.7.0, the web view check became implicit and type-based, and support for Python 3.4 was disabled. If you were relying on explicit view checks or using Python 3.4, this will break your application.
  Fix: Ensure your application is running on Python 3.5+ (preferably 3.9+ as per current requirements) and review any custom logic related to aiohttp views that might have been affected by the change to implicit type-based checking.

Install

• pip install aiohttp-cors Install latest version

Imports

• aiohttp_cors
  wrong:

  from aiohttp_cors import setup

  correct:

  import aiohttp_cors

  The primary functions `setup` and `add` are typically accessed directly from the imported `aiohttp_cors` module.
• CorsViewMixin

  from aiohttp_cors import CorsViewMixin

  Used for enabling CORS on aiohttp.web.View classes.

Quickstart

This quickstart sets up a basic aiohttp web application and applies a permissive CORS policy to a '/hello' endpoint, allowing requests from any origin. It demonstrates how to initialize CORS for the application and then apply it to specific routes or resources. It also shows a commented-out section for applying CORS to all routes programmatically.

import aiohttp_cors
from aiohttp import web

async def handler(request):
    return web.Response(text="Hello from CORS-enabled endpoint!")

async def main():
    app = web.Application()

    # Setup CORS for all origins, allowing all headers and methods
    cors = aiohttp_cors.setup(app, defaults={
        "*": aiohttp_cors.ResourceOptions(
            allow_credentials=True,
            expose_headers="*",
            allow_headers="*",
            allow_methods="*"
        )
    })

    # Add a route and enable CORS for it
    resource = cors.add(app.router.add_resource("/hello"))
    resource.add_route("GET", handler)

    # Alternatively, you can add CORS to existing routes directly
    # For example, if you had:
    # app.router.add_post("/data", data_handler)
    # cors.add(app.router.get("/data"))

    # To apply CORS to ALL existing routes:
    # for route in list(app.router.routes()):
    #     if not route.is_cors_enabled():
    #         cors.add(route)

    print("Server starting on http://localhost:8080")
    runner = web.AppRunner(app)
    await runner.setup()
    site = web.TCPSite(runner, 'localhost', 8080)
    await site.start()
    await asyncio.Event().wait() # Keep server running

if __name__ == '__main__':
    import asyncio
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Server stopped.")