Quickstart¶

This page gives an introduction in how to get started with some examples.

Bootstrapping¶

First, make sure that ZRQ is installed with a running Redis instance.

In order of discovering and invoking tasks, it is mandatory to work from a directory.

To do so, the following command will creates a temporary folder and goes into it.

$ cd $(mktemp -d)

Start a worker¶

Now, let’s start a worker in his simplest form.

$ zrq worker
> Registering as 3c155bf27171453cbe066e69032fb8e8
> Consuming the default queue
> Awaiting for jobs

The default queue is assumed in lack of arguments. Another and/or serveral queues can also be consumed at once by providing their names as positional arguments.

Since the worker is a foreground process, you may want to open a new terminal for the following steps. To go back on the original folder path, cd "$OLDPWD can be useful.

Define a task¶

The first task can be declared in the quickstart.py file.

$ code quickstart.py

With the following content:

import asyncio
from zrq import task

@task
async def say_after(delay: int, what: str):
    await asyncio.sleep(delay)
    print(what)

Few things to note:

say_after is an awaitable function, note the async def in the definition
say_after are decorated with @task without arguments (using defaults)
asyncio.sleep is not time.sleep, the first is awaitable unlike the second

Playground¶

Run a Python REPL in async mode, using:

$ python3 -m asyncio

>>> from quickstart import say_after
>>> job = await say_after.enqueue(1, "hello world")

Configuration¶

The following settings can be configured in three manners.

Environment variables¶

Each setting are checked from environment variables at runtime instanciation. To avoid collisions, prefixed envvars are expected, for example ZRQ_DEFAULT_QUEUE affects DEFAULT_QUEUE. For flag-like settings, values like y / yes / true are also supported.

Command line interface¶

Some parameters like REDIS_URL are customizable with the CLI (using -r or --redis-url). CLI arguments takes priority on environment variables. To have a list of exposed settings, use zrq --help.

Programmatically¶

The settings are exposed from zrq.context module. Settings are an unmutable object so his attributes can’t be updated directly. Nevertheless, the update() method can be used before the redis client is built.

>>> from zrq.context import settings
>>> settings.update(DEFAULT_QUEUE="helloworld")

Settings¶

REDIS_URL¶

URL to built the default Redis connection pool.

Following schemes are supported:

TCP socket connection¶

redis://[[username]:[password]]@localhost:6379/0

See https://www.iana.org/assignments/uri-schemes/prov/redis

SSL wrapped TCP socket connection¶

rediss://[[username]:[password]]@localhost:6379/0

See https://www.iana.org/assignments/uri-schemes/prov/rediss

Unix Domain Socket connection¶

unix://[username@]/path/to/socket.sock?db=0[&password=password]

Default: redis://localhost:6379/0

DEFAULT_QUEUE¶

WORKER_SIZE¶

JOB_MAX_RETRY¶

JOB_TIMEOUT¶

Constants¶

ENV_PREFIX¶

Advanced Usage¶

Delayed jobs¶

Tasks can be runned in the future using enqueue_in or enqueue_at methods.

Enqueuing 101¶

There is many way to enqueue a task. The naive method, as seen in the quickstart, is just one of them.

CLI¶

Profiling¶

Sometime, we are struggle on something. -> PDB and cProfile.