aioguest: run asyncio and another event loop in the same thread
===============================================================
.. image:: https://img.shields.io/pypi/v/aioguest.svg
:target: https://pypi.org/project/aioguest
:alt: Latest PyPI version
.. image:: https://github.com/oremanj/aioguest/actions/workflows/ci.yml/badge.svg
:target: https://github.com/oremanj/aioguest/actions/workflows/ci.yml
:alt: Automated test status
.. image:: https://codecov.io/gh/oremanj/aioguest/branch/master/graph/badge.svg
:target: https://codecov.io/gh/oremanj/aioguest
:alt: Test coverage
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
:alt: Code style: black
`Trio <https://github.com/python-trio/trio>`__, an alternate async framework
for Python, supports a feature called `"guest mode"
<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#using-guest-mode-to-run-trio-on-top-of-other-event-loops>`__ where it can run in the same thread as
another event loop. In guest mode, low-level I/O waiting occurs on a worker thread,
but the threading is invisible to user code, and both event loops can interact
with each other without any special synchronization.
This package implements guest mode for asyncio. It has one public function::
aioguest.start_guest_run(
coro,
*,
run_sync_soon_threadsafe,
done_callback,
run_sync_soon_not_threadsafe=None,
debug=None,
loop_factory=None,
)
This effectively starts a call to ``asyncio.run(coro)`` in parallel
with the currently running ("host") event loop. The *debug* parameter
is passed to ``asyncio.run()`` if specified. On Python 3.11+, you can
also supply a *loop_factory* which will be passed to ``asyncio.Runner()``.
The parameters *run_sync_soon_threadsafe*, *done_callback*, and (optionally)
*run_sync_soon_not_threadsafe* tell ``aioguest`` how to interact with the host
event loop. Someday ``aioguest`` will have documentation of its own.
Until then, see the `Trio documentation
<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#reference>`__
for details on these parameters, including an `example
<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#implementing-guest-mode-for-your-favorite-event-loop>`__.
``start_guest_run()`` returns the main task of the new asyncio run, i.e.,
the ``asyncio.Task`` that wraps *coro*. It may also return None if the main task
could not be determined, such as because ``asyncio.run()`` raised an exception
before starting to execute *coro*. The main task is provided mostly for
cancellation purposes; while you can also register callbacks upon its completion,
the run is not necessarily finished at that point, because background tasks and
async generators might still be in the process of finalization.
Exceptions noticed when starting up the asyncio run might either propagate out of
``start_guest_run()`` or be delivered to your *done_callback*, maybe even before
``start_guest_run()`` returns (it will return None in that case). In general,
problems noticed by ``aioguest`` will propagate out of ``start_guest_run()``,
while problems noticed by asyncio will be delivered to your *done_callback*.
``aioguest`` requires Python 3.8 or later. Out of the box it supports
the default asyncio event loop implementation (only) on Linux,
Windows, macOS, FreeBSD, and maybe others. It does not support
operating systems that provide only ``select()`` or ``poll()``; due to
thread-safety considerations it needs an I/O abstraction where the OS
kernel is involved in registrations, such as IOCP, epoll, or kqueue.
Alternative Python-based event loops can likely be supported given
modest effort if they use such an abstraction. Alternative C-based
event loops (such as uvloop) present much more of a challenge because
compiled code generally can't be monkeypatched.
Development status
------------------
``aioguest`` has been tested with a variety of toy examples and
pathological cases, and its unit tests exercise full coverage. It
hasn't had a lot of exposure to real-world problems yet. Maybe you'd
like to expose it to yours?
License
-------
``aioguest`` is licensed under your choice of the MIT or Apache 2.0
license. See `LICENSE <https://github.com/oremanj/aioguest/blob/master/LICENSE>`__
for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/oremanj/aioguest",
"name": "aioguest",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "async,trio,asyncio",
"author": "Joshua Oreman",
"author_email": "oremanj@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/77/77/77d0701a2b13d202de41809e3942d98596f2c791aadd94f4d3bcf2791a4c/aioguest-0.1.0.tar.gz",
"platform": null,
"description": "aioguest: run asyncio and another event loop in the same thread\n===============================================================\n\n.. image:: https://img.shields.io/pypi/v/aioguest.svg\n :target: https://pypi.org/project/aioguest\n :alt: Latest PyPI version\n\n.. image:: https://github.com/oremanj/aioguest/actions/workflows/ci.yml/badge.svg\n :target: https://github.com/oremanj/aioguest/actions/workflows/ci.yml\n :alt: Automated test status\n\n.. image:: https://codecov.io/gh/oremanj/aioguest/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/oremanj/aioguest\n :alt: Test coverage\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/ambv/black\n :alt: Code style: black\n\n`Trio <https://github.com/python-trio/trio>`__, an alternate async framework\nfor Python, supports a feature called `\"guest mode\"\n<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#using-guest-mode-to-run-trio-on-top-of-other-event-loops>`__ where it can run in the same thread as\nanother event loop. In guest mode, low-level I/O waiting occurs on a worker thread,\nbut the threading is invisible to user code, and both event loops can interact\nwith each other without any special synchronization.\n\nThis package implements guest mode for asyncio. It has one public function::\n\n aioguest.start_guest_run(\n coro,\n *,\n run_sync_soon_threadsafe,\n done_callback,\n run_sync_soon_not_threadsafe=None,\n debug=None,\n loop_factory=None,\n )\n\nThis effectively starts a call to ``asyncio.run(coro)`` in parallel\nwith the currently running (\"host\") event loop. The *debug* parameter\nis passed to ``asyncio.run()`` if specified. On Python 3.11+, you can\nalso supply a *loop_factory* which will be passed to ``asyncio.Runner()``.\n\nThe parameters *run_sync_soon_threadsafe*, *done_callback*, and (optionally)\n*run_sync_soon_not_threadsafe* tell ``aioguest`` how to interact with the host\nevent loop. Someday ``aioguest`` will have documentation of its own.\nUntil then, see the `Trio documentation\n<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#reference>`__\nfor details on these parameters, including an `example\n<https://trio.readthedocs.io/en/stable/reference-lowlevel.html#implementing-guest-mode-for-your-favorite-event-loop>`__.\n\n``start_guest_run()`` returns the main task of the new asyncio run, i.e.,\nthe ``asyncio.Task`` that wraps *coro*. It may also return None if the main task\ncould not be determined, such as because ``asyncio.run()`` raised an exception\nbefore starting to execute *coro*. The main task is provided mostly for\ncancellation purposes; while you can also register callbacks upon its completion,\nthe run is not necessarily finished at that point, because background tasks and\nasync generators might still be in the process of finalization.\n\nExceptions noticed when starting up the asyncio run might either propagate out of\n``start_guest_run()`` or be delivered to your *done_callback*, maybe even before\n``start_guest_run()`` returns (it will return None in that case). In general,\nproblems noticed by ``aioguest`` will propagate out of ``start_guest_run()``,\nwhile problems noticed by asyncio will be delivered to your *done_callback*.\n\n``aioguest`` requires Python 3.8 or later. Out of the box it supports\nthe default asyncio event loop implementation (only) on Linux,\nWindows, macOS, FreeBSD, and maybe others. It does not support\noperating systems that provide only ``select()`` or ``poll()``; due to\nthread-safety considerations it needs an I/O abstraction where the OS\nkernel is involved in registrations, such as IOCP, epoll, or kqueue.\nAlternative Python-based event loops can likely be supported given\nmodest effort if they use such an abstraction. Alternative C-based\nevent loops (such as uvloop) present much more of a challenge because\ncompiled code generally can't be monkeypatched.\n\nDevelopment status\n------------------\n\n``aioguest`` has been tested with a variety of toy examples and\npathological cases, and its unit tests exercise full coverage. It\nhasn't had a lot of exposure to real-world problems yet. Maybe you'd\nlike to expose it to yours?\n\nLicense\n-------\n\n``aioguest`` is licensed under your choice of the MIT or Apache 2.0\nlicense. See `LICENSE <https://github.com/oremanj/aioguest/blob/master/LICENSE>`__\nfor details.\n",
"bugtrack_url": null,
"license": "MIT -or- Apache License 2.0",
"summary": "Run asyncio and another event loop in the same thread",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/oremanj/aioguest"
},
"split_keywords": [
"async",
"trio",
"asyncio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "90ddfbdcc568d3655c626f6f5e08b91eeeb1497208f012c12cc87abc5afbcd3c",
"md5": "1e5f87997a58dbc721677309bd8bff72",
"sha256": "2f993e173503638a61e8f51b5f5f71ed0b9cfdb782b208d3822d10904cd0af75"
},
"downloads": -1,
"filename": "aioguest-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e5f87997a58dbc721677309bd8bff72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17625,
"upload_time": "2023-06-02T18:51:18",
"upload_time_iso_8601": "2023-06-02T18:51:18.382153Z",
"url": "https://files.pythonhosted.org/packages/90/dd/fbdcc568d3655c626f6f5e08b91eeeb1497208f012c12cc87abc5afbcd3c/aioguest-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "777777d0701a2b13d202de41809e3942d98596f2c791aadd94f4d3bcf2791a4c",
"md5": "080caf61984bc803341fd9027d49e48c",
"sha256": "b0bad95272592703379ada3d69f442c73b2cb64075be21d8617049c75747904b"
},
"downloads": -1,
"filename": "aioguest-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "080caf61984bc803341fd9027d49e48c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25344,
"upload_time": "2023-06-02T18:51:20",
"upload_time_iso_8601": "2023-06-02T18:51:20.080270Z",
"url": "https://files.pythonhosted.org/packages/77/77/77d0701a2b13d202de41809e3942d98596f2c791aadd94f4d3bcf2791a4c/aioguest-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-02 18:51:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oremanj",
"github_project": "aioguest",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "aioguest"
}
JSON
