sk-python

Écrire et déboguer du Python en prêtant attention aux pièges qui produisent des comportements erronés silencieux — valeurs par défaut mutables, fermetures à liaison tardive, copies superficielles, exceptions avalées — ainsi qu'aux types, à l'environnement et au packaging avec uv ou venv, et à la structure pytest. À utiliser lors de l'écriture d'un script, d'un service ou d'une bibliothèque Python, de la mise en place d'un projet Python, ou du débogage d'un comportement qui semble impossible.

Qu'est-ce que sk-python ?

Ce skill fournit un guide complet pour éviter les pièges courants de Python qui échouent silencieusement, comme les arguments par défaut mutables, les fermetures liées tardivement et les copies superficielles. Il couvre la configuration de l'environnement et du packaging avec `uv`, `venv`, et `pyproject.toml` pour garantir la reproductibilité, ainsi que les bonnes pratiques d'annotation de types avec `typing` et la vérification en CI avec des outils comme `mypy`. Les idiomes essentiels, les structures de test avec `pytest` (paramétrage, fixtures, assertions d'exceptions) et les astuces de performance (profilage, concurrence, opérations vectorisées) sont détaillés. Le skill est conçu pour les développeurs utilisant des agents d'IA comme Claude Code, Cursor ou Codex afin de produire du code Python fiable et maintenable.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-python

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Python

Python est facile à écrire et facile à se tromper subtilement. Ce document couvre les pièges qui échouent silencieusement et la configuration de projet qui évite un environnement cassé.

Pièges qui échouent silencieusement

Les arguments par défaut mutables sont évalués une fois, à la définition, et partagés par chaque appel :

def add(item, bucket=[]):   # faux : bucket persiste entre les appels
def add(item, bucket=None): # correct
    bucket = [] if bucket is None else bucket

Les fermetures se lient tardivement. Une lambda créée dans une boucle capture la variable, pas sa valeur, donc chacune d'elles voit la valeur finale. Liez-la explicitement avec un argument par défaut, ou utilisez functools.partial.

is est l'identité, pas l'égalité. Cela fonctionne pour None, True et False, et pour rien d'autre. Cela semble fonctionner pour les petits entiers et les courtes chaînes parce qu'ils sont internés, ce qui est exactement la raison pour laquelle le bug survit aux tests.

Les copies sont superficielles. list(xs), xs[:] et dict(d) copient le conteneur et partagent les éléments. Les structures imbriquées nécessitent copy.deepcopy.

Un except: nu attrape tout, y compris KeyboardInterrupt et SystemExit. Attrapez l'exception spécifique, et n'écrivez jamais except Exception: pass — si elle est vraiment ignorable, enregistrez-la et dites pourquoi.

Division entière et égalité de flottants. / produit toujours un flottant ; // arrondit vers la négation infinie, donc -7 // 2 donne -4. Ne comparez jamais des flottants avec == ; utilisez math.isclose, ou Decimal pour l'argent.

Itérer une collection tout en la mutant saute des éléments. Construisez une nouvelle liste, ou itérez une copie.

Les générateurs sont consommés une fois. Un second passage sur le même générateur ne produit rien, ce qui se lit comme un résultat vide plutôt qu'une erreur.

Environnement et packaging

N'installez jamais dans l'interpréteur système. Créez un environnement virtuel par projet et activez-le, ou laissez uv le gérer :

uv venv && uv pip install -e ".[dev]"     # ou : python -m venv .venv

Déclarez les dépendances dans pyproject.toml, et engagez un fichier de verrouillage pour que l'environnement soit reproductible. Un requirements.txt avec des versions non épinglées n'est pas reproductible et cassera sur une machine future.

Épinglez la version Python que le projet supporte et déclarez-la dans pyproject.toml. Le comportement diffère entre les versions mineures plus que ce que les gens attendent.

Quand quelque chose importe à un endroit et pas à un autre, la cause est presque toujours l'interpréteur plutôt que le code. Vérifiez which python et python -c "import sys; print(sys.executable)" avant de déboguer l'import.

Types

Annotez les signatures de fonctions — paramètres et retour. Le corps a rarement besoin d'annotation ; la frontière en a toujours besoin, car c'est ce dont les autres codes dépendent.

Exécutez un vérificateur de types dans le CI. Les annotations que rien ne vérifie se dégradent et deviennent une documentation trompeuse.

Utilisez X | None plutôt qu'un optionnel nu par convention, et rendez l'optionalité visible dans la signature. Préférez les types spécifiques à Any ; quand le type est vraiment inconnu, utilisez l'équivalent de unknown — object — et réduisez-le, afin que le vérificateur force la réduction.

Pour les données structurées, préférez un dataclass, ou un modèle validant à la frontière où les données arrivent de l'extérieur. Un dictionnaire de chaînes passé entre fonctions perd toute garantie à la première faute de frappe.

Idiomes qui comptent

Utilisez une compréhension quand elle mappe ou filtre, et une boucle quand elle fait autre chose. Une compréhension avec un effet secondaire ou trois clauses est plus difficile à lire que la boucle qu'elle remplace.

Utilisez pathlib.Path plutôt que des chemins de chaînes, et un gestionnaire de contexte pour tout ce qui doit être fermé — fichiers, connexions, verrous, répertoires temporaires.

Produisez avec yield from un générateur plutôt que de construire une liste quand l'entrée est grande ou illimitée ; c'est la différence entre un script qui diffuse et un qui épuise la mémoire.

Utilisez enumerate, zip, et dict.get avec une valeur par défaut plutôt que l'arithmétique d'index et les vérifications d'appartenance. Ils sont plus rapides et ils éliminent une classe d'erreurs de décalage.

Tests

pytest, avec assert simple. Utilisez @pytest.mark.parametrize pour les cas pilotés par tableau plutôt qu'une boucle à l'intérieur d'un test, afin que chaque cas soit rapporté séparément.

Placez la configuration partagée dans une fixture avec la portée la plus étroite qui fonctionne. Une fixture de portée session qui contient un état mutable fuit entre les tests et produit des échecs dépendants de l'ordre.

Affirmez l'exception spécifique avec pytest.raises, y compris le message quand cela compte.

Performance, quand elle compte

Mesurez avant d'optimiser — time.perf_counter pour un chiffre approximatif, cProfile pour savoir où ça va.

Le gain habituel consiste à déplacer le travail hors de l'interpréteur : une fonction native, une compréhension, str.join au lieu de concaténations répétées, une recherche dans un set ou dict au lieu de parcourir une liste, ou un appel de bibliothèque vectorisée pour le travail numérique.

Pour la concurrence liée aux E/S, utilisez asyncio ou des threads ; pour le travail lié au CPU, utilisez des processus, car le verrou global de l'interpréteur (GIL) signifie que les threads n'aideront pas.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Skills associés