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 (str) – A DSN for connecting to the queue. Passed along to the backend.
Returns:	A backend `Client` instance
Return type:	Client

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 (str) – The identifier of the task to process
Returns:	The canceled `Task` instance
Return type:	Task

execute(task)¶

Given a task instance, this runs it.

This includes handling retries & re-raising exceptions.

Ex:

task = Task(is_async=False, retries=5)
task.to_call(add, 101, 35)
finished_task = gator.execute(task)

Parameters:	task_id (str) – The identifier of the task to process
Returns:	The completed `Task` instance
Return type:	Task

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 (str) – The identifier of the task to process
Returns:	The completed `Task` instance
Return type:	Task

len()¶

Returns the number of remaining queued tasks.

Returns:	A count of the remaining tasks
Return type:	int

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
Return type:	Options

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
Return type:	Task

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 is_async = False option, the task will be run immediately (in-process). This is useful for development and in testing.

Ex:

task = Task(is_async=False, retries=3)
finished = gator.push(task, increment, incr_by=2)

Parameters:	task (Task) – 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 fleshed-out `Task` instance
Return type:	Task

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, is_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
Return type:	Task

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
Return type:	Task