.. _user:

.. _quickstart:

Quickstart
==========

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

Bootstrapping
-------------

First, make sure that ZRQ is :ref:`installed <install>` with a :ref:`running <install-redis>` 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.

.. code-block:: console

   $ cd $(mktemp -d)


Start a worker
--------------

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

.. code-block:: console

   $ 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-block:: console

   $ code quickstart.py

With the following content:

.. literalinclude:: examples/simple_task.py
  :language: python

Few things to note:

- ``say_after`` is an awaitable function, note the ``async def`` in the definition
- ``say_after`` are decorated with :func:`@task <zrq.task>` without arguments *(using defaults)*
- :func:`asyncio.sleep` is not :func:`time.sleep`, the first is awaitable unlike the second


Playground
----------

Run a Python REPL in async mode, using:

.. code-block:: console

   $ python3 -m asyncio

.. code-block:: python

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


Configuration
=============

.. currentmodule:: zrq.context

The following settings can be configured in three manners.

.. glossary::

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

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

   Programmatically
      The :attr:`settings` are exposed from :mod:`zrq.context` module.
      Settings are an unmutable object so his attributes can't be updated directly.
      Nevertheless, the :meth:`update() <Settings.update>` method can be used before the redis client is built.

      .. code-block:: python

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


Settings
--------

.. currentmodule:: None

.. data:: REDIS_URL

   | URL to built the default Redis connection pool.
   | Following schemes are supported:

   .. glossary::

      TCP socket connection
         .. code-block:: text

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

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

      SSL wrapped TCP socket connection
         .. code-block:: text

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

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

      Unix Domain Socket connection
         .. code-block:: text

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

   Default: ``redis://localhost:6379/0``

.. data:: DEFAULT_QUEUE

.. data:: WORKER_SIZE

.. data:: JOB_MAX_RETRY

.. data:: JOB_TIMEOUT

Constants
---------

.. py:data:: ENV_PREFIX


Advanced Usage
==============

.. currentmodule:: zrq


Delayed jobs
------------

Tasks can be runned in the future using :meth:`enqueue_in <Queue.enqueue_in>` or :meth:`enqueue_at <Queue.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.