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
- 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
- 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