alligator.gator

class alligator.gator.Gator(conn_string, queue_name='all', task_class=<class 'alligator.tasks.Task'>, backend_class=None)
build_backend(conn_string)

Given a DSN, returns an instantiated backend class.

Ex:

backend = gator.build_backend('locmem://')
# ...or...
backend = gator.build_backend('redis://127.0.0.1:6379/0')
Parameters:conn_string (string) – A DSN for connecting to the queue. Passed along to the backend.
Returns:A backend Client instance
cancel(task_id)

Takes an existing task & cancels it before it is processed.

Returns the canceled task, as that could be useful in creating a new task.

Ex:

task = gator.task(add, 18, 9)

# Whoops, didn't mean to do that.
gator.cancel(task.task_id)
Parameters:task_id (string) – The identifier of the task to process
Returns:The canceled Task instance
execute(task)

Given a task instance, this runs it.

This includes handling retries & re-raising exceptions.

Ex:

task = Task(async=False, retries=5)
task.to_call(add, 101, 35)
finished_task = gator.execute(task)
Parameters:task_id (string) – The identifier of the task to process
Returns:The completed Task instance
get(task_id)

Gets a specific task, by task_id off the queue & runs it.

Using this is not as performant (because it has to search the queue), but can be useful if you need to specifically handle a task right now.

Ex:

# Tasks were previously added, maybe by a different process or
# machine...
finished_task = gator.get('a-specific-uuid-here')
Parameters:task_id (string) – The identifier of the task to process
Returns:The completed Task instance
len()

Returns the number of remaining queued tasks.

Returns:An integer count
options(**kwargs)

Allows specifying advanced Task options to control how the task runs.

This returns a context manager which will create Task instances with the supplied options. See Task.__init__ for the available arguments.

Ex:

def party_time(task, result):
    # Throw a party in honor of this task completing.
    # ...

with gator.options(retries=2, on_success=party_time) as opts:
    opts.task(increment, incr_by=2678)
Parameters:kwargs (dict) – Keyword arguments to control the task execution
Returns:An Options context manager instance
pop()

Pops a task off the front of the queue & runs it.

Typically, you’ll favor using a Worker to handle processing the queue (to constantly consume). However, if you need to custom-process the queue in-order, this method is useful.

Ex:

# Tasks were previously added, maybe by a different process or
# machine...
finished_topmost_task = gator.pop()
Returns:The completed Task instance
push(task, func, *args, **kwargs)

Pushes a configured task onto the queue.

Typically, you’ll favor using the Gator.task method or Gator.options context manager for creating a task. Call this only if you have specific needs or know what you’re doing.

If the Task has the async = False option, the task will be run immediately (in-process). This is useful for development and in testing.

Ex:

task = Task(async=False, retries=3)
finished = gator.push(task, increment, incr_by=2)
Parameters:
  • task (A Task instance) – A mostly-configured task
  • func (callable) – The callable with business logic to execute
  • args (list) – Positional arguments to pass to the callable task
  • kwargs (dict) – Keyword arguments to pass to the callable task
Returns:

The Task instance

task(func, *args, **kwargs)

Pushes a task onto the queue.

This will instantiate a Gator.task_class instance, configure the callable & its arguments, then push it onto the queue.

You’ll typically want to use either this method or the Gator.options context manager (if you need to configure the Task arguments, such as retries, async, task_id, etc.)

Ex:

on_queue = gator.task(increment, incr_by=2)
Parameters:
  • func (callable) – The callable with business logic to execute
  • args (list) – Positional arguments to pass to the callable task
  • kwargs (dict) – Keyword arguments to pass to the callable task
Returns:

The Task instance

class alligator.gator.Options(gator, **kwargs)
task(func, *args, **kwargs)

Pushes a task onto the queue (with the specified options).

This will instantiate a Gator.task_class instance, configure the task execution options, configure the callable & its arguments, then push it onto the queue.

You’ll typically call this method when specifying advanced options.

Parameters:
  • func (callable) – The callable with business logic to execute
  • args (list) – Positional arguments to pass to the callable task
  • kwargs (dict) – Keyword arguments to pass to the callable task
Returns:

The Task instance