https://github.com/toastdriven/alligator

Simple offline task queues. For Python.
https://github.com/toastdriven/alligator

Last synced: 3 months ago
JSON representation

Simple offline task queues. For Python.

• Host: GitHub
• URL: https://github.com/toastdriven/alligator
• Owner: toastdriven
• License: bsd-3-clause
• Created: 2014-12-31T07:24:51.000Z (almost 10 years ago)
• Default Branch: master
• Last Pushed: 2023-05-16T01:10:51.000Z (over 1 year ago)
• Last Synced: 2024-07-24T08:45:39.414Z (3 months ago)
• Language: Python
• Homepage: http://alligator.readthedocs.org/en/latest/
• Size: 202 KB
• Stars: 27
• Watchers: 4
• Forks: 5
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • Contributing: docs/contributing.rst
  • License: LICENSE
  • Security: docs/security.rst

Awesome Lists containing this project

• starred-awesome - alligator - Simple offline task queues. For Python. (Python)

README

        
Alligator

=========

.. image:: https://travis-ci.org/toastdriven/alligator.png?branch=master

        :target: https://travis-ci.org/toastdriven/alligator

Simple offline task queues. For Python.

`"See you later, alligator."`

Latest documentation at http://alligator.readthedocs.org/en/latest/.

Requirements

------------

* Python 3.6+

* (Optional) ``redis`` for the Redis backend

* (Optional) ``boto3>=1.12.0`` for the SQS backend

Basic Usage

-----------

This example uses Django, but there's nothing Django-specific about Alligator.

I repeat, You can use it with **any** Python code that would benefit from

background processing.

.. code:: python

    from alligator import Gator

    from django.contrib.auth.models import User

    from django.shortcuts import send_email

    # Make a Gator instance.

    # Under most circumstances, you would configure this in one place &

    # import that instance instead.

    gator = Gator('redis://localhost:6379/0')

    # The task itself.

    # Nothing special, just a plain *undecorated* function.

    def follow_email(followee_username, follower_username):

        followee = User.objects.get(username=followee_username)

        follower = User.objects.get(username=follower_username)

        subject = 'You got followed!'

        message = 'Hey {}, you just got followed by {}! Whoohoo!'.format(

            followee.username,

            follower.username

        )

        send_email(subject, message, '[email protected]', [followee.email])

    # An simple, previously expensive view.

    @login_required

    def follow(request, username):

        # You'd import the task function above.

        if request.method == 'POST':

            # Schedule the task.

            # Use args & kwargs as normal.

            gator.task(follow_email, request.user.username, username)

            return redirect('...')

Running Tasks

-------------

Rather than trying to do autodiscovery, fanout, etc., you control how your

workers are configured & what they consume.

If your needs are simple, run the included ``latergator.py`` worker:

.. code:: bash

    $ python latergator.py redis://localhost:6379/0

If you have more complex needs, you can create a new executable file

(bin script, management command, whatever) & drop in the following code.

.. code:: python

    from alligator import Gator, Worker

    # Bonus points if you import that one pre-configured ``Gator`` instead.

    gator = Gator('redis://localhost:6379/0')

    # Consume & handle all tasks.

    worker = Worker(gator)

    worker.run_forever()

License

-------

New BSD

Running Tests

-------------

Alligator has 95%+ test coverage & aims to be passing/stable at all times.

If you'd like to run the tests, clone the repo, then run::

    $ virtualenv -p python3 env

    $ . env/bin/activate

    $ pip install -r requirements-tests.txt

    $ python setup.py develop

    $ pytest -s -v --cov=alligator --cov-report=html tests

The full test suite can be run via:

    $ export ALLIGATOR_TESTS_INCLUDE_SQS=true

    $ ./tests/run_all.sh

This requires all backends/queues to be running, as well as valid AWS

credentials if ``ALLIGATOR_TESTS_INCLUDE_SQS=true`` is set.

WHY?!!1!

--------

* Because I have NIH-syndrome.

* Or because I longed for something simple (~375 loc).

* Or because I wanted something with tests (90%+ coverage) & docs.

* Or because I wanted pluggable backends.

* Or because testing some other queuing system was a pain.

* Or because I'm an idiot.

Roadmap

-------

Post-`1.0.0`:

    * Expand the supported backends

        * Kafka?

        * ActiveMQ support?

        * RabbitMQ support?

        * ???