Doc Technique - PyTaskRunner (Runner CLI de tâches Python)

À quoi ça sert ?

PyTaskRunner sert à organiser et exécuter des “tâches projet” récurrentes : build, tests, lint, release, backup, jobs d’ops, scripts de maintenance, etc. L’idée : au lieu d’avoir 25 scripts éparpillés, tu écris des fonctions Python annotées et tu les exécutes via une commande unique pytask.

Pourquoi c’est utile (en vrai) :

Tu standardises la manière de lancer les tâches (local, CI, serveur)
Tu factorises dépendances + ordre d’exécution (ex : deploy dépend de build et test)
Tu peux activer --dry pour vérifier sans exécuter
Tu charges automatiquement un .env pour secrets/config locale (API_KEY, HOST, etc.)
Tu gardes du Python : conditions, boucles, génération de commandes, etc.

Dépendances & Orchestration

Définis une tâche deploy qui dépend de build et test. PyTaskRunner garantit l’ordre.

@task(deps=[...])toposortcycle detection

Shell streaming

sh() exécute une commande et laisse le stdout/stderr “en live” (parfait pour pytest, rsync, docker).

subprocesscheck=Truerc handling

.env intégré

Charge un .env local et expose ctx.env pour tes tâches (sans dépendance python-dotenv).

load_dotenvctx.envoverride control

Comparaison (PyTaskRunner vs scripts dispersés)

Problème courant	Sans runner	Avec PyTaskRunner
Ordre build/test/deploy	docs + “faut penser à…”	`deps=["build","test"]` (automatique)
Secrets & config	env bricolé / export manuel	`.env` chargé + `ctx.env`
Lisibilité / maintenance	bash + scripts multiples	1 fichier `tasks.py` versionnable/testable
Dry-run	souvent absent	`--dry` (validation safe)

Philosophie : petit, stable, sans dépendances. PyTaskRunner ne remplace pas un CI/CD, il sert à standardiser l’exécution des tâches projet et à éviter les scripts “one-shot” oubliés.

Installation (.whl)

PyTaskRunner est livré en wheel (installation rapide dans ton venv). Une fois installé, tu obtiens la commande pytask.

Télécharger le Wheel (pytaskrunner v0.1.0)

/static/toolbox/pytaskrunner-0.1.0-py3-none-any.whl

Commande d’installation

# venv activé
pip install /chemin/local/pytaskrunner-0.1.0-py3-none-any.whl

Vérifier que la CLI est disponible

pytask --help
pytask list

Si “pytask: command not found” :

vérifie que ton venv est bien activé
ou lance via python -m pytaskrunner (option alternative si tu ajoutes un entrypoint plus tard)

Quickstart (5 minutes)

Étape 1 — Crée un fichier tasks.py à la racine

from pytaskrunner import task, sh

@task(desc="Run unit tests")
def test(ctx):
    sh("pytest -q")

@task(desc="Build wheel")
def build(ctx):
    sh("python -m build")

@task(desc="Deploy (example)", deps=["build", "test"])
def deploy(ctx):
    sh("echo Deploying...")

Étape 2 — Liste les tâches

pytask list

Résultat →Tasks: build, deploy (deps=[build,test]), test

Étape 3 — Exécute une tâche simple

pytask run test

Étape 4 — Exécute une tâche avec deps

pytask run deploy

Résultat →build → test → deploy (dans cet ordre)

Étape 5 — Dry-run pour valider sans exécuter

pytask run deploy --dry

Résultat →DRY-RUN: skipped execution of build/test/deploy

Une fois ce schéma en place, tu peux remplacer progressivement tes scripts dispersés par des tâches bien nommées.

Exemples concrets (dev, ops, Django)

1) Tasks “Dev” classiques (lint / tests / format)

from pytaskrunner import task, sh

@task(desc="Format code")
def fmt(ctx):
    sh("ruff format .")

@task(desc="Lint")
def lint(ctx):
    sh("ruff check .")

@task(desc="Tests", deps=["lint"])
def test(ctx):
    sh("pytest -q")

2) Wheel + Release local

Centralise build + vérifications + génération artefacts.

@task(desc="Build dist")
def build(ctx):
    sh("python -m build")

@task(desc="Check dist")
def check(ctx):
    sh("python -m pip install -U twine")
    sh("twine check dist/*")

@task(desc="Release local", deps=["build", "check"])
def release(ctx):
    sh("ls -lh dist")

3) Django : migrations / collectstatic / runserver

@task(desc="Django migrate")
def migrate(ctx):
    sh("python manage.py migrate")

@task(desc="Collect static")
def collectstatic(ctx):
    sh("python manage.py collectstatic --noinput")

@task(desc="Run dev server", deps=["migrate"])
def run(ctx):
    sh("python manage.py runserver 0.0.0.0:8000")

4) Ops : backup PostgreSQL (env via .env)

Exemple : dans .env : PGHOST, PGUSER, PGDATABASE, BACKUP_DIR.

@task(desc="Backup Postgres")
def pg_backup(ctx):
    host = ctx.env.get("PGHOST","localhost")
    user = ctx.env.get("PGUSER","postgres")
    db   = ctx.env.get("PGDATABASE","app")
    out  = ctx.env.get("BACKUP_DIR","./backups")
    sh(f"mkdir -p {out}")
    sh(f"pg_dump -h {host} -U {user} {db} | gzip > {out}/{db}.sql.gz")

Remarque : sh() stream le stdout/stderr. Pour des secrets, privilégie env plutôt que l’inline.

5) Télécharger/Sync artefacts (rsync)

@task(desc="Sync dist to server", deps=["build"])
def sync(ctx):
    host = ctx.env.get("DEPLOY_HOST","myserver")
    sh(f"rsync -av dist/ {host}:/srv/releases/")

6) Exemple de sortie attendue (logs)

# pytask run deploy
[12:01:03] INFO Running task: build — Build wheel
... build output ...
[12:01:07] OK   Done: build (4.12s)
[12:01:07] INFO Running task: test — Run unit tests
... pytest output ...
[12:01:15] OK   Done: test (7.88s)
[12:01:15] INFO Running task: deploy — Deploy (example)
Deploying...
[12:01:15] OK   Done: deploy (0.12s)

Avancé (deps, jobs, patterns, pièges)

Dépendances : règles & erreurs

PyTaskRunner calcule un ordre via tri topologique. En cas de cycle (A dépend de B et B dépend de A), l’exécution échoue volontairement.

Erreurs typiques :

Task inconnue dans deps → “Unknown task”
Cycle de dépendances → “Cycle detected”
Commande shell rc!=0 → stop (fail-fast) + code retour non zéro

Jobs parallèles (-j) best-effort

Si plusieurs dépendances sont indépendantes, PyTaskRunner peut les lancer en parallèle. Attention : si deux tâches touchent les mêmes fichiers, tu peux créer des race conditions.

pytask run deploy -j 4

Conseil : réserve le parallel à des tâches “read-only” (lint/test) ou à des steps réellement indépendants.

Pattern recommandé : tâches petites + composables

Pattern	Pourquoi
tâches courtes (`lint`, `test`, `build`)	plus faciles à réutiliser comme deps (ex: deploy dépend de build+test)
tâches “meta” (`ci`, `release`)	juste des deps, pas de logique compliquée
utiliser `.env` pour config locale	évite hardcode, simplifie usage multi-env

Trucs utiles à ajouter en V2 (si tu veux)

Arguments de task : pytask run backup -- --full (pass-through args)
Hooks : pre=["lint"] / post=["report"]
Capture output optionnelle (pour logs structurés)
Affichage “plan” d’exécution (graph deps)