Metadata-Version: 2.4
Name: pyarcflow
Version: 0.0.1
Summary: Moteur de workflow asynchrone pour ARC-CMS : nœuds, transitions, tâches et scheduler.
Home-page: https://github.com/inicode/pyarc-utilities
Author: INICODE
Author-email: contact.inicode@gmail.com
License: MIT
Keywords: python,inicode,pyarcflow,workflow,async,scheduler,automation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
Requires-Dist: pyarcidgen
Provides-Extra: http
Requires-Dist: httpx>=0.24.0; extra == "http"
Provides-Extra: all
Requires-Dist: httpx>=0.24.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# pyarcflow

**Moteur de workflow asynchrone** pour Python et ARC-CMS.

`pyarcflow` permet de définir, d'enregistrer et d'exécuter des workflows sous forme de graphes de nœuds reliés par des transitions conditionnelles. Il fournit un ensemble de tâches prêtes à l'emploi (feature, HTTP, condition, attente, notification, boucle) ainsi qu'un scheduler pour planifier des exécutions.

Conçu et maintenu par **INICODE**.

---

## Table des matières

1. [Installation](#installation)
2. [Démarrage rapide](#démarrage-rapide)
3. [Concepts](#concepts)
4. [Tâches disponibles](#tâches-disponibles)
5. [Transitions conditionnelles](#transitions-conditionnelles)
6. [Scheduler](#scheduler)
7. [API de référence](#api-de-référence)
8. [Tests](#tests)
9. [Architecture](#architecture)

---

## Installation

```bash
pip install pyarcflow
```

### Dépendances

- `pyarcidgen` — génération d'identifiants uniques pour les instances.

### Dépendances optionnelles

- `httpx` — requêtes HTTP pour `HttpTask`.

```bash
pip install pyarcflow[http]
```

### Installation en mode développeur (depuis les sources)

```bash
git clone https://github.com/inicode/pyarc-utilities.git
cd pyarc-utilities
python cmd.py --build --only pyarcflow
pip install dist/pyarcflow-*.whl
```

---

## Démarrage rapide

```python
import asyncio
from pyarcflow import WorkflowEngine, WorkflowBuilder, FeatureTask

engine = WorkflowEngine()
wf = (
    WorkflowBuilder("hello")
    .add_node("start", FeatureTask("module_manager_feature.list_modules", module="module_manager"))
    .build()
)
engine.register(wf)

async def main():
    state = await engine.start("hello", context={"user": "alice"})
    print(state.to_dict())

asyncio.run(main())
```

---

## Concepts

- **Workflow** : définition statique d'un graphe (`Workflow`).
- **Node** : nœud du graphe associé à une tâche (`Task`).
- **Transition** : lien conditionnel entre deux nœuds.
- **Instance** : exécution concrète d'un workflow (`WorkflowState`).
- **Engine** : registre et exécuteur de workflows (`WorkflowEngine`).

---

## Tâches disponibles

| Tâche | Description |
|-------|-------------|
| `FeatureTask` | Appelle une feature `pyarccore`. |
| `HttpTask` | Effectue une requête HTTP asynchrone. |
| `ConditionTask` | Évalue une expression Jinja2. |
| `WaitTask` | Attend un nombre de secondes. |
| `NotifyTask` | Envoie une notification e-mail ou WebSocket. |
| `LoopTask` | Itère sur une liste et exécute une sous-tâche. |

Exemple avec une condition :

```python
from pyarcflow import WorkflowBuilder, ConditionTask, WaitTask

wf = (
    WorkflowBuilder("demo")
    .add_node("check", ConditionTask("value > 10"))
    .add_node("wait", WaitTask(seconds=2), transitions=[{"to": "check", "condition": "value > 10"}])
    .build()
)
```

---

## Transitions conditionnelles

Les transitions utilisent des expressions **Jinja2** évaluées dans le contexte courant.

```python
WorkflowBuilder("demo").add_node(
    "start",
    some_task,
    transitions=[
        {"to": "success", "condition": "status == 'ok'"},
        {"to": "failure", "condition": "status != 'ok'"},
    ],
)
```

---

## Scheduler

Le scheduler permet de planifier l'exécution périodique de workflows.

```python
from pyarcflow import Scheduler

sched = Scheduler()

async def run_heartbeat():
    await engine.start("heartbeat")

sched.add_job(run_heartbeat, "interval", job_id="heartbeat", seconds=60)
sched.start()
```

Si `APScheduler` est installé, il est utilisé en backend ; sinon un scheduler léger basé sur `threading` est utilisé.

---

## API de référence

```python
from pyarcflow import (
    WorkflowEngine,
    WorkflowBuilder,
    WorkflowLoader,
    WorkflowState,
    Scheduler,
    Transition,
    Task,
    TaskResult,
    FeatureTask,
    HttpTask,
    ConditionTask,
    WaitTask,
    NotifyTask,
    LoopTask,
    WorkflowError,
)
```

### WorkflowEngine

- `register(workflow)` — enregistre un workflow.
- `start(workflow_id, context, instance_id)` — démarre une instance.
- `cancel(instance_id)` — annule une instance en cours.
- `list_workflows()` — liste les workflows enregistrés.

### WorkflowBuilder

- `set_trigger(trigger)` — définit le déclencheur.
- `add_node(node_id, task, transitions)` — ajoute un nœud.
- `build()` — construit le workflow.

### Scheduler

- `add_job(func, trigger, job_id, **kwargs)` — ajoute un job.
- `remove_job(job_id)` — supprime un job.
- `pause_job(job_id)` / `resume_job(job_id)` — gère l'état.
- `list_jobs()` — liste les jobs planifiés.
- `start()` / `shutdown()` — démarre / arrête le scheduler.

---

## Tests

```bash
# Tests du plugin pyarcflow
python cmd.py --test --only pyarcflow

# Ou directement avec unittest
python -m unittest discover -s tests/pyarcflow -p "*.py"
```

---

## Architecture

```text
pyarcflow/
├── __init__.py       # API publique
├── engine.py         # WorkflowEngine, Workflow, Node
├── builder.py        # WorkflowBuilder fluent
├── loader.py         # Chargement depuis fichiers .py
├── state.py          # WorkflowState
├── scheduler.py      # WorkflowScheduler / Scheduler
├── transitions.py    # Transition
├── exceptions.py     # Exceptions
└── tasks/            # Tâches exécutables
    ├── base.py
    ├── feature.py
    ├── http.py
    ├── condition.py
    ├── wait.py
    ├── notify.py
    └── loop.py
```

---

## Auteur

Développé avec passion par **INICODE** — `contact.inicode@gmail.com`.

Licence : MIT.
