apio
====

Apio contiene una capa de abstracción para la creación de modelos de datos de
Django que son capaces de disparar tareas de Celery y de almacenar los
resultados de la misma.

.. figure:: _static/apio_flowchart.png
   :align: center
   
   Diagrama de flujo de apio.

1. El usuario interactua con el modelo de datos mediante un formulario.
2. Cuando el método `save` del modelo es llamado los datos de la petición
   (:ref:`request`) se almacenan.
3. En el mismo método `save` se llama a la tarea de Celery pasándole los datos
   de la petición que ha facilitado el usuario.
4. Cuando la tarea es llamada, se dispara la señal `pre_run` generando una
   entrada en el modelo :ref:`execution`.
5. Al finalizar la tarea de Celery, se dispara la señal `post_run` actualizando
   el estado de la ejecución en el modelo :ref:`execution`.

Modelos
=======

Apio proporciona dos modelos abstractos: :ref:`request` y :ref:`execution`.

.. _request:

Request
-------

Los datos del modelo :ref:`request` representan las peticiónes usuario. 

El desarrollador debe crear una subclase de :ref:`request` añadiendo los campos
que necesite para su tipo de petición.

Además existe un atributo especial llamado `task` al que se debe asignar la
tarea de Celery que se desea ejecutar cuando se haga una petición.

.. autoclass:: apio.models.Request
   :members:


Request Meta
++++++++++++

Los models que heredan de :ref:`request` pueden contener atributos adicionales
en la clase ``Meta``.

``apio_task``
~~~~~~~~~~~~~

Tarea de Celery que se ha de ejecutar por cada petición.

``apio_fields``
~~~~~~~~~~~~~~~

Tupla de nombres de campos del modelo que se deben pasar como argumentos a la
tarea de Celery. Por defecto se pasarán todos los campos definidos por el
usuario.

``apio_excluded_fields``
~~~~~~~~~~~~~~~~~~~~~~~~

Tupla de nombres de campos del modelo que se deben excluir al pasar los
argumentos a la tarea de Celery.

``apio_execute_on_save``
~~~~~~~~~~~~~~~~~~~~~~~~

Atributo que de tipo ``bool`` que define si se debe invocar la tarea en el
momento del guardado.

.. _execution:

Execution
---------

Las entradas del modelo :ref:`execution` representan las ejecuciones de tareas
de Celery que se han generado por cada una de las peticiones. Tenga en cuenta
que una petición puede ejecutarse más de una vez si, por ejemplo, se produce un
fallo en la primera ejecución.

.. autoclass:: apio.models.Execution
   :members:


Ejemplo
=======

.. note::
   Añadir un ejemplo de uso