# GitHub Copilot – Instructions pour le projet

## Objectif
Créer une librairie Python modulaire et importable
Les spécifications détaillées de cette librairie se trouvent dans `specification.md`. 
Le module doit être simple, performant, typé, et sans dépendances inutiles.

## Style de code attendu
- Respect strict de **PEP8**.
- Typage Python **obligatoire** (typing).
- Respect strict de **PEP257** pour les docstrings strictement en style Google
- Utilisation systématique de **Polars** plutôt que Pandas.
- Découpage logique en modules si nécessaire, selon la complexité du code obtenu
- L'API doit être basée sur une ou plusieurs classes. Pas de fonctions pures à moins que cela ne soit absolument nécessaire.
- Ne pas ajouter de dépendance superflue à des modules qui ne seraient pas livrés dans la distribution python sauf gain significatif sur la complexité du code.
- Code compatible Python 3.10+.


## Directives pour Copilot
- Toujours proposer un design modulaire.
- Toujours proposer des exemples d'utilisation dans les docstrings.
- Préférer les DataFrame Polars lazy lorsque possible.
- Privilégier les fonctions Polars au code Python standard pour obtenir la meilleure performace possible.
- Générer des tests unitaires avec pytest.
- Si un fichier n’existe pas encore, proposer sa création automatiquement.
- Favoriser un code clair et auto-documenté.
- Les identifiants et les commentaires doient être en anglais.
- Rester cohérent avec l’architecture définie.
- la clarté et la lisibilité du code sont prioritaires sur la concision. 
- La complexite algorithmique doit être optimisée: choisir par exemple un algorithme en O(log n) plutôt qu’en O(n) si cela est possible même au détriment de la lisibilité.
- Ne pas hésiter à ajouter des commentaires raisonnablement concis (deux ou trois lignes max) à chaque grande étape du code pour expliquer ce qui est fait et pourquoi mais sans paraphraser le code lui-même.
- Si on peut organiser le code en modules logiques aux interfaces bien définies, faire un découpage en modules.
- uv doit être utilisé. Ne jamais utiliser venv ni y faire référence.


## Ce que Copilot doit éviter
- Ne **jamais** éditer les fichiers d'instructions, sauf si je te le demande **expressément** dans le chat.
- Pas de code Pandas.
- Pas de classes inutiles ou juste là pour l'esthétique du code. Mais respecter absolument la décision de créer une classe si la spécification le demande.
- Eviter les modules utilitaires. Si des fonctions sont nécessaires, voir s'il est possible de les intégrer dans les classes existantes soit comme métodes d'instance soit plus probablementcomme méthodes statiques. Mais ne pas tordre le code pour éviter à tout prix de créer un module utilitaire si cela rend le code plus clair et plus lisible. En d'autres termes, privilégier la clarté du code plutôt que la pureté de son architecture.
- Pas de code non typé.
- Ne pas ajouter de dépendance externe superflue à des modules qui ne seraient pas livrés dans la distribution python sauf gain significatif sur la complexité et la lisibilité du code.
- Pas de génération de fichiers en dehors de l’arborescence standard.
- Pas de logique métier dans `__init__.py`.
- Inutile de faire des commentaires pour expliquer le "comment" dans le code: le code lui-même fait déjà ça très bien
- On ne fait pas de commentaire sur une fonction ou une classe dans son ensemble: ce rôle doit être joué par la docstring. 
- Ne pas générer de code "drap de lit": les fonctions doivent être concises et faire une seule chose avec une interface claire. Si une fonction devient trop longue, il faut la découper en plusieurs fonctions plus petites selon ces principes de concision et de clarté. Même principe pour le découpage en modules: si un module devient trop long ou complexe, il faut le découper en plusieurs modules autonomes plus petits.

## Comportement attendu
- Si un fichier n’existe pas encore, proposer sa création automatiquement.

## Fichiers d’instructions locaux
Pour chaque fichier source X.py, Copilot doit automatiquement lire et suivre le fichier X.instructions.md
situé dans le même dossier si ce fichier existe. 
