feat: adds handling for eventlet/gevent

[namsnath]

Summary of change

• Adds AsyncHandler (sub)classes to manage async_to_sync across frameworks
• Adds a new param to Supertokens to configure async type

Examples:

# flask.py

from supertokens_python.async_to_sync.handler import DefaultHandler, AsyncioHandler

init(
    async_handler=DefaultHandler(), # default, no need to set explicitly
    async_handler=AsyncioHandler(), # Similar to DefaultHandler with default params
    async_handler=DefaultHandler(create_loop_thread=True), # Creates a thread to run the event loop
)

# gevent.py

from supertokens_python.async_to_sync.handler import GeventHandler

init(
    async_handler=GeventHandler(), # Creates a thread to run the event loop
)

# eventlet.py

from supertokens_python.async_to_sync.handler import EventletHandler

init(
    async_handler=EventletHandler(), # Creates a thread to run the event loop
)

Optionally, pass in a loop param to use pre-existing loops within Supertokens.

Usage Examples

Python runner

Default

# flask.py
init(
    # ...
)

Existing non-threaded event loop

NOTE: Do NOT use the is_loop_threaded option for non-threaded loops. Will cause the server to not respond.

# flask.py
import asyncio
loop = asyncio.new_event_loop()

init(
    # ...
    # Does not require any additional handling
)

Existing threaded event loop

# flask.py
from supertokens_python.async_to_sync.handler import AsyncioHandler

import asyncio, nest_asyncio, threading
loop = asyncio.new_event_loop()
loop_thread = threading.Thread(target=loop.run_forever, daemon=True)
loop_thread.start()

asyncio.set_event_loop(loop)

init(
    # ...
    async_handler=AsyncioHandler(loop=loop, is_loop_threaded=True)
)

Create new threaded event loop

# flask.py
from supertokens_python.async_to_sync.handler import AsyncioHandler

init(
    # ...
    async_handler=AsyncioHandler(
        create_loop_thread=True,
        is_loop_threaded=True, # Not required, set internally
    )
)

Gevent

Default - Create loop thread for better performance

# gevent.py
from supertokens_python.async_to_sync.handler import GeventHandler

init(
    async_handler=GeventHandler(
        create_loop_thread=True, # Not required, set by default
        is_loop_threaded=True, # Not required, set by default
    ),
)

Existing threaded loop

# gevent.py
from supertokens_python.async_to_sync.handler import GeventHandler

import asyncio, threading
loop = asyncio.new_event_loop()
loop_thread = threading.Thread(target=loop.run_forever, daemon=True)
loop_thread.start()
asyncio.set_event_loop(loop)

init(
    async_handler=GeventHandler(create_loop_thread=False, loop=loop, is_loop_threaded=False),
)

Eventlet

Default - Create loop thread

# eventlet.py
from supertokens_python.async_to_sync.handler import EventletHandler

init(
    async_handler=EventletHandler(
        create_loop_thread=True, # Not required, set by default
        is_loop_threaded=True, # Not required, set by default
    ),
)

Use existing threaded loop

# eventlet.py
from supertokens_python.async_to_sync.handler import EventletHandler

import asyncio, threading
loop = asyncio.new_event_loop()
loop_thread = threading.Thread(target=loop.run_forever, daemon=True)
loop_thread.start()
asyncio.set_event_loop(loop)

init(
    async_handler=EventletHandler(
        create_loop_thread=False,
        loop=loop,
        is_loop_threaded=True,
    ),
)

Related issues

• #532

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)

Documentation changes

(If relevant, please create a PR in our docs repo, or create a checklist here highlighting the necessary changes)

Checklist for important updates

• [ ] Changelog has been updated
• [ ] coreDriverInterfaceSupported.json file has been updated (if needed)
  • Along with the associated array in supertokens_python/constants.py
• [ ] frontendDriverInterfaceSupported.json file has been updated (if needed)
• [ ] Changes to the version if needed
  • In setup.py
  • In supertokens_python/constants.py
• [x] Had installed and ran the pre-commit hook
• [x] Issue this PR against the latest non released version branch.
  • To know which one it is, run find the latest released tag (git tag) in the format vX.Y.Z, and then find the latest branch (git branch --all) whose X.Y is greater than the latest released tag.
  • If no such branch exists, then create one from the latest released branch.
• [ ] If have added a new web framework, update the supertokens_python/utils.py file to include that in the FRAMEWORKS variable
• [ ] If added a new recipe that has a User type with extra info, then be sure to change the User type in supertokens_python/types.py
• [ ] Make sure that syncio / asyncio functions are consistent.
• [ ] If access token structure has changed
  • Modified test in tests/sessions/test_access_token_version.py to account for any new claims that are optional or omitted by the core

Remaining TODOs for this PR

• [x] Fix cyclic import lint errors (potentially create module for async_to_sync)
• [x] Optimize the options exposed to users
  • [x] Consider differentiating between loop types (threaded/non-threaded) to change sync handling
• [x] Add docstrings