============================
vsq - View Server Task Queue
============================


* License: MIT license


Installation
------------

Install with pip

.. code-block:: bash

   pip install vsq


Usage
-----

Producer:

.. code-block:: python

   from redis import Redis
   from vsq.queue import Queue

   # create a queue instance
   queue = Queue('queue_name', Redis(...))

   # send a message, which is anything that can be encoded as JSON.
   # a Task object is returned.
   task = queue.put({
      'type': 'myMessageType',
      'payload': ['some', 'values'],
   })

   # some metadata of that task
   print(task.id, task.status, task.created)

   # wait for the task result, ideally with a timeout
   result = task.get(timeout=120)


Consumer:


.. code-block:: python

   from redis import Redis
   from vsq.queue import Queue

   # create a queue instance
   queue = Queue('queue_name', Redis(...))

   # get a single task (with or without timeout):
   task = queue.get_task(timeout=None)

   # a task offers an error capturing context manager API
   with task:
       ...
       task.result = {
           'some': 'result'
       }

   # a queue can be iterated, when listening on an arbitrary amount of messages
   for task in queue:
       with task:
           ...
           task.result = {
               'some': 'result'
           }


Async Queue
...........

``vsq`` provides an async interface mirroring the synchronous one:



.. code-block:: python

   import aioredis
   from vsq.aqueue import Queue

   # create a queue instance
   queue = Queue('queue_name', aioredis.from_url('redis://host:6379'))

   # send a message, which is anything that can be encoded as JSON.
   # a Task object is returned. This is an asynchronous method call
   task = await queue.put({
      'type': 'myMessageType',
      'payload': ['some', 'values'],
   })

   # some metadata of that task
   print(task.id, task.status, task.created)

   # wait for the task result, ideally with a timeout. Also this is
   # asynchronous
   result = await task.get(timeout=120)


Consumer:


.. code-block:: python

   import aioredis
   from vsq.queue import Queue

   # create a queue instance
   queue = Queue('queue_name', aioredis.from_url('redis://host:6379'))

   # get a single task (with or without timeout):
   task = await queue.get_task(timeout=None)

   # a task offers an error capturing context manager API
   async with task:
       ...
       task.result = {
           'some': 'result'
       }

   # a queue can be iterated, when listening on an arbitrary amount of messages
   async for task in queue:
       async with task:
           ...
           task.result = {
               'some': 'result'
           }


Features
--------

``vsq`` provides command line interfaces to easily start a task daemon or to
dispatch messages.


.. code-block:: bash

   # start a task daemon with a given handler function
   python -m vsq.queue daemon myq mymodule.somehandler

   # send a json encoded message
   python -m vsq.queue message myq --json '{"type": "message", "args": "abc"}' --wait



Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage