Python Digne

Guidance Python opiniâtre pour écrire du code Python propre, maintenable et moderne (versions 3.10-3.13).

Quand utiliser cette compétence

Auto-invoquer quand les utilisateurs demandent :

• « rendre ceci pythonic » / « est-ce du bon python »
• « type hints » / « type annotations » / « typing »
• « LBYL vs EAFP » / « exception handling »
• « pathlib vs os.path » / « opérations sur les chemins »
• « CLI patterns » / « utilisation de click »
• « code review » / « améliorer ce code »
• Toute question sur la qualité ou les normes du code Python

Note : Cette compétence est du guidance Python style à usage général, non spécifique à Dagster. Elle capture un ensemble de conventions explicites penchant vers LBYL ; les conventions du projet peuvent la surcharger si nécessaire.

Quand utiliser cette compétence par rapport aux autres

Connaissance Core (TOUJOURS Chargée)

@dignified-python-core.md

Version Detection

Identifier la version Python minimale du projet en vérifiant (dans l'ordre) :

1. pyproject.toml - Chercher le champ requires-python (ex. requires-python = ">=3.12")
2. setup.py ou setup.cfg - Chercher python_requires
3. Fichier .python-version - Contient une version comme 3.12 ou 3.12.0
4. Par défaut Python 3.12 si aucun spécificateur de version trouvé

Une fois identifiée, charger le fichier spécifique à la version :

• Python 3.10 : Charger versions/python-3.10.md
• Python 3.11 : Charger versions/python-3.11.md
• Python 3.12 : Charger versions/python-3.12.md
• Python 3.13 : Charger versions/python-3.13.md

Chargement Conditionnel (Charger Selon les Patterns de Tâche)

Les fichiers core ci-dessus couvrent 80%+ des patterns de code Python. Charger ces fichiers supplémentaires uniquement si vous détectez des patterns spécifiques :

Exemples de détection de pattern :

• Si la tâche mentionne « click » ou « CLI » -> Charger cli-patterns.md
• Si la tâche mentionne « subprocess » -> Charger subprocess.md

Structure de la Documentation de Référence

Le matériel de référence de cette compétence est organisé par sujet :

Références Core

• dignified-python-core.md - Normes essentielles (toujours chargé)
• cli-patterns.md - Patterns d'interface en ligne de commande (click, argparse)

Références Version-Spécifiques (versions/)

• python-3.10.md - Features disponibles en Python 3.10+
• python-3.11.md - Features disponibles en Python 3.11+
• python-3.12.md - Features disponibles en Python 3.12+
• python-3.13.md - Features disponibles en Python 3.13+

Sujets Avancés (references/advanced/)

• exception-handling.md - Patterns LBYL, error boundaries
• interfaces.md - Patterns ABC et Protocol
• typing-advanced.md - Patterns typing avancés
• api-design.md - Principes de design d'API

Quand lire chaque document de référence

references/advanced/exception-handling.md

Lire quand :

• Écrire des blocs try/except
• Wrapper des APIs tierces qui peuvent lever
• Voir ou écrire from e ou from None
• Incertain si une alternative LBYL existe

references/advanced/interfaces.md

Lire quand :

• Créer des classes ABC ou Protocol
• Écrire des décorateurs @abstractmethod
• Concevoir des interfaces de couche gateway
• Choisir entre ABC et Protocol

references/advanced/typing-advanced.md

Lire quand :

• Utiliser typing.cast()
• Créer des alias de type Literal
• Affiner des types dans des blocs conditionnels

references/module-design.md

Lire quand :

• Créer de nouveaux modules Python
• Ajouter du code au niveau module (au-delà de simples constantes)
• Utiliser le décorateur @cache au niveau module
• Voir Path() ou un calcul au niveau module
• Envisager des imports inline

references/advanced/api-design.md

Lire quand :

• Ajouter des valeurs de paramètre par défaut aux fonctions
• Définir des fonctions avec 5 paramètres ou plus
• Utiliser ThreadPoolExecutor.submit()
• Revoir les signatures de fonction

references/checklists.md

Lire quand :

• Révision finale avant commit du code Python
• Incertain d'avoir suivi tous les règles
• Besoin d'une lookup rapide des requirements

Comment utiliser cette compétence

1. La connaissance core est chargée automatiquement (defaults, pathlib, imports, anti-patterns)
2. La version detection se fait une seule fois - identifier la version Python minimale et charger le fichier de version approprié
3. Les documents de référence sont chargés à la demande selon les déclencheurs ci-dessus
4. Les patterns supplémentaires peuvent nécessiter un chargement supplémentaire (CLI patterns, subprocess)
5. Chaque fichier est auto-contenu avec un guidance complet pour son domaine