alligator.gator — Alligator 0.5.0-dev documentation

### Navigation

- index
- modules |
- next |
- previous |
- Alligator 0.5.0-dev documentation »

# 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

### Navigation

- index
- modules |
- next |
- previous |
- Alligator 0.5.0-dev documentation »