=======
janus
=======
.. image:: https://github.com/aio-libs/janus/actions/workflows/ci.yml/badge.svg
:target: https://github.com/aio-libs/janus/actions/workflows/ci.yml
.. image:: https://codecov.io/gh/aio-libs/janus/branch/master/graph/badge.svg
:target: https://codecov.io/gh/aio-libs/janus
.. image:: https://img.shields.io/pypi/v/janus.svg
:target: https://pypi.python.org/pypi/janus
.. image:: https://badges.gitter.im/Join%20Chat.svg
:target: https://gitter.im/aio-libs/Lobby
:alt: Chat on Gitter
Mixed sync-async queue, supposed to be used for communicating between
classic synchronous (threaded) code and asynchronous (in terms of
`asyncio <https://docs.python.org/3/library/asyncio.html>`_) one.
Like `Janus god <https://en.wikipedia.org/wiki/Janus>`_ the queue
object from the library has two faces: synchronous and asynchronous
interface.
Synchronous is fully compatible with `standard queue
<https://docs.python.org/3/library/queue.html>`_, asynchronous one
follows `asyncio queue design
<https://docs.python.org/3/library/asyncio-queue.html>`_.
Usage
=====
Three queues are available:
* ``Queue``
* ``LifoQueue``
* ``PriorityQueue``
Each has two properties: ``sync_q`` and ``async_q``.
Use the first to get synchronous interface and the second to get asynchronous
one.
Example
-------
.. code:: python
import asyncio
import janus
def threaded(sync_q: janus.SyncQueue[int]) -> None:
for i in range(100):
sync_q.put(i)
sync_q.join()
async def async_coro(async_q: janus.AsyncQueue[int]) -> None:
for i in range(100):
val = await async_q.get()
assert val == i
async_q.task_done()
async def main() -> None:
queue: janus.Queue[int] = janus.Queue()
loop = asyncio.get_running_loop()
fut = loop.run_in_executor(None, threaded, queue.sync_q)
await async_coro(queue.async_q)
await fut
await queue.aclose()
asyncio.run(main())
Limitations
===========
This library is built using a classic thread-safe design. The design is
time-tested, but has some limitations.
* Once you are done working with a queue, you must properly close it using
``aclose()``. This is because this library creates new tasks to notify other
threads. If you do not properly close the queue,
`asyncio may generate error messages
<https://github.com/aio-libs/janus/issues/574>`_.
* The library has quite good performance only when used as intended, that is,
for communication between synchronous code and asynchronous one.
For sync-only and async-only cases, use queues from
`queue <https://docs.python.org/3/library/queue.html>`_ and
`asyncio queue <https://docs.python.org/3/library/asyncio-queue.html>`_ modules,
otherwise `the slowdown can be significant
<https://github.com/aio-libs/janus/issues/419>`_.
* You cannot use queues for communicating between two different event loops
because, like all asyncio primitives, they bind to the current one.
Development status is production/stable. The ``janus`` library is maintained to
support the latest versions of Python and fixes, but no major changes will be
made. If your application is performance-sensitive, or if you need any new
features such as ``anyio`` support, try the experimental
`culsans <https://github.com/x42005e1f/culsans>`_ library as an alternative.
Communication channels
======================
GitHub Discussions: https://github.com/aio-libs/janus/discussions
Feel free to post your questions and ideas here.
*gitter chat* https://gitter.im/aio-libs/Lobby
License
=======
``janus`` library is offered under Apache 2 license.
Thanks
======
The library development is sponsored by DataRobot (https://datarobot.com)
Raw data
{
"_id": null,
"home_page": "https://github.com/aio-libs/janus",
"name": "janus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "janus, queue, asyncio",
"author": "Andrew Svetlov <andrew.svetlov@gmail.com>",
"author_email": "andrew.svetlov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d8/7f/69884b6618be4baf6ebcacc716ee8680a842428a19f403db6d1c0bb990aa/janus-2.0.0.tar.gz",
"platform": null,
"description": "=======\n janus\n=======\n.. image:: https://github.com/aio-libs/janus/actions/workflows/ci.yml/badge.svg\n :target: https://github.com/aio-libs/janus/actions/workflows/ci.yml\n.. image:: https://codecov.io/gh/aio-libs/janus/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/aio-libs/janus\n.. image:: https://img.shields.io/pypi/v/janus.svg\n :target: https://pypi.python.org/pypi/janus\n.. image:: https://badges.gitter.im/Join%20Chat.svg\n :target: https://gitter.im/aio-libs/Lobby\n :alt: Chat on Gitter\n\n\n\nMixed sync-async queue, supposed to be used for communicating between\nclassic synchronous (threaded) code and asynchronous (in terms of\n`asyncio <https://docs.python.org/3/library/asyncio.html>`_) one.\n\nLike `Janus god <https://en.wikipedia.org/wiki/Janus>`_ the queue\nobject from the library has two faces: synchronous and asynchronous\ninterface.\n\nSynchronous is fully compatible with `standard queue\n<https://docs.python.org/3/library/queue.html>`_, asynchronous one\nfollows `asyncio queue design\n<https://docs.python.org/3/library/asyncio-queue.html>`_.\n\nUsage\n=====\n\nThree queues are available:\n\n* ``Queue``\n* ``LifoQueue``\n* ``PriorityQueue``\n\nEach has two properties: ``sync_q`` and ``async_q``.\n\nUse the first to get synchronous interface and the second to get asynchronous\none.\n\n\nExample\n-------\n\n.. code:: python\n\n import asyncio\n import janus\n\n\n def threaded(sync_q: janus.SyncQueue[int]) -> None:\n for i in range(100):\n sync_q.put(i)\n sync_q.join()\n\n\n async def async_coro(async_q: janus.AsyncQueue[int]) -> None:\n for i in range(100):\n val = await async_q.get()\n assert val == i\n async_q.task_done()\n\n\n async def main() -> None:\n queue: janus.Queue[int] = janus.Queue()\n loop = asyncio.get_running_loop()\n fut = loop.run_in_executor(None, threaded, queue.sync_q)\n await async_coro(queue.async_q)\n await fut\n await queue.aclose()\n\n\n asyncio.run(main())\n\n\nLimitations\n===========\n\nThis library is built using a classic thread-safe design. The design is\ntime-tested, but has some limitations.\n\n* Once you are done working with a queue, you must properly close it using\n ``aclose()``. This is because this library creates new tasks to notify other\n threads. If you do not properly close the queue,\n `asyncio may generate error messages\n <https://github.com/aio-libs/janus/issues/574>`_.\n* The library has quite good performance only when used as intended, that is,\n for communication between synchronous code and asynchronous one.\n For sync-only and async-only cases, use queues from\n `queue <https://docs.python.org/3/library/queue.html>`_ and\n `asyncio queue <https://docs.python.org/3/library/asyncio-queue.html>`_ modules,\n otherwise `the slowdown can be significant\n <https://github.com/aio-libs/janus/issues/419>`_.\n* You cannot use queues for communicating between two different event loops\n because, like all asyncio primitives, they bind to the current one.\n\nDevelopment status is production/stable. The ``janus`` library is maintained to\nsupport the latest versions of Python and fixes, but no major changes will be\nmade. If your application is performance-sensitive, or if you need any new\nfeatures such as ``anyio`` support, try the experimental\n`culsans <https://github.com/x42005e1f/culsans>`_ library as an alternative.\n\n\nCommunication channels\n======================\n\nGitHub Discussions: https://github.com/aio-libs/janus/discussions\n\nFeel free to post your questions and ideas here.\n\n*gitter chat* https://gitter.im/aio-libs/Lobby\n\n\nLicense\n=======\n\n``janus`` library is offered under Apache 2 license.\n\nThanks\n======\n\nThe library development is sponsored by DataRobot (https://datarobot.com)\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "Mixed sync-async queue to interoperate between asyncio tasks and classic threads",
"version": "2.0.0",
"project_urls": {
"CI: GitHub Actions": "https://github.com/aio-libs/janus/actions/workflows/ci.yml",
"Chat: Gitter": "https://gitter.im/aio-libs/Lobby",
"Coverage: codecov": "https://codecov.io/github/aio-libs/janus",
"GitHub: issues": "https://github.com/aio-libs/janus/issues",
"GitHub: repo": "https://github.com/aio-libs/janus",
"Homepage": "https://github.com/aio-libs/janus"
},
"split_keywords": [
"janus",
" queue",
" asyncio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "683465604740edcb20e1bda6a890348ed7d282e7dd23aa00401cbe36fd0edbd9",
"md5": "5f2932b1e695451d8b7d7537bbeaf846",
"sha256": "7e6449d34eab04cd016befbd7d8c0d8acaaaab67cb59e076a69149f9031745f9"
},
"downloads": -1,
"filename": "janus-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f2932b1e695451d8b7d7537bbeaf846",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 12161,
"upload_time": "2024-12-13T12:59:06",
"upload_time_iso_8601": "2024-12-13T12:59:06.106157Z",
"url": "https://files.pythonhosted.org/packages/68/34/65604740edcb20e1bda6a890348ed7d282e7dd23aa00401cbe36fd0edbd9/janus-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d87f69884b6618be4baf6ebcacc716ee8680a842428a19f403db6d1c0bb990aa",
"md5": "7c8ec257be4e90abc47a7df47df88436",
"sha256": "0970f38e0e725400496c834a368a67ee551dc3b5ad0a257e132f5b46f2e77770"
},
"downloads": -1,
"filename": "janus-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7c8ec257be4e90abc47a7df47df88436",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 22910,
"upload_time": "2024-12-13T12:59:08",
"upload_time_iso_8601": "2024-12-13T12:59:08.622806Z",
"url": "https://files.pythonhosted.org/packages/d8/7f/69884b6618be4baf6ebcacc716ee8680a842428a19f403db6d1c0bb990aa/janus-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 12:59:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aio-libs",
"github_project": "janus",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "janus"
}
JSON
