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
instanceReturn 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
instanceReturn 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
instanceReturn 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
instanceReturn 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. SeeTask.__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 instanceReturn 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
instanceReturn type: Task
-
push
(task, func, *args, **kwargs)¶ Pushes a configured task onto the queue.
Typically, you’ll favor using the
Gator.task
method orGator.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 theis_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
instanceReturn type:
-
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 theTask
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
instanceReturn type:
-
-
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
instanceReturn type:
-