Code/docs/GUIDE_RUFF.md

Guide d'utilisation de Ruff

Configuration effectuee

J'ai configure Ruff pour votre projet FabNum avec deux fichiers :

1. pyproject.toml

Configuration principale de Ruff avec :

• Longueur de ligne : 120 caractères maximum
• Exclusions : pgpt/, IA/, batch_ia/ (modules priorite basse)
• Regles activees :
  • Erreurs de style (pycodestyle)
  • Detection de bugs (pyflakes, bugbear)
  • Docstrings obligatoires (pydocstyle)
  • Tri automatique des imports (isort)
  • Simplifications de code
  • Detection de code mort

2. .vscode/settings.json

Configuration VSCodium pour :

• Formattage automatique avec Ruff
• Organisation des imports au save
• Detection des problemes en temps reel
• Integration avec pytest

Utilisation dans VSCodium

Actions automatiques

Lorsque vous ouvrez un fichier Python, Ruff va :

• Souligner en rouge/jaune les problemes detectes
• Proposer des corrections rapides (Quick Fix)
• Organiser les imports quand vous sauvegardez

Actions manuelles

Voir tous les problemes :

• Panneau "Problemes" (Ctrl+Shift+M)
• Filtre par fichier, par type (erreur/warning)

Corriger automatiquement :

1. Clic droit sur le code souligne
2. "Quick Fix..." (Ctrl+.)
3. Selectionner "Ruff: Fix all auto-fixable problems"

Organiser les imports :

• Clic droit > "Organiser les imports"
• Ou sauvegarde automatique (deja configure)

Formater un fichier :

• Clic droit > "Formater le document"
• Ou Shift+Alt+F

Regles principales pour les docstrings

Ruff va exiger des docstrings au format Google :

Fonction simple

def calculer_ivc(graph, node):
    """Calcule l'indice de vulnerabilite competitive pour un noeud.

    Args:
        graph: Le graphe NetworkX contenant les donnees.
        node: L'identifiant du noeud a analyser.

    Returns:
        float: La valeur IVC calculee.

    Raises:
        ValueError: Si le noeud n'existe pas dans le graphe.
    """
    # code...

Fonction complexe avec exemples

def synchroniser_gitea(repo_name, force=False):
    """Synchronise les donnees locales avec le depot Gitea.

    Cette fonction compare les timestamps locaux et distants pour determiner
    si une synchronisation est necessaire. En mode force, ignore le cache.

    Args:
        repo_name: Nom du depot Gitea (DEPOT_FICHES ou DEPOT_CODE).
        force: Si True, force la synchronisation meme si le cache est valide.

    Returns:
        dict: Dictionnaire avec les cles :
            - 'synced': bool, True si synchronisation effectuee
            - 'files_updated': int, nombre de fichiers mis a jour
            - 'timestamp': str, horodatage de la synchronisation

    Raises:
        ConnectionError: Si impossible de contacter le serveur Gitea.
        ValueError: Si repo_name n'est pas reconnu.

    Example:
        >>> result = synchroniser_gitea('DEPOT_FICHES', force=True)
        >>> print(result['files_updated'])
        12
    """
    # code...

Classe

class GraphAnalyzer:
    """Analyseur de graphes pour les chaines d'approvisionnement.

    Cette classe fournit des methodes pour analyser les dependances
    et calculer les indices de risque sur un graphe NetworkX.

    Attributes:
        graph: Le graphe NetworkX a analyser.
        config: Configuration des seuils et parametres.
    """

    def __init__(self, graph, config=None):
        """Initialise l'analyseur avec un graphe.

        Args:
            graph: Graphe NetworkX des dependances.
            config: Configuration optionnelle (dict).
        """
        # code...

Ce que Ruff va detecter

Problemes de docstrings

• Fonctions publiques sans docstring
• Docstrings mal formatees
• Arguments non documentes
• Valeurs de retour non documentees

Problemes de code

• Imports non utilises
• Variables definies mais jamais utilisees
• Code mort (apres return/break)
• Comparaisons dangereuses (== None au lieu de is None)
• Lignes trop longues (>120 caracteres)
• Complexite trop elevee

Suggestions d'amelioration

• Utiliser pathlib au lieu de os.path
• Simplifier les comprehensions
• Utiliser f-strings au lieu de .format()
• Remplacer list() + comprehension par comprehension directe

Commandes utiles (si Ruff CLI installe)

Si vous souhaitez installer Ruff en ligne de commande :

pip install ruff

# Verifier tout le projet
ruff check app/ utils/

# Corriger automatiquement ce qui peut l'etre
ruff check app/ utils/ --fix

# Voir les statistiques
ruff check app/ utils/ --statistics

# Formater le code
ruff format app/ utils/

Prochaines etapes

1. Rechargez VSCodium pour que la configuration prenne effet
2. Ouvrez un fichier Python (ex: app/fiches/interface.py)
3. Regardez le panneau Problemes (Ctrl+Shift+M)
4. Vous verrez la liste des problemes detectes par Ruff

Ruff va vous guider pour :

• Ajouter les docstrings manquantes
• Corriger les problemes de style
• Ameliorer la qualite du code

Questions frequentes

Q: Trop de problemes affiches, c'est normal ? R: Oui, la premiere fois Ruff peut detecter beaucoup de choses. Traitez-les progressivement, module par module.

Q: Puis-je desactiver certaines regles ? R: Oui, editez pyproject.toml, section [tool.ruff.lint] > ignore.

Q: Comment ignorer un warning sur une ligne specifique ? R: Ajoutez un commentaire : # noqa: CODE (ex: # noqa: D103 pour ignorer docstring manquante)

Q: formatOnSave est a false, pourquoi ? R: Pour eviter de reformater tout le code d'un coup. Vous pouvez le mettre a true quand vous serez pret.

Fichiers de configuration

• pyproject.toml : Configuration Ruff (regles, exclusions, style)
• .vscode/settings.json : Integration VSCodium
• requirements.txt : Dependances Python (existe deja)

Support

Pour plus d'informations : https://docs.astral.sh/ruff/