python-resilience

Présentation de la skill python-resilience

Ce que fait python-resilience

La skill python-resilience vous aide à concevoir du code Python qui échoue de façon plus sûre lorsque des dépendances sont peu fiables. Elle se concentre sur des patterns de résilience concrets : retries, exponential backoff, jitter, timeouts, fenêtres de retry bornées et wrappers tolérants aux pannes autour des appels externes.

À qui s’adresse cette skill

Cette python-resilience skill convient particulièrement aux développeurs, équipes plateforme et utilisateurs d’agents qui travaillent sur des services communiquant avec des API, des bases de données, des files de messages ou d’autres systèmes en réseau. Elle est particulièrement utile si vous avez besoin d’une aide à la génération de code qui va au-delà de « ajouter un retry » et qui choisit à la place des limites de gestion d’échec cohérentes.

Le vrai besoin auquel elle répond

La plupart des utilisateurs n’ont pas besoin d’une page théorique sur la fiabilité. Ils ont besoin de patterns Python utilisables pour répondre à des questions comme :

• « Cette erreur doit-elle être retentée ou faut-il échouer immédiatement ? »
• « Quelle stratégie de backoff reste sûre sous charge ? »
• « Où faut-il placer les timeouts ? »
• « Comment éviter les retries infinis et les thundering herds ? »
• « Quel décorateur ou helper doit encapsuler cet appel externe ? »

La python-resilience skill est précieuse parce qu’elle explicite ces choix, au lieu de traiter la logique de retry comme un simple correctif en une ligne.

Ce qui la distingue d’un prompt générique

Un prompt de code générique peut ajouter des retries partout ou ignorer la différence entre pannes transitoires et permanentes. python-resilience for Reliability adopte une approche plus directive : ne retenter que les échecs réellement retryable, ajouter du jitter, plafonner le nombre de tentatives et la durée totale, et considérer les frontières externes comme l’endroit principal où ajouter la logique de résilience.

Ce que couvre réellement la source

La skill amont se limite à un seul fichier SKILL.md, mais son contenu est substantiel. Il se concentre sur :

• les pannes transitoires vs permanentes
• l’exponential backoff
• le jitter
• les retries bornés
• des exemples Python concrets avec tenacity

Cela la rend rapide à inspecter et facile à adopter, mais cela signifie aussi qu’il faut s’attendre à des recommandations, pas à une bibliothèque packagée ni à un harness de test.

Quand cette skill est particulièrement pertinente

Utilisez python-resilience si vous :

• appelez des API tierces
• encapsulez des interactions réseau ou service instables
• construisez des microservices ou des workers
• ajoutez des garde-fous de fiabilité à des utilitaires client partagés
• gérez du rate limiting, des indisponibilités temporaires ou des timeouts intermittents

Si votre code se compose surtout de logique locale pure en mémoire, cette skill n’est probablement pas l’installation la plus rentable.

Comment utiliser la skill python-resilience

Contexte d’installation de python-resilience

Installez la skill depuis le dépôt wshobson/agents :

npx skills add https://github.com/wshobson/agents --skill python-resilience

Après l’installation, ouvrez d’abord le fichier de la skill :

• plugins/python-development/skills/python-resilience/SKILL.md

Cette zone du dépôt semble ne contenir que le document de la skill ; l’adoption est donc simple : lisez la skill, puis appliquez ses patterns dans votre propre base de code.

Commencez par lire ce fichier

Parcourez SKILL.md du début à la fin. Les sections les plus utiles à lire en priorité sont :

1. When to Use This Skill
2. Core Concepts
3. Quick Start

Cet ordre de lecture vous donne d’abord l’adéquation du cas d’usage, puis les règles de conception, puis la forme de mise en œuvre avant de demander au modèle de modifier votre code.

Ce que la skill attend comme informations de votre part

La qualité d’utilisation de python-resilience dépend fortement du contexte que vous fournissez. Avant d’invoquer la skill, réunissez :

• la fonction ou la frontière de service à protéger
• le type de dépendance : HTTP API, DB, queue, cache, filesystem
• les exceptions exactes ou symptômes d’échec observés
• le caractère transitoire ou permanent des pannes
• les attentes en matière de timeout
• les contraintes d’idempotence
• la latence maximale acceptable
• le budget de retry : nombre de tentatives ou durée totale
• la possibilité que de nombreux clients retry en même temps

Sans ces éléments, le modèle produira souvent une logique de retry trop large.

Transformer un objectif flou en prompt efficace

Prompt faible :

Add resilience to this Python API client.

Meilleur prompt :

Use the python-resilience skill to refactor this Python client method.

Context:
- Dependency: third-party HTTP API
- Library: httpx
- Traffic: moderate, bursty
- Common failures: read timeout, connect timeout, occasional 429 and 503
- Permanent failures: 400, 401, 403 should not be retried
- Idempotency: safe to retry GET requests only
- SLO: fail within 8 seconds total
- Requirement: use bounded retries, exponential backoff with jitter, and clear logging

Task:
- Propose a retry policy
- Implement the wrapper/decorator
- Explain which exceptions and status codes are retryable
- Show where timeout configuration should live

Cela fonctionne mieux parce que vous donnez à la skill les frontières de décision pour lesquelles elle est conçue.

Demandez d’abord la policy, puis le code

Un bon workflow avec le python-resilience guide consiste à :

1. demander une classification des échecs
2. demander une policy de retry/timeout
3. examiner les compromis
4. puis seulement générer le code d’implémentation

Cela évite de partir directement sur des décorateurs avant d’avoir décidé ce qui doit, ou non, être retenté.

Utiliser la skill aux frontières externes

La skill est la plus efficace lorsqu’elle s’applique à du code qui franchit des frontières de processus ou de réseau, par exemple :

• des appels httpx ou requests
• la publication ou la consommation de messages
• des requêtes base de données avec des modes d’échec transitoires connus
• des appels SDK cloud
• des méthodes de client de service

Ne commencez pas par encapsuler de bout en bout de gros workflows métier. Placez d’abord les contrôles de résilience autour de la dépendance instable.

À quoi doit ressembler un bon résultat python-resilience

Lorsque la skill fonctionne bien, le résultat doit généralement inclure :

• des règles explicites pour distinguer pannes transitoires et permanentes
• des limites de retry finies
• de l’exponential backoff
• du jitter
• l’emplacement des timeouts
• des exemples avec des outils Python comme tenacity
• des notes sur l’idempotence et les effets de bord

Si le résultat se limite à « retry 3 times », demandez une policy de retry plus explicite.

Pattern d’implémentation pratique à demander

La skill source inclut un quick start basé sur tenacity. En pratique, cela signifie que vous pouvez demander des patterns comme :

• un décorateur autour d’une méthode de client de service
• un helper wrapper pour tous les appels HTTP sortants
• des policies de retry distinctes pour lecture et écriture
• des retries filtrés par type d’exception ou code de statut

Pour les opérations de mutation, demandez au modèle de justifier pourquoi le retry est sûr. Les patterns de fiabilité qui ignorent l’idempotence peuvent créer des effets de bord dupliqués.

Erreurs fréquentes lors de l’usage de python-resilience

Surveillez ces problèmes dans le code généré :

• retry de pannes d’authentification ou de validation
• absence de timeout, avec uniquement des retries
• boucles de retry sans budget total
• backoff sans jitter
• trop de code encapsulé, ce qui masque la cause racine
• retry par défaut d’écritures non idempotentes

Ce sont des blocages concrets bien plus importants que le style de code.

Un workflow utile dans votre dépôt

Pour de meilleurs résultats, fournissez à la skill :

• la fonction client actuelle
• les classes d’exception visibles dans les logs
• des exemples de codes de statut
• votre budget de latence ou de retry
• une ou deux traces d’échec représentatives

Puis demandez :

1. un résumé de la policy
2. les modifications de code
3. les tests à ajouter
4. les champs de monitoring à logger

Cette séquence produit généralement des résultats plus faciles à adopter qu’une simple demande de code.

FAQ sur la skill python-resilience

python-resilience est-elle réservée aux API web ?

Non. La python-resilience skill traite plus largement des dépendances peu fiables. Les appels HTTP sont l’exemple le plus simple, mais le même raisonnement s’applique aux files de messages, bases de données, caches et services cloud où les pannes transitoires sont courantes.

Est-ce une bibliothèque ou une skill de guidance ?

C’est une skill de guidance, pas un package Python autonome. Elle enseigne des patterns et montre un style d’implémentation, y compris avec des exemples basés sur tenacity, mais c’est à vous d’appliquer ces patterns dans votre propre base de code.

Quand ne faut-il pas utiliser python-resilience ?

N’utilisez pas python-resilience comme couche par défaut au-dessus de chaque fonction. Elle est peu adaptée pour :

• la logique locale pure limitée au CPU
• les erreurs clairement permanentes
• les workflows où des retries dupliqueraient des effets de bord risqués
• les systèmes dont les budgets de latence sont trop serrés pour des fenêtres de retry

Dans ces cas, mieux vaut échouer rapidement ou repenser l’intégration.

python-resilience convient-elle aux débutants ?

Oui, si vous maîtrisez déjà les bases de Python et de la gestion des exceptions. Les idées centrales de la skill sont accessibles, mais l’utilisateur doit tout de même fournir le contexte métier : sécurité des retries, budgets de timeout et types d’échecs qu’il est acceptable de retenter.

En quoi est-ce mieux que de demander simplement des retries à un LLM ?

L’avantage de python-resilience for Reliability ne se limite pas à la génération de code. Elle aide le modèle à raisonner sur les catégories d’échec, les retries bornés et le comportement du backoff. Les prompts génériques ratent souvent ces frontières et produisent une logique de retry risquée ou trop bruyante sous charge.

python-resilience choisit-elle la policy de retry exacte à ma place ?

Pas automatiquement. Elle fournit un vocabulaire de patterns solide, mais la meilleure policy dépend du comportement de votre dépendance, de vos exigences de latence et de vos règles d’idempotence. Attendez-vous à ajuster le nombre de tentatives, les plages d’attente et les filtres de retry selon votre environnement.

Comment améliorer la skill python-resilience

Mieux classer les pannes pour python-resilience

Le moyen le plus rapide d’améliorer les résultats de python-resilience consiste à préciser quels échecs sont transitoires et lesquels sont permanents. Par exemple :

• transitoires : ConnectTimeout, ReadTimeout, 503, certains 429
• permanents : 400, 401, 403, erreurs de schéma, identifiants invalides

Cette distinction à elle seule détermine souvent si la policy générée est sûre.

Fournir des budgets de latence et de retry

Si vous ne fournissez pas de budget, le modèle peut choisir des nombres de retries arbitraires. Indiquez des limites comme :

• maximum 3 tentatives
• fenêtre totale de retry inférieure à 8 secondes
• timeout par requête de 2 secondes
• job en arrière-plan tolérant jusqu’à 30 secondes au total

Ces contraintes produisent un code plus réaliste.

Préciser si les opérations sont idempotentes

Beaucoup d’erreurs de résilience viennent d’un manque de contexte sur les effets de bord. Améliorez l’usage de python-resilience en indiquant si les opérations sont :

• sûres à retry
• sûres uniquement avec une idempotency key
• dangereuses à retry automatiquement

Cela change à la fois la conception du décorateur et les filtres d’exception.

Demander des règles explicites de non-retry

Ne demandez pas seulement « qu’est-ce qui doit être retenté ? ». Demandez aussi :

• qu’est-ce qui doit échouer immédiatement ?
• qu’est-ce qui doit être remonté au caller sans délai ?
• qu’est-ce qui doit être loggé mais non retenté ?

Cela rend la sortie beaucoup plus exploitable en production.

Demander de l’observabilité avec l’implémentation

Un bon python-resilience guide ne doit pas s’arrêter aux décorateurs. Demandez au modèle d’ajouter :

• le nombre de tentatives dans les logs
• le type d’exception
• le temps écoulé
• la raison finale de l’échec
• un message d’épuisement des retries

Sans cela, votre couche de résilience peut masquer pourquoi les appels échouent.

Itérer après la première version

Après la première sortie, affinez avec des retours concrets comme :

• « Ne retry pas les requêtes POST. »
• « Plafonne la durée totale, pas seulement le nombre de tentatives. »
• « Gère 429 différemment de 500. »
• « Utilise du jitter pour éviter des retries synchronisés. »
• « Sépare la configuration de timeout de la configuration de retry. »

Ce type d’itération améliore sensiblement l’implémentation.

Tester les chemins d’échec proposés par la skill

Demandez au modèle de générer des tests pour :

• le retry sur exception transitoire
• le comportement fast-fail sur exception permanente
• l’épuisement des retries
• l’application des timeouts
• les limites de la policy de backoff

Un code de résilience non testé est facile à mal configurer et difficile à fiabiliser.

Améliorer la sortie de la skill avec de vraies traces

Si vous avez des logs ou des exemples de stack traces, incluez-les. Des preuves d’échec réelles aident python-resilience à recommander des filtres d’exception plus ciblés et des réglages de timeout/backoff plus crédibles que des prompts abstraits.

Garder un niveau d’abstraction modeste

Un écueil fréquent consiste à demander à la skill de concevoir tout un framework de résilience alors que vous avez seulement besoin d’un wrapper client fiable. Commencez plus petit :

• une fonction
• une dépendance
• une policy de retry

Puis élargissez après avoir validé l’utilité du pattern.

Utiliser python-resilience comme grille de revue

Même si vous avez déjà écrit le code, python-resilience reste utile comme prompt de revue. Demandez-lui d’inspecter la logique de retry existante pour repérer :

• des retries non bornés
• l’absence de jitter
• un mauvais placement des timeouts
• des retries d’échecs permanents
• des risques cachés d’effets de bord

Dans les bases de code matures, ce cas d’usage orienté revue est souvent l’application la plus rentable de la skill.