Leçon 10-3 — Lire du code, lire la doc, demander de l'aide

1. Objectif

À la fin de cette leçon tu sauras : explorer un projet Python inconnu avec méthode (trouver l'entrée, cartographier la structure, suivre une fonctionnalité de bout en bout), chercher une réponse dans la doc officielle (docs.python.org) au lieu d'un tutoriel, lire une signature de fonction dans la doc (y compris les mystérieux / et *), poser une question de débogage qui obtient une réponse, et écrire ton plan de progression personnel pour l'après-méthode.

2. Pourquoi c'est important

Jusqu'ici, chaque notion t'a été servie découpée et dans l'ordre. Ça s'arrête : après le niveau 10, tu apprendras comme tous les développeurs — en lisant du code écrit par d'autres, en fouillant la doc, et en posant des questions. Un développeur professionnel passe plus de temps à lire du code qu'à en écrire ; savoir entrer dans un projet inconnu est la compétence d'embauche par excellence. Et savoir formuler une bonne question, c'est 50 % du débogage : la moitié des questions bien posées se répondent toutes seules pendant qu'on les rédige. Cette leçon ne t'apprend pas une dernière notion Python — elle t'apprend à apprendre les suivantes sans moi.

3. Explication simple

Lire un projet inconnu, c'est comme arriver dans une ville inconnue. Tu ne visites pas les rues par ordre alphabétique : tu prends la carte (le README), tu repères la gare — l'endroit par où tout entre (le point d'entrée du programme) — puis tu suis UNE ligne de bus du départ au terminus (UNE fonctionnalité, de l'entrée jusqu'à l'effet). Après deux ou trois lignes de bus, tu connais la ville — sans avoir visité chaque rue. Personne, jamais, ne lit un projet fichier par fichier de haut en bas.

Lire la doc, c'est utiliser le mode d'emploi officiel au lieu de demander au voisin. docs.python.org dit toujours la vérité, pour TA version de Python, avec tous les paramètres — quand un tutoriel de blog dit à peu près la vérité, pour la version d'il y a cinq ans, avec les deux paramètres que l'auteur connaissait.

Demander de l'aide, c'est fournir à l'autre (humain ou IA) exactement ce qu'il lui faut pour reproduire ton problème : le contexte, le plus petit code qui montre le bug, l'erreur exacte copiée-collée, et ce que tu as déjà tenté. « Ça marche pas » n'est pas une question — c'est un soupir.

4. Explication approfondie

a) La méthode d'exploration, en quatre passes. Pour tout projet inconnu :

  1. La carte : lire le README (quoi, pour qui, comment on le lance) et la liste des fichiers. 5 minutes, sans ouvrir le code.
  2. La gare : trouver le point d'entrée. Indices, par ordre de fréquence : un bloc if __name__ == "__main__": (⏩ niveau 05), un fichier __main__.py (c'est lui qui s'exécute avec python -m <paquet>), un main.py ou cli.py, ou la section [project.scripts] d'un pyproject.toml.
  3. Le squelette : ouvrir chaque module et lire SEULEMENT les lignes def et class (et le docstring de tête). Tu obtiens la table des matières du projet sans te noyer dans les corps de fonctions.
  4. Une ligne de bus : choisir UNE fonctionnalité visible et la suivre de l'entrée à l'effet, avec la recherche dans les fichiers (Ctrl+Maj+F dans VS Code) et « Aller à la définition » (F12 / Ctrl+clic). C'est cette passe qui fait vraiment comprendre le projet.

Règle d'or : tu n'as pas besoin de tout comprendre. Viser 100 % d'un projet inconnu, c'est le moyen sûr d'abandonner à 10 %. Vise : « je sais où sont les choses et je peux suivre un fil ».

b) docs.python.org a trois étages — et on se perd quand on se trompe d'étage :

Complément local : help(objet) dans le terminal Python affiche la doc sans navigateur — essaie help(sorted).

c) Lire une signature de la doc. Exemple réel :

sorted(iterable, /, *, key=None, reverse=False)

Décodage : le / signifie « tout ce qui est à gauche est positionnel uniquement » (interdit d'écrire sorted(iterable=...)) ; le * signifie « tout ce qui est à droite est par mot-clé uniquement » (obligatoire d'écrire key=len, pas sorted(data, len)) ; =None et =False sont les valeurs par défaut — donc facultatifs. Ces deux symboles arrêtent d'être mystérieux une fois qu'on sait qu'ils ne sont pas des paramètres mais des séparateurs. Guette aussi les encadrés « Changed in version 3.x » : ils expliquent pourquoi un vieux tutoriel contredit la doc.

d) L'anatomie d'une bonne question. Quatre pièces, toutes obligatoires :

  1. Contexte : ce que tu essaies d'accomplir (le but, pas la technique) + ta version de Python et ton OS si pertinent.
  2. Code minimal reproductible : le PLUS PETIT programme complet qui montre le problème. Pas ton projet entier, pas trois lignes sans leurs variables — un extrait qu'un inconnu peut coller et exécuter. Construire ce minimal résout la question une fois sur deux : en retirant du code, tu isoles le coupable.
  3. L'erreur exacte : le traceback COMPLET, copié-collé — jamais paraphrasé (« ça me met une erreur de type » ne suffit pas), jamais en capture d'écran.
  4. Ce que tu as tenté : deux ou trois pistes essayées et leur résultat. Ça évite les réponses « as-tu essayé X ? » et ça prouve le travail.

Ce gabarit vaut pour un forum, un collègue… et une IA : Claude répond d'autant mieux que la question contient ces quatre pièces. Et la règle du README du niveau s'applique à toute réponse reçue : ne coller que ce qu'on peut réexpliquer. Si tu ne peux pas expliquer la réponse ligne par ligne, tu n'as pas fini — demande « explique-moi cette ligne » avant de l'adopter.

e) Continuer seul après la méthode. Un plan de progression tient en trois listes : (1) deux ou trois sujets à approfondir ensuite, choisis parce que tes projets en ont besoin (pas parce qu'ils brillent) ; (2) un projet par sujet — on n'apprend rien sans projet ; (3) un rythme réaliste (par exemple : 3 sessions/semaine, revue mensuelle dans le journal). Les mécanismes de la méthode qui restent valables à vie : journal, révisions espacées, commits disciplinés, cadrage avant code.

Difficulté honnête : lire le code des autres est frustrant au début — tout paraît trop malin, trop dense, plein de choses jamais vues. C'est normal et ça ne signifie PAS que tu n'es pas prêt : même les seniors ressentent ça devant un projet inconnu. La différence est qu'ils ont une méthode et tolèrent l'inconfort. Donne-toi le droit de ne pas comprendre 30 % des lignes — tant que tu peux suivre le fil.

5. Exemples commentés

Exemple 1 — explorer un vrai projet : le paquet json de la bibliothèque standard. C'est du code réel, écrit par d'autres, déjà sur ta machine. Trouvons-le puis appliquons la méthode :

import json, inspect, os
print(os.path.dirname(inspect.getfile(json)))
C:\Users\jtron\AppData\Local\Python\pythoncore-3.14-64\Lib\json

Passe 1, la carte — le contenu du dossier :

__init__.py     365 lignes   ← la façade : dump/dumps/load/loads vivent ici
__main__.py      20 lignes   ← le point d'entrée de `python -m json`
decoder.py      364 lignes   ← JSON → objets Python
encoder.py      461 lignes   ← objets Python → JSON
scanner.py       73 lignes   ← découpage bas niveau du texte
tool.py         121 lignes   ← l'outil en ligne de commande

~1 400 lignes : un projet de taille très raisonnable, et le découpage en modules raconte déjà l'architecture (une façade, deux sens de conversion, un outil CLI) — exactement le genre de structure que ton projet final devrait avoir.

Exemple 2 — la gare : lire __main__.py en entier (20 lignes, on peut) :

import json.tool

if __name__ == '__main__':
    try:
        json.tool.main()
    except BrokenPipeError as exc:
        raise SystemExit(exc.errno)

Tout y est : le point d'entrée ne fait RIEN lui-même, il délègue à json.tool.main(). Fil suivant à tirer : ouvrir tool.py et lire main() — tu y trouveras un argparse (⏩ niveau 09) construit exactement comme dans tes projets. Le code des pros n'est pas d'une autre nature que le tien.

Exemple 3 — suivre une ligne de bus : « d'où vient indent=2 ? »

import json
print(json.dumps({"b": 1, "a": 2}, indent=2, sort_keys=True))
{
  "a": 2,
  "b": 1
}

Le fil : dumps est dans __init__.py (recherche def dumps, ligne ~185) ; sa signature commence par dumps(obj, *, skipkeys=False, ... — tiens, le * de la section 4c : tout se passe par mots-clés ; le corps montre que dumps délègue à un JSONEncoder… défini dans encoder.py. En trois sauts (F12 à chaque fois), tu as traversé l'architecture du paquet. C'est ça, « lire du code » : suivre un fil, pas tout lire.

Exemple 4 — une question mal posée, puis bien posée.

Version qui n'obtiendra pas de réponse :

salut mon script csv marche pas ça me met une erreur de liste
quelqu'un peut m'aider ??

La même, au gabarit des quatre pièces :

CONTEXTE — Python 3.14, Windows. Je lis un CSV de dépenses et j'additionne la
colonne montant. Le fichier a bien une ligne d'en-tête.

CODE MINIMAL (plante à l'identique avec ce CSV de 2 lignes) :
    import csv
    with open("expenses.csv", encoding="utf-8") as f:
        rows = list(csv.reader(f))
    total = sum(row[1] for row in rows)
expenses.csv :
    date,amount
    2026-07-01,12.50

ERREUR EXACTE :
    Traceback (most recent call last):
      File "C:\Users\jtron\demo\total.py", line 4, in <module>
        total = sum(row[1] for row in rows)
    TypeError: unsupported operand type(s) for +: 'int' and 'str'

DÉJÀ TENTÉ — print(rows) : tout est en str, ET la ligne d'en-tête est dans
rows. Je pense qu'il faut sauter l'en-tête et convertir en float, mais je ne
sais pas si csv sait faire ça tout seul ou si je le fais à la main.

Remarque ce qui s'est passé : en rédigeant la pièce 4, l'auteur a pratiquement trouvé la réponse (sauter l'en-tête, convertir). C'est l'effet canard en plastique : expliquer le problème à voix haute — même à un canard posé sur le bureau — le résout une fois sur deux. La question bien posée EST un outil de débogage.

Exemple 5 — chercher dans la doc, pas dans un tutoriel. Question : « il existe un truc pour enlever un préfixe d'une chaîne ? ». Réflexe doc : page Library Reference → str (méthodes des chaînes) → balayer la liste alphabétique → str.removeprefix(prefix). Vérification locale :

print("feat/export-csv".removeprefix("feat/"))   # export-csv

Temps total : deux minutes, réponse sûre et à jour. Le même chemin par tutoriels/vidéos : dix minutes, et une chance sur trois de tomber sur la vieille bidouille s[len(p):] d'avant Python 3.9. La doc d'abord — le tutoriel seulement si la doc reste obscure.

6. Erreurs fréquentes

1) Lire un projet fichier par fichier, de haut en bas. Symptôme : 40 minutes sur le premier fichier, découragement, abandon. Ce n'est pas un roman. Correction : les quatre passes de la section 4a — carte, gare, squelette, une ligne de bus.

2) Chercher un tutoriel avant la doc. Les tutoriels vieillissent mal, simplifient trop, et visent une autre version. Correction : docs.python.org d'abord ; le tutoriel comme SECOURS si la doc reste obscure — jamais l'inverse. (Le tutoriel garde un usage légitime : découvrir un domaine entier dont tu ignores tout.)

3) Poser une question sans traceback. « ça me met une erreur de type » — paraphrasé, donc inutilisable : le traceback contenait le fichier, la ligne et le message exacts. Correction : copier-coller le traceback COMPLET, en texte (pas en capture d'écran — illisible sur mobile, impossible à copier).

4) Le faux code minimal. Coller ses 200 lignes (« quelque part là-dedans ») ou l'extrait de 3 lignes qui n'inclut même pas les variables utilisées. Correction : construire un vrai programme minimal exécutable — et accepter que ça prenne 15 minutes : c'est du débogage, pas de la politesse.

5) Copier une réponse (forum ou IA) sans la comprendre. Ça « marche » aujourd'hui, et demain c'est indébogable — tu ne peux pas réparer ce que tu ne comprends pas. Correction : la règle du niveau — ne coller que ce qu'on peut réexpliquer ligne par ligne. Sinon : « explique-moi cette ligne » d'abord.

6) Vouloir tout comprendre du projet exploré. Symptôme : bloqué sur un détail pointu de scanner.py alors que le but était de comprendre la structure. Correction : l'objectif d'exploration est « je sais où sont les choses et je peux suivre un fil » — noter le mystère dans le journal, et continuer.

7. Lire les messages d'erreur

Depuis le niveau 01 tu lis les tracebacks de TON code. Deux situations nouvelles ici.

Le traceback de quelqu'un d'autre (dans une question de forum, ou d'un collègue) se lit avec la même méthode — dernière ligne d'abord — plus un réflexe : vérifier de quel fichier vient chaque étage. Un traceback qui traverse un projet inconnu mélange SES fichiers et ceux des bibliothèques :

Traceback (most recent call last):
  File "C:\project\cli.py", line 42, in main          ← le code du projet
    data = load_config(path)
  File "C:\project\config.py", line 17, in load_config ← le code du projet
    return json.loads(text)
  File "...\Lib\json\__init__.py", line 346, in loads  ← la stdlib (pas le bug !)
    ...
json.decoder.JSONDecodeError: Expecting property name enclosed in
double quotes: line 1 column 3 (char 2)

Le bug n'est presque jamais dans l'étage « bibliothèque » (des millions de gens l'utilisent) : il est dans le DERNIER étage appartenant au projet — ici, ce que config.py a passé à json.loads. C'est aussi comme ça qu'on lit les tracebacks pendant l'exploration d'un projet : ils sont une carte d'appel, du point d'entrée jusqu'au crash.

Les « erreurs » de la doc ne sont pas des exceptions mais des encadrés à prendre au sérieux : Deprecated since version 3.x (ne pas utiliser dans du code neuf), Changed in version 3.x (la raison n°1 des tutoriels contradictoires). Devant un comportement qui contredit un vieil article, le réflexe est : la doc de TA version a raison.

8. Exercices — faciles

Règles : réponses en Markdown dans lessons/level-10-autonomie/exercices/mes-reponses/ (ex-10-3-a.md, etc.). Pour les recherches doc : interdiction de consulter autre chose que docs.python.org (et help()) — c'est tout l'exercice.

a) En n'utilisant QUE la doc officielle, réponds à ces trois questions, et note pour chacune la page où tu as trouvé : (1) que fait str.removesuffix et depuis quelle version existe-t-il ? (2) quel paramètre de sorted permet de trier en ordre décroissant, et peut-on le passer en positionnel ? (3) dans le module csv, quelle classe lit chaque ligne comme un dictionnaire ?

b) Décode ces deux signatures en une phrase chacune (rôle de /, * et des valeurs par défaut) : sorted(iterable, /, *, key=None, reverse=False) et json.dumps(obj, *, skipkeys=False, ensure_ascii=True, ...) — pourquoi json.dumps(data, 2) est-il une erreur alors que json.dumps(data, indent=2) marche ?

c) Réécris cette question au gabarit des quatre pièces (invente les détails manquants de façon plausible) : « python veut pas ouvrir mon fichier, jsp pourquoi, une idée ? »

9. Exercices — moyens

a) Explore le paquet json de TA machine avec les quatre passes (l'exemple 1 t'a donné la carte — fais les passes 3 et 4 toi-même) et produis une carte d'une page : rôle de chaque module en une ligne, le point d'entrée de python -m json, et le fil complet de json.load(f) (quelles fonctions dans quels fichiers, dans l'ordre). Piège de la section 6 à éviter : si tu te surprends à lire scanner.py ligne à ligne, tu es en train de « lire le roman ».

b) Prends le dernier vrai bug que tu as rencontré (niveau 08 ou 09 — fouille ton journal) et rédige rétroactivement la question parfaite à son sujet : contexte, code minimal reproductible QUE TU AS VRAIMENT EXTRAIT ET EXÉCUTÉ, traceback, pistes. Note en bas : la rédaction t'a-t-elle fait voir quelque chose que tu n'avais pas vu à l'époque ?

c) Choisis dans la Library Reference un module que tu n'as JAMAIS utilisé, guidé par un besoin réel de ton projet final (candidats classiques : datetime, pathlib, collections, random, textwrap). En te servant uniquement de sa page de doc, écris un script de 10–20 lignes qui en utilise trois fonctions/classes, avec un commentaire par usage citant ce que la doc en dit.

10. Exercices — difficiles

a) L'exploration hors les murs : choisis un petit projet Python open source sur GitHub (critères : moins de ~3 000 lignes de Python, un CLI de préférence, un README digne de ce nom — cherche par exemple dans les topics cli + python un outil que tu aimerais avoir écrit). Clone-le, applique les quatre passes, et produis la carte : structure annotée, point d'entrée, UNE fonctionnalité suivie de bout en bout (liste des sauts : fichier → fonction → fichier → fonction), et trois choses que ce projet fait mieux que les tiens (que tu voleras pour ton projet final).

b) Écris ton plan de progression post-méthode (une page, format de la section 4e) : deux ou trois sujets choisis PARCE QUE tes projets en ont besoin, un projet concret par sujet, un rythme réaliste, et les mécanismes de la méthode que tu gardes. Ce document part dans ton journal — c'est lui que tu relis dans trois mois.

11. Mini-projet lié — « exploration guidée d'un projet open source »

C'est le mini-projet prévu par le README du niveau, et c'est l'exercice 10-a mené au propre : la carte complète du projet open source choisi, rédigée comme si tu devais l'expliquer à un autre apprenant — structure, point d'entrée, un fil suivi de bout en bout, trois idées volées. Ajoute une section « ce que je n'ai pas compris » assumée (elle fait partie de l'exercice : cartographier SES propres zones de brume, c'est le métier). Durée : 45 min après l'exercice 10-a. Range-la dans exercices/mes-reponses/exploration-<nom-du-projet>.md.

12. Correction / méthode de correction

Les solutions détaillées sont dans solutions/serie-10-3-solutions.md — dont les réponses doc sourcées, une carte de référence complète du paquet json, une question modèle au gabarit, et un exemple de plan de progression rempli.

Méthode : pour les recherches doc, compare le CHEMIN autant que la réponse (es-tu passé par la Library Reference ou par un moteur de recherche qui t'a recraché un blog ?). Pour l'exploration, ta carte peut différer de la mienne : le test n'est pas la conformité, c'est « quelqu'un d'autre peut-il naviguer le projet avec ta carte ? ». Pour le plan de progression, personne n'a la solution — vérifie seulement les trois listes (sujets tirés de besoins réels, un projet par sujet, un rythme tenable).

13. À retenir

14. Questions de révision

  1. Quelles sont les quatre passes d'exploration d'un projet inconnu, et que produit chacune ?
  2. Cite trois endroits où chercher le point d'entrée d'un projet Python.
  3. Quelle est la différence entre le Tutorial et la Library Reference de docs.python.org, et lequel utilises-tu au quotidien ?
  4. Dans sorted(iterable, /, *, key=None, reverse=False), pourquoi sorted(data, len) échoue-t-il ?
  5. Quelles sont les quatre pièces d'une bonne question, et laquelle résout souvent le problème à elle seule ?
  6. Pourquoi un traceback en capture d'écran est-il une mauvaise pratique ?
  7. Que fais-tu d'une réponse d'IA qui marche mais que tu ne comprends pas ?
  8. Que contiennent les trois listes d'un plan de progression post-méthode ?

15. Checklist de compréhension

Si une case reste vide : refais les exercices de la section correspondante demain, AVANT d'ouvrir la leçon suivante.

16. Commit conseillé

git add lessons/level-10-autonomie/exercices/mes-reponses/
git commit -m "exercises: complete lesson 10-3 reading code and docs"

Puis, si c'est ta fin de session : entrée de journal + git push.