Metadata-Version: 2.1
Name: aqueue
Version: 0.5.1
Summary: An async task queue with live progress display
Home-page: https://t-mart.github.io/aqueue/
License: MIT
Keywords: queue,async,task
Author: Tim Martin
Author-email: tim@timmart.in
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Trio
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: attrs (>=22.1.0,<23.0.0)
Requires-Dist: rich (>=12.6.0,<13.0.0)
Requires-Dist: sortedcontainers (>=2.4.0,<3.0.0)
Requires-Dist: trio (>=0.22.0,<0.23.0)
Project-URL: Documentation, https://t-mart.github.io/aqueue/
Project-URL: Repository, https://github.com/t-mart/aqueue
Description-Content-Type: text/x-rst

.. teaser-begin

==========
``aqueue``
==========

``aqueue`` is an async task queue with live progress display.

You put items in, and they get processed, possibly creating more items which get processed, and so
on, until all items are completed. A typical use case would be to scrape a website.

.. image:: https://raw.githubusercontent.com/t-mart/aqueue/master/docs/_static/demo.gif
  :alt: Demonstration of aqueue

.. note::

  ``aqueue``, or any asynchronous framework, is only going to be helpful if you're performing
  **I/O-bound** work.


Installation
============

``aqueue`` is a Python package `hosted on PyPI <https://pypi.org/project/aqueue/>`_. The recommended
installation method is `pip <https://pip.pypa.io/en/stable/>`_-installing into a virtual
environment:

.. code-block:: shell

   pip install aqueue

Getting Started
===============

There's two things you need to do to use aqueue:

1. Implement your `Item <https://t-mart.github.io/aqueue/#items>`_ subclasses.
2. `Start your queue <https://t-mart.github.io/aqueue/#starting-your-queue>`_ with one of those
   items.

.. teaser-end

Example
=======

If you had a hierarchy of items like this...

.. image:: docs/_static/simple-diagram.png
  :alt: Simple item hierarchy with one root item and many children items stemming from it.

Then, you might process it with ``aqueue`` like this...

.. code-block:: python

   import aqueue


   class RootItem(aqueue.Item):
      async def process(
         self, enqueue: aqueue.EnqueueFn, set_desc: aqueue.SetDescFn
      ) -> None:
         # display what we're doing in the worker status panel
         set_desc("Processing RootItem")

         # make an HTTP request, parse it, etc
         ...

         # when you discover more items you want to process, enqueue them:
         for _ in range(5):
               enqueue(ChildItem())

      async def after_children_processed(self) -> None:
         # run this method when this Item and all other Items it enqueued are done
         print("All done!")


   class ChildItem(aqueue.Item):

      # track the enqueueing and completion of these items in the overall panel
      track_overall: bool = True

      async def process(
         self, enqueue: aqueue.EnqueueFn, set_desc: aqueue.SetDescFn
      ) -> None:
         set_desc("Processing ChildItem")


   if __name__ == "__main__":
      aqueue.run_queue(
         initial_items=[RootItem()],
         num_workers=2,
      )

.. -project-information-

Project Information
===================

- **License**: `MIT <https://choosealicense.com/licenses/mit/>`_
- **PyPI**: https://pypi.org/project/aqueue/
- **Source Code**: https://github.com/t-mart/aqueue
- **Documentation**: https://t-mart.github.io/aqueue/
- **Supported Python Versions**: 3.10 and later

