Mettre à jour une dépendance en toute sécurité
- Étude de cas 2
- 150 min
- Facultative · 1 étude de cas requise pour le certificat
Où nous en sommes
Cette étude de cas applique les vérifications de dépendances et la révision ligne par ligne du module 3 à une mise à jour qui brise la compatibilité. Vous sauvegardez le comportement actuel, laissez un assistant proposer les changements, et vérifiez chacun avec le vrai journal des modifications avant de fixer la nouvelle version.
Étude de cas 2 sur 2 · Développement logiciel assisté par l'IAMettre à jour une dépendance en toute sécurité
1. Mettre en place un environnement de travail sûr
2. Rédiger des tâches exploitables
3. Réviser le travail généré
4. Déboguer et tester avec l'assistant
5. Livrer un travail facile à maintenir
Ce que vous saurez faire
Faites passer un petit projet d’une version majeure d’un paquet à la suivante. Lisez le journal des modifications avant l’installation, et sauvegardez le comportement actuel. Laissez un assistant proposer les changements au code. Vérifiez ensuite chaque changement avec le vrai journal des modifications et le comportement sauvegardé. Fixez la nouvelle version et consignez la décision.
L’équipe du cours a écrit form-intake pour cette étude de cas, sous licence MIT. Ses 32 soumissions de formulaire Web sont inventées. Le paquet dont il dépend, marshmallow, existe et est largement utilisé. Ses versions et son journal des modifications sont aussi réels. La session avec l’assistant est un véritable enregistrement fourni avec le projet. Vous n’avez donc besoin ni d’assistant ni de compte.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
Cette étude de cas applique tout le cours à un projet que vous ne connaissez pas. Elle s’appuie surtout sur Vérifier les dépendances, Examiner les différences, Reproduire d’abord, Choisir des vérifications utiles et Documenter les décisions. Le fichier de verrouillage vient d’Isoler les dépendances, dans le cours de Python. Les branches viennent de L’essentiel de Git et du développement en équipe.
Ce qu’il vous faut sur votre ordinateur
- Python 3.12 ou une version plus récente, Git et VS Code.
- Environ 60 Mo d’espace disque libre et une connexion Internet pour
pip. - Aucun compte ni paiement. Un assistant est facultatif : la session enregistrée se trouve dans le téléchargement.
Testé sur macOS (Apple silicon) avec Python 3.14.6 et pip 26.1.2. Les commandes Windows sont écrites, mais non testées. Les identifiants de commit (enregistrement des changements) sur votre ordinateur seront différents de ceux présentés ici.
La situation
Section intitulée « La situation »Grace, responsable du soutien, envoie à Amira deux soumissions rejetées par le formulaire Web :
« Deux clients ont appuyé sur Help (aide), et
form-intakeles a rejetés avec “Not a valid URL.” (URL non valide). Les deux pages existent :https://larkfield.example#helpsur la page d’accueil ethttps://café.larkfield.example/helpsur le site du café. Pouvez-vous corriger ça? »
form-intake vérifie chaque soumission du formulaire Web de Larkfield avant qu’elle arrive au service de soutien. Il décrit les règles avec marshmallow, un paquet qui vérifie les données selon un schéma : une liste de champs et de règles. C’est la règle URL de marshmallow qui vérifie les adresses Web, et non le code de Larkfield.
Amira lit le journal des modifications de marshmallow. Les versions récentes acceptent les deux adresses : les noms de domaine internationaux depuis 4.2.4, et #help directement après le domaine depuis 4.3.1. form-intake fixe la version à 3.26.2. La correction exige donc une mise à jour vers une nouvelle version majeure, de 3 à 4.
Tomás a un plan rapide : « Remplaçons le 3 par un 4. Laissons l’assistant corriger ce qui casse, puis fusionnons quand les tests passent. » Kwame demande : « Qu’est-ce que la version 4 change d’autre, et comment le saurons-nous? »
L’objectif. Faites passer form-intake à marshmallow 4.3.1 pour que :
- Les deux soumissions de Grace soient acceptées.
- Toutes les autres décisions restent identiques, sauf si l’équipe choisit de les modifier et consigne pourquoi.
- Chaque changement au code corresponde à une véritable entrée du journal des modifications de marshmallow.
- Les tests passent, sans aucun avertissement.
- La nouvelle version soit fixée et la décision soit consignée.
Ce que vous allez faire
Section intitulée « Ce que vous allez faire »Description textuelle du diagramme
Neuf étapes, du problème de Grace aux nouvelles entrées. Les tests passent à l’étape 5, après le changement de l’assistant. La révision à l’étape 6 trouve six formats d’heure qui reçoivent maintenant une autre décision. Aucun test ne les avait détectés.
Le projet et sa licence
Section intitulée « Le projet et sa licence »| Fichier | Son rôle |
|---|---|
form_intake/schema.py |
Les règles, sous forme de schéma marshmallow, et check_submissions() |
form_intake/cli.py |
La commande : lit un fichier JSON, écrit out/accepted.json et out/rejected.json |
tests/ |
13 tests des règles et de la commande |
data/submissions.json |
12 soumissions inventées, dont les deux de Grace |
data/time-formats.json |
10 façons d’écrire l’heure d’une soumission, une soumission par format |
data/new-submissions.json |
10 autres soumissions, pour la fin |
tools/compare.py |
Liste les soumissions dont la décision a changé entre deux exécutions |
DECISIONS.md, README.md |
Les choix et les règles dans un tableau |
Le projet est sous licence MIT, avec la mention « Copyright (c) Nextia Learning ». marshmallow est aussi sous licence MIT, par Steven Loria et les personnes qui y contribuent. pip le télécharge depuis PyPI; il n’est pas dans le fichier zip. La fiche dataset.md du téléchargement indique ce qui est réel et ce qui est construit.
Préparer le projet
Section intitulée « Préparer le projet »-
Téléchargez le projet de départ depuis l’encadré en haut de cette page. Créez un dossier
~/projects/upgrade-case-studyet décompressez-y le fichier. Vous obtenez deux dossiers :form-intakeetassistant-session. -
Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier), puis ouvrez
form-intake. Ouvrez ensuite un terminal : Terminal > New Terminal (terminal, nouveau terminal). -
Créez et activez un environnement virtuel. Installez ensuite les versions exactes du fichier de verrouillage :
Fenêtre de terminal python3 -m venv .venvsource .venv/bin/activatepython -m pip install -r requirements-lock.txtFenêtre de terminal python -m venv .venv.venv\Scripts\Activate.ps1python -m pip install -r requirements-lock.txtFenêtre de terminal python3 -m venv .venvsource .venv/bin/activatepython -m pip install -r requirements-lock.txt -
Exécutez les tests et le programme :
Fenêtre de terminal python -m pytestpython -m form_intake data/submissions.jsonpython -m form_intake --versionOutput (the last lines) ======================= 13 passed, 20 warnings in 0.03s ========================12 submissions: 3 accepted, 9 rejected.Saved: out/accepted.json, out/rejected.jsonform_intake 1.0.0 (marshmallow 3.26.2) -
Faites du projet un dépôt Git avec un commit, comme dans L’essentiel de Git et du développement en équipe :
Fenêtre de terminal git initgit add -Agit commit -m "Start"
Ce que cela nous apprend. Les tests passent, mais avec 20 avertissements. Vous les lirez dans la partie 2. Ouvrez out/rejected.json : T-4007 et T-4011 sont les deux soumissions de Grace, rejetées avec "page_url": ["Not a valid URL."] (URL non valide).
Numéros de version et versions incompatibles
Section intitulée « Numéros de version et versions incompatibles »Une nouvelle édition du livre de recettes
Section intitulée « Une nouvelle édition du livre de recettes »Votre livre de recettes préféré a une nouvelle édition. La plupart des pages restent identiques. Mais la nouvelle édition ne contient plus la sauce de votre repas du dimanche. Elle cuit aussi le gâteau à une température plus basse. Si vous cuisinez sans lire l’avant-propos, le repas du dimanche échoue et le gâteau reste pâle. Personne ne vous avertit devant la cuisinière. Pourtant, l’éditeur vous avait prévenu : dans l’avant-propos et dans une note du dernier tirage de l’ancienne édition.
Le problème : un seul nombre, et plus rien ne fonctionne
Section intitulée « Le problème : un seul nombre, et plus rien ne fonctionne »Le plan de Tomás consiste à remplacer marshmallow==3.26.2 par 4.3.1 et à voir ce qui arrive. L’auteur a fait exactement cela, sur une branche (la partie 4 le montre). Aucun test ne s’est exécuté :
E TypeError: Field.__init__() got an unexpected keyword argument 'missing'!!!!!!!!!!!!!!!!!!! Interrupted: 2 errors during collection !!!!!!!!!!!!!!!!!!!!Cette erreur est évidente. Les changements silencieux sont pires : une version peut modifier ce que le code fait, sans aucune erreur. Vous les trouvez seulement si vous savez où chercher.
L’idée : le numéro de version vous indique où chercher
Section intitulée « L’idée : le numéro de version vous indique où chercher »La plupart des paquets Python numérotent leurs versions selon MAJOR.MINOR.PATCH (majeure.mineure.correctif). Ce système s’appelle le versionnage sémantique. Un nouveau numéro PATCH (4.3.0 → 4.3.1) corrige des bogues. Un nouveau numéro MINOR (4.2 → 4.3) ajoute des fonctionnalités. Il peut aussi rendre quelque chose obsolète : cela fonctionne encore, mais affiche un avertissement annonçant sa suppression. Un nouveau numéro MAJOR (3 → 4) peut supprimer ou modifier des éléments : c’est une version incompatible. Le journal des modifications du projet liste les changements de chaque version. marshmallow marque les changements incompatibles par Backwards-incompatible (rétro-incompatible) et propose un guide de mise à jour.
Un nouveau numéro MAJOR signifie donc : lisez le journal des modifications avant l’installation. Et l’avertissement d’obsolescence actuel sera l’erreur de la prochaine version MAJOR.
Un petit exemple : les versions importantes pour form-intake
Section intitulée « Un petit exemple : les versions importantes pour form-intake »Description textuelle du diagramme
Une liste de versions tirée du journal des modifications de marshmallow. Quatre versions MINOR de la série 3.x ont rendu obsolètes des éléments que form-intake utilise. 4.0.0 les a tous supprimés et a changé la lecture des heures. 3.26.2, la version fixée par form-intake, est un PATCH avec un correctif de sécurité, sorti après 4.0.0. 4.2.4 et 4.3.1 ont corrigé les deux adresses Web.
Deux détails de l’image comptent. D’abord, les correctifs de Grace sont dans 4.2.4 et 4.3.1, pas dans 4.0.0. L’auteur a vérifié : 4.0.0 rejette encore les deux adresses. Ensuite, 3.26.2 est plus récente que 4.0.0 selon la date. Un projet peut continuer quelque temps à corriger une ancienne série MAJOR pour les équipes qui n’ont pas encore migré. Utilisez le numéro de version, pas la date, pour juger les changements.
Les quatre vérifications de Vérifier les dépendances s’appliquent aussi à une nouvelle version d’un paquet que vous utilisez déjà. Elle existe. Vous en avez besoin pour les correctifs de Grace. Sa licence reste MIT. Et elle prend en charge votre Python : le journal des modifications de 4.1.0 indique « Test against Python 3.14 » (tester avec Python 3.14).
Partie 1 : le problème de Grace sous forme de tests
Section intitulée « Partie 1 : le problème de Grace sous forme de tests »Comme dans Reproduire d’abord, les preuves viennent avant le changement. Ajoutez import pytest aux importations de tests/test_schema.py, puis ce test à la fin :
@pytest.mark.parametrize( "page_url", ["https://larkfield.example#help", "https://café.larkfield.example/help"],)def test_page_addresses_from_the_web_form_are_accepted(page_url): accepted, rejected = check(page_url=page_url) assert rejected == [] assert accepted[0].page_url == page_urlGrace s’attend aussi à ce que les nombres pour le fichier complet changent. Dans tests/test_cli.py, modifiez trois valeurs attendues :
- la sortie :
12 submissions: 5 accepted, 7 rejected.(12 soumissions : 5 acceptées, 7 rejetées) - la liste des soumissions acceptées :
["T-4001", "T-4002", "T-4007", "T-4011", "T-4012"] - le nombre de soumissions rejetées :
7
Exécutez ensuite les tests :
python -m pytest -qFAILED tests/test_cli.py::test_cli_writes_accepted_and_rejected - AssertionEr...FAILED tests/test_schema.py::test_page_addresses_from_the_web_form_are_accepted[https://larkfield.example#help]FAILED tests/test_schema.py::test_page_addresses_from_the_web_form_are_accepted[https://caf\xe9.larkfield.example/help]3 failed, 12 passed, 22 warnings in 0.04sTrois tests échouent pour la bonne raison : 'page_url': ['Not a valid URL.'] (URL non valide). Consignez-les avec git commit -am "Describe Grace's page addresses as tests". Ces tests définissent maintenant ce que signifie « terminé ». Personne ne doit les modifier pour faire réussir une mise à jour.
Partie 2 : lire avant l’installation
Section intitulée « Partie 2 : lire avant l’installation »Les avertissements
Section intitulée « Les avertissements »Les 20 avertissements de la première exécution sont la note de l’ancienne édition. Listez chaque avertissement différent :
python -m pytest -q 2>&1 | grep -E 'Warning:' | sed -e 's/^ *//' | sort | uniq -cpython -m pytest -q 2>&1 | Select-String 'Warning:' | Sort-Object -Uniquepython -m pytest -q 2>&1 | grep -E 'Warning:' | sed -e 's/^ *//' | sort | uniq -c 1 fields.py:1753: RemovedInMarshmallow4Warning: The 'missing' argument to fields is deprecated. Use 'load_default' instead. 1 fields.py:276: ChangedInMarshmallow4Warning: Returning `False` from a validator is deprecated. Raise a `ValidationError` instead. 1 fields.py:986: RemovedInMarshmallow4Warning: The 'missing' argument to fields is deprecated. Use 'load_default' instead. 1 schema.py:129: RemovedInMarshmallow4Warning: The `ordered` `class Meta` option is deprecated. Field order is already preserved by default. Set `Schema.dict_class` to OrderedDict to maintain the previous behavior. 1 ~/projects/upgrade-case-study/form-intake/form_intake/cli.py:28: DeprecationWarning: The '__version__' attribute is deprecated and will be removed in in a future version. Use feature detection or 'importlib.metadata.version("marshmallow")' instead. 1 ~/projects/upgrade-case-study/form-intake/form_intake/schema.py:46: RemovedInMarshmallow4Warning: The 'missing' argument to fields is deprecated. Use 'load_default' instead. 1 ~/projects/upgrade-case-study/form-intake/form_intake/schema.py:64: RemovedInMarshmallow4Warning: The `context` parameter is deprecated and will be removed in marshmallow 4.0. Use `contextvars.ContextVar` to pass context instead.Les noms des avertissements le disent : RemovedInMarshmallow4 (supprimé dans marshmallow 4), ChangedInMarshmallow4 (modifié dans marshmallow 4). Vous pouvez aussi demander à Python de traiter ces avertissements comme des erreurs. Vous voyez alors le premier échec de la version 4 avant son installation :
python -m pytest -q -W error::DeprecationWarningE marshmallow.warnings.RemovedInMarshmallow4Warning: The 'missing' argument to fields is deprecated. Use 'load_default' instead.!!!!!!!!!!!!!!!!!!! Interrupted: 2 errors during collection !!!!!!!!!!!!!!!!!!!!Le journal des modifications
Section intitulée « Le journal des modifications »Ouvrez maintenant la section 4.0.0 du journal des modifications de marshmallow et le guide de mise à jour. Le journal est long, et la plupart des entrées ne touchent pas form-intake. Cherchez le nom de chaque entrée dans le projet. Dans VS Code, utilisez Edit > Find in Files (édition, rechercher dans les fichiers), par exemple missing= ou context. Gardez seulement les entrées qui correspondent à une ligne de votre code. Notez ensuite l’effet que vous attendez de chacune :
Description textuelle du diagramme
Huit lignes. Quatre entrées arrêtent le programme avec une erreur : missing, data_key, context et __version__. Trois changent son comportement sans erreur : un validateur qui renvoie False, l’option ordered et une date sans heure. La dernière ligne est le changement dont Grace a besoin.
Voici la citation la plus importante pour ce projet, tirée du journal des modifications de 4.0.0 :
Backwards-incompatible : utiliser
datetime.date.fromisoformat,datetime.time.fromisoformatetdatetime.datetime.fromisoformatde la bibliothèque standard pour désérialiser les dates, les heures et les dates-heures. Conséquences de ce changement : les heures avec un décalage horaire sont maintenant prises en charge. YYYY-MM-DD est maintenant accepté comme date-heure et désérialisé à minuit (00:00), sans fuseau horaire.
form-intake possède un test pour cela précisément : test_date_without_time_is_rejected. Mais un journal des modifications liste les conséquences que ses auteurs ont remarquées. Il ne peut pas lister toutes les entrées que votre programme reçoit. C’est la raison de la partie 3.
Partie 3 : sauvegarder le comportement actuel
Section intitulée « Partie 3 : sauvegarder le comportement actuel »Dans Préparer le dépôt, la référence de base était l’état connu avant un changement. Les tests fixent les règles que quelqu’un a écrites. Mais un programme prend aussi des décisions qu’aucun test ne décrit, et une mise à jour peut les modifier. Conservez donc une deuxième référence de base : les décisions actuelles, sur plus d’entrées que les tests n’en couvrent.
data/time-formats.json contient une soumission pour chacune des 10 façons d’écrire une heure. Le formulaire envoie seulement la première. Les autres forment une sonde : des entrées choisies pour découvrir ce que fait le code. Exécutez la sonde et les 12 soumissions avec 3.26.2, puis conservez les résultats :
python -m form_intake data/time-formats.json --output-dir out/before/time-formatspython -m form_intake data/submissions.json --output-dir out/before/submissions10 submissions: 4 accepted, 6 rejected.Saved: out/before/time-formats/accepted.json, out/before/time-formats/rejected.json12 submissions: 3 accepted, 9 rejected.Saved: out/before/submissions/accepted.json, out/before/submissions/rejected.json| Soumission | submitted_at |
3.26.2 |
|---|---|---|
| T-5001 | 2026-10-09T08:12:00 (ce que le formulaire envoie) |
acceptée |
| T-5002 | 2026-10-09 08:12:00 |
acceptée |
| T-5003 | 2026-10-09T08:12 |
acceptée |
| T-5004 | 2026-10-09 |
rejetée |
| T-5005 | 2026-10-09T08 |
rejetée |
| T-5006 | 20261009T081200 |
rejetée |
| T-5007 | 2026-W41-5T08:12 (une date par semaine) |
rejetée |
| T-5008 | 2026-10-09T08:12:00,5 |
rejetée |
| T-5009 | 2026-10-09T0812 |
rejetée |
| T-5010 | 2026-1-9T8:05 |
acceptée |
out/ figure dans .gitignore. Ces résultats restent donc sur votre ordinateur et ne font pas partie des commits.
Partie 4 : la nouvelle version, sur une branche
Section intitulée « Partie 4 : la nouvelle version, sur une branche »-
Créez une branche pour la mise à jour :
Fenêtre de terminal git switch -c upgrade/marshmallow-4 -
Dans
requirements.txtetrequirements-lock.txt, remplacezmarshmallow==3.26.2parmarshmallow==4.3.1. Rien d’autre ne change dans le fichier de verrouillage : avec Python 3.11 et les versions suivantes, 4.3.1 n’exige aucun autre paquet. -
Installez les dépendances à partir du fichier de verrouillage :
Fenêtre de terminal python -m pip install -r requirements-lock.txtSortie (extrait) Installing collected packages: marshmallowAttempting uninstall: marshmallowFound existing installation: marshmallow 3.26.2Uninstalling marshmallow-3.26.2:Successfully uninstalled marshmallow-3.26.2Successfully installed marshmallow-4.3.1 -
Exécutez les tests et le programme :
Fenêtre de terminal python -m pytest -qpython -m form_intake --versionOutput (end of each) E TypeError: Field.__init__() got an unexpected keyword argument 'missing'...!!!!!!!!!!!!!!!!!!! Interrupted: 2 errors during collection !!!!!!!!!!!!!!!!!!!!2 errors in 0.07scategory = fields.Str(missing="other", validate=validate.OneOf(CATEGORIES))TypeError: Field.__init__() got an unexpected keyword argument 'missing'
C’est la référence de base de la mise à jour : la nouvelle version sans changement de code. Vous l’avez prédite à la partie 2. Remarquez ce qu’elle ne montre pas. Python s’arrête à la première erreur au chargement d’un module. Cette erreur cache donc les trois autres erreurs visibles, et les changements silencieux ne peuvent pas apparaître du tout.
Partie 5 : demander à l’assistant
Section intitulée « Partie 5 : demander à l’assistant »Une migration convient bien à un assistant : elle comporte de nombreux petits changements décrits dans le journal des modifications. Délimitez la tâche, comme dans Problème et critères d’acceptation. Fournissez les changements, les preuves, les fichiers qu’il peut modifier et les règles. Amira a envoyé cette requête (prompt) à Aider, un assistant à code source ouvert utilisé dans un terminal. Elle a utilisé le plus grand modèle du cours :
We are upgrading marshmallow from 3.26.2 to 4.3.1 (a new major version). requirements.txt andrequirements-lock.txt already say 4.3.1, and it is installed. Now the tests fail:
```E TypeError: Field.__init__() got an unexpected keyword argument 'missing'...2 errors in 0.06s```
Task: change form_intake/schema.py and form_intake/cli.py so that the project works with marshmallow 4.3.1.
Rules:- Do not change the tests or the requirements files. The tests describe the behaviour that we want. The two tests of the page addresses failed with 3.26.2 on purpose: 4.3.1 should make them pass.- Keep every other behaviour the same.- Do not add a dependency.- For each change, name the change in marshmallow 4 that makes it necessary.La dernière règle compte le plus : elle demande une raison que vous pouvez vérifier. L’assistant pouvait modifier schema.py et cli.py. Il pouvait seulement lire les tests et requirements.txt, et exécuter les tests. Toute la session se trouve dans assistant-session/upgrade-marshmallow-4.md, avec la requête et la réponse exactes.
Résultat : un appel au modèle, environ 24 secondes, 4 664 jetons (tokens) en entrée et 1 529 en sortie. Cela représente environ 0,025 $ US au tarif payé par l’équipe du cours. Les prix changent, et la lecture de la transcription ne vous coûte rien. L’assistant n’a vu que la première erreur. Pourtant, il a modifié les sept endroits, dans six sections numérotées, chacune avec une raison. En voici deux :
### 1. Validators must raise `ValidationError`
Marshmallow 4 no longer treats a validator returning `False` as a validation failure. Keep the previous default error message.
### 2. Preserve the requirement for a time component
Marshmallow 4 uses `datetime.fromisoformat`, which also accepts date-only strings. Add a datetime field that retains the requirement for a date/time separator.Aider a ensuite exécuté les tests : 15 passed (15 tests réussis). Appliquez le même changement à votre projet, puis vérifiez-le :
git apply ../assistant-session/upgrade-marshmallow-4.patchgit diff --stat -- form_intakepython -m pytest -qpython -m pytest -q -W errorruff check .ruff format --check . form_intake/cli.py | 5 ++--- form_intake/schema.py | 37 +++++++++++++++++++++++++------------ 2 files changed, 27 insertions(+), 15 deletions(-)............... [100%]15 passed in 0.04s............... [100%]15 passed in 0.04sAll checks passed!9 files already formattedTous les tests réussissent, même en traitant les avertissements comme des erreurs, et ruff ne signale aucun problème. Tomás : « Fusionnez. » Pas encore. Les tests ont été écrits pour 3.26.2. Ils vérifient seulement ce que quelqu’un a pensé à consigner.
Partie 6 : vérifier chaque changement dans le journal des modifications
Section intitulée « Partie 6 : vérifier chaque changement dans le journal des modifications »Ouvrez les différences avec git diff, ou dans la vue Source Control (contrôle de code source) de VS Code. Examinez un changement à la fois, comme dans Examiner les différences. Posez deux questions pour chacun. Sa raison correspond-elle à une vraie entrée du journal des modifications? Préserve-t-il le comportement demandé par l’objectif?
Description textuelle du diagramme
Sept lignes, une par changement. Les sept raisons correspondent à de vraies entrées du journal des modifications. Dans cet enregistrement, l’assistant n’a inventé aucune API ni aucune entrée. Cinq changements sont acceptés tels quels. Un autre, le contexte, est accepté avec une raison consignée. Le dernier, la vérification de la date, réussit son test, mais échoue à la comparaison avec 3.26.2.
Deux changements exigent une décision
Section intitulée « Deux changements exigent une décision »Le contexte. marshmallow 4 a supprimé Schema(context=...). Le journal des modifications et le guide suggèrent contextvars de Python, ou la nouvelle classe Context de marshmallow, qu’ils qualifient d’expérimentale. L’assistant a fait autre chose : il a donné au schéma un argument de constructeur, SubmissionSchema(now=now). C’est du Python ordinaire, facile à tester, qui évite une API expérimentale. Acceptez ce choix et consignez la raison à la partie 8. Un réviseur qui compare seulement les différences au guide dirait que c’est incorrect. C’est un choix.
La vérification de la date. La raison est juste : marshmallow 4 accepte une date seule. Mais « tous les autres comportements restent-ils les mêmes »? Comparez les décisions à celles que vous avez sauvegardées à la partie 3 :
python -m form_intake data/time-formats.json --output-dir out/after/time-formatspython tools/compare.py out/before/time-formats out/after/time-formats10 submissions: 8 accepted, 2 rejected.Saved: out/after/time-formats/accepted.json, out/after/time-formats/rejected.jsonSame decision: 4Accepted before, rejected now: T-5010Rejected before, accepted now: T-5005, T-5006, T-5007, T-5008, T-5009Six des dix décisions ont changé. La vérification de l’assistant bloque une date seule : le seul cas nommé dans le journal des modifications et vérifié par le test. Mais datetime.fromisoformat accepte plus de formats que marshmallow 3. Il accepte une heure sans minutes (2026-10-09T08), l’absence de traits d’union (20261009T081200), une date de semaine, une virgule et l’absence de deux-points. Il refuse aussi les mois et les heures à un chiffre (2026-1-9T8:05), que 3.26.2 acceptait.
L’assistant s’est-il trompé? Il a fait ce que les preuves fournies demandaient : les tests réussissent. Le comportement qui a changé n’était consigné nulle part. Ni les tests ni l’assistant ne pouvaient donc le voir. Votre référence de base sauvegardée le pouvait.
Partie 7 : le changement révisé
Section intitulée « Partie 7 : le changement révisé »La règle de Larkfield pour l’heure se trouve dans le README : une date et une heure. Écrivez donc cette règle dans le code, au lieu de laisser la bibliothèque en décider. Dans form_intake/schema.py, ajoutez import re en haut, puis modifiez le SubmissionDateTime de l’assistant :
# Our rule for submitted_at: a date and a local time, as the form sends them.# marshmallow 4 reads times with datetime.fromisoformat, which also accepts a# date alone and other ISO 8601 forms (changelog, 4.0.0). So the rule is ours.LOCAL_TIME = re.compile(r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?")
class SubmissionDateTime(fields.DateTime): """Require a time component as well as a date.""" """A date and a local time: YYYY-MM-DD, T or a space, HH:MM, seconds if any."""
def _deserialize(self, value, attr, data, **kwargs): if isinstance(value, str) and "T" not in value and " " not in value: if not isinstance(value, str) or not LOCAL_TIME.fullmatch(value): raise self.make_error("invalid", input=value, obj_type=self.OBJ_TYPE) return super()._deserialize(value, attr, data, **kwargs)Le motif se lit ainsi : quatre chiffres, deux, deux, puis T ou une espace, puis les heures et les minutes. Les secondes suivent si elles sont présentes. Le guide de marshmallow utilise lui aussi un champ personnalisé qui modifie _deserialize.
Fixez ensuite chaque format avec un test, pour que la prochaine mise à jour ne puisse pas le changer sans faire échouer un test. Ajoutez ceci à tests/test_schema.py :
@pytest.mark.parametrize( "submitted_at", ["2026-10-09T08:12:00", "2026-10-09 08:12:00", "2026-10-09T08:12"],)def test_date_and_local_time_are_accepted(submitted_at): accepted, _ = check(submitted_at=submitted_at) assert accepted[0].submitted_at == datetime(2026, 10, 9, 8, 12)
@pytest.mark.parametrize( "submitted_at", [ "2026-10-09", # a date alone: marshmallow 4 accepts it "2026-10-09T08", # the hour alone: marshmallow 4 accepts it "20261009T081200", # ISO 8601 without hyphens: marshmallow 4 accepts it "2026-W41-5T08:12", # a week date: marshmallow 4 accepts it "2026-10-09T08:12:00+02:00", # a time zone: 3.26.2 crashed on it "2026-1-9T8:05", # one-digit parts: 3.26.2 accepted them ],)def test_other_time_formats_are_rejected(submitted_at): assert problems(submitted_at=submitted_at) == { "submitted_at": ["Not a valid datetime."] }Exécutez tout de nouveau, puis comparez les deux entrées à la référence de base :
python -m pytest -q -W errorruff check .ruff format --check .python -m form_intake data/time-formats.json --output-dir out/after/time-formatspython tools/compare.py out/before/time-formats out/after/time-formatspython -m form_intake data/submissions.json --output-dir out/after/submissionspython tools/compare.py out/before/submissions out/after/submissions........................ [100%]24 passed in 0.05sAll checks passed!9 files already formatted10 submissions: 3 accepted, 7 rejected.Same decision: 9Accepted before, rejected now: T-5010Rejected before, accepted now: none12 submissions: 5 accepted, 7 rejected.Same decision: 10Accepted before, rejected now: noneRejected before, accepted now: T-4007, T-4011Ce que cela nous apprend. Sur les 22 décisions sauvegardées, trois ont changé, chacune volontairement. T-4007 et T-4011 sont les deux soumissions de Grace. T-5010, 2026-1-9T8:05, est maintenant rejetée, car la règle de Larkfield exige deux chiffres; le formulaire n’en envoie jamais un seul. C’est un choix, donc il doit figurer dans DECISIONS.md.
La comparaison équitable
Section intitulée « La comparaison équitable »Quatre versions de form-intake ont été exécutées, chacune dans un nouveau dossier, avec un nouvel environnement créé à partir de son propre fichier de verrouillage. Les quatre ont reçu les mêmes entrées : les 12 soumissions et les 10 formats d’heure. Une mesure : combien des 22 décisions diffèrent de la règle écrite de Larkfield. La règle correspond au tableau du README, entrée par entrée : les deux pages de Grace acceptées, une date et une heure avec des parties à deux chiffres, etc.
| Version | marshmallow | Tests | Le programme fonctionne-t-il? | Décisions qui diffèrent de la règle |
|---|---|---|---|---|
| A. Rester sur 3.26.2 | 3.26.2 | 3 failed, 12 passed, 22 warnings | oui | 3 : les deux de Grace et T-5010 |
| B. Changer seulement le numéro | 4.3.1 | 2 errors | non : TypeError |
– |
| C. Le changement de l’assistant | 4.3.1 | 15 passed | oui | 5 : T-5005 à T-5009 |
| D. Le changement révisé | 4.3.1 | 24 passed | oui | 0 |
Description textuelle du graphique
Sur 22 décisions, rester sur 3.26.2 diffère de la règle pour 3. Le changement de l’assistant diffère pour 5, et le changement révisé pour 0. Changer seulement le numéro de version ne donne aucune décision : le programme ne démarre pas.
Ce que cela nous apprend.
- Rester préserve les formats d’heure, mais ne règle pas le problème de Grace. Ses deux clients restent rejetés, et les avertissements demeurent.
- Changer seulement le numéro est la pire option. Rien ne fonctionne, et la première erreur cache les autres.
- Le changement de l’assistant corrige tout ce que les tests décrivent, avec de vraies raisons tirées du journal des modifications. Pourtant, il prend cinq décisions que personne n’a choisies. « Tous les tests réussissent » était vrai, mais insuffisant.
- Le changement révisé atteint l’objectif. Soyez honnête sur la raison de son score de zéro : sa règle d’heure est la règle écrite, transposée en code. La mesure montre que le code fait maintenant ce que dit le README, pour ces 22 entrées. Elle ne peut pas montrer ce que le formulaire pourrait envoyer un jour.
Recommandation : la version D. Elle conserve les six changements corrects de l’assistant et en remplace un. Chaque changement correspond à une entrée du journal des modifications. Trois décisions ont changé volontairement, et chacune est consignée.
Partie 8 : fixer la version et consigner
Section intitulée « Partie 8 : fixer la version et consigner »Les deux fichiers de dépendances fixent déjà marshmallow==4.3.1, et rien d’autre n’y a changé. Écrivez maintenant la décision. Copiez la décision 2 du fichier DECISIONS.md du projet terminé, ou rédigez la vôtre avec les mêmes parties. Voici le début :
## 2. Upgrade marshmallow from 3.26.2 to 4.3.1
**Why.** Grace's team saw two real submissions rejected with "Not a validURL.": `https://larkfield.example#help` and`https://café.larkfield.example/help`. Both are fixed in marshmallow 4(changelog: 4.2.4, "`URL` and `Email` accept Internationalized Domain Names";4.3.1, "`URL` accepts a fragment that follows an empty path"). The 3.x linehas had no release since 3.26.2.Vient ensuite un tableau : chaque changement de notre code, à côté de son entrée du journal des modifications. Puis les vérifications effectuées : 24 tests, aucun avertissement, les deux comparaisons. Ensuite, ce qui a été modifié ou écarté : la vérification de la date, le Context expérimental. Enfin, le plantage lié au fuseau horaire découvert pendant la mise à jour. Dans README.md, inscrivez la règle d’heure dans le tableau des règles. Créez ensuite un commit (enregistrement des changements) :
git add -Agit commit -m "Upgrade marshmallow to 4.3.1"git diff --stat main DECISIONS.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++- README.md | 8 +++++--- form_intake/cli.py | 5 ++--- form_intake/schema.py | 44 ++++++++++++++++++++++++++++++++------------ requirements-lock.txt | 2 +- requirements.txt | 2 +- tests/test_schema.py | 26 ++++++++++++++++++++++++++ 7 files changed, 114 insertions(+), 21 deletions(-)Un seul commit contient toute la mise à jour : la version fixée, le code, les tests et la documentation. Si l’équipe doit un jour l’annuler, git revert annule tout en une seule fois.
Erreur courante
Le code est passé à la version 4, mais pas la version fixée
Symptôme : un collègue a exécuté python -m pip install --upgrade marshmallow dans son propre environnement. Il a créé un commit avec le nouveau code, et python -m pytest a affiché 24 passed (24 tests réussis) chez lui. Kwame crée un nouvel environnement à partir du fichier de verrouillage et obtient :
FAILED tests/test_cli.py::test_cli_writes_accepted_and_rejected - AssertionEr...FAILED tests/test_schema.py::test_page_addresses_from_the_web_form_are_accepted[https://larkfield.example#help]FAILED tests/test_schema.py::test_page_addresses_from_the_web_form_are_accepted[https://caf\xe9.larkfield.example/help]3 failed, 21 passed in 0.03sCause : pip install --upgrade a modifié un ordinateur, pas le projet. Les deux fichiers de dépendances indiquent encore marshmallow==3.26.2. Chaque nouvel environnement installe donc l’ancienne version. Le nouveau code fonctionne avec elle, mais rejette de nouveau les adresses de Grace.
Correction : une mise à jour modifie les fichiers de dépendances, dans le même commit que le code. Modifiez le fichier de verrouillage, puis installez les dépendances à partir de celui-ci, jamais avec --upgrade. Le nouvel environnement de Kwame sert de vérification : ses tests doivent aussi réussir.
Partie 9 : nouvelles entrées, de bout en bout
Section intitulée « Partie 9 : nouvelles entrées, de bout en bout »data/new-submissions.json contient 10 soumissions qu’aucune étape n’a encore utilisées. Prédisez d’abord chaque décision sur papier, à partir des règles du README. Exécutez ensuite le programme :
python -m form_intake data/new-submissions.json10 submissions: 5 accepted, 5 rejected.Saved: out/accepted.json, out/rejected.jsonAfficher chaque décision
| Soumission | Particularité | Décision |
|---|---|---|
| T-4013 | une adresse de page normale | acceptée |
| T-4014 | https://larkfield.example#contact |
acceptée : la correction de 4.3.1 |
| T-4015 | https://müller.larkfield.example/help |
acceptée : la correction de 4.2.4 |
| T-4016 | un sujet vide | rejetée : subject « Invalid value. » (valeur invalide) |
| T-4017 | quinn.example.com |
rejetée : « Not a valid email address. » (adresse courriel invalide) |
| T-4018 | aucune catégorie, priorité ou page | acceptée : other (autre), 2, aucune page |
| T-4019 | 2026-10-10, une date seule |
rejetée : « Not a valid datetime. » (date-heure invalide) |
| T-4020 | priorité "high" |
rejetée : « Not a valid integer. » (nombre entier invalide) |
| T-4021 | une adresse de page normale | acceptée |
| T-4022 | l’année 2062 | rejetée : « The time is in the future. » (l’heure est dans le futur) |
Si votre prédiction diffère de la sortie, trouvez ce qui est incorrect : la règle du README, votre interprétation ou le code. T-4016 et T-4019 testent deux des changements silencieux de la partie 2. Avec 4.3.1 et l’ancien validateur ou le champ DateTime ordinaire, les deux seraient acceptées.
Constats et limites
Section intitulée « Constats et limites »- Lisez avant d’installer. Les 20 avertissements et le journal des modifications de 4.0.0 annonçaient toutes les erreurs visibles. Lors de l’exécution après la mise à jour, une seule est apparue.
- Les changements silencieux demandent le vrai travail. Quatre incompatibilités ont arrêté le programme, et trois ne l’ont pas arrêté. Deux des changements silencieux avaient un test, et
orderedest sans danger. Mais le changement d’heure dépassait son entrée du journal des modifications. Seule la référence de base sauvegardée a révélé le reste. - L’assistant avait raison sur le journal des modifications. Dans cet enregistrement, les sept raisons correspondaient à de vraies entrées. Il a trouvé les incompatibilités cachées à partir d’un message d’erreur et du code. Son seul changement faible suivait les seules preuves dont il disposait. Une autre exécution, un autre modèle ou un autre assistant peut faire mieux ou moins bien : vérifiez chaque fois.
- Limites. Un paquet, une mise à jour, une session enregistrée. L’essai comporte 10 formats d’heure, pas toutes les entrées qu’un formulaire Web peut envoyer. Testé sur macOS seulement.
Utilisation responsable
Section intitulée « Utilisation responsable »- Installez ce que vous avez vérifié. Installez les dépendances à partir du fichier de verrouillage, avec des versions exactes. Lisez la page de la version sur pypi.org avant de lui faire confiance : qui l’a publiée, quand et sous quelle licence.
- Gardez l’assistant dans les limites de la tâche. La requête autorisait deux fichiers, et aucun changement aux tests ou aux dépendances. Un assistant qui modifie les tests jusqu’à leur réussite a supprimé les preuves.
- Envoyez le moins de données possible. La requête contenait des sorties de tests et du code, mais aucune donnée de client. Ne collez jamais de vraies soumissions dans un assistant. Utilisez des soumissions inventées, comme ici.
- Nommez la licence de la dépendance dans la documentation. Une nouvelle version MAJOR (majeure) peut la changer. marshmallow 4.3.1 utilise toujours la licence MIT.
- Dites ce que l’assistant a fait. Le document de décision indique la session enregistrée et le changement que l’équipe y a apporté.
En faire un projet de portfolio
Section intitulée « En faire un projet de portfolio »Chaque équipe doit mettre à jour ses dépendances, et personne ne voit ce travail quand tout se passe bien. Ce projet montre que vous pouvez le faire avec soin. Vous lisez d’abord, sauvegardez le comportement, utilisez un assistant et révisez son travail à partir de preuves.
Quoi mettre dans le dépôt :
form-intake/ README.md what it does, how to run and check it, the rules DECISIONS.md decision 2: why, each change and its changelog entry, the checks, what you changed LICENSE MIT form_intake/ the schema and the command tests/ 24 tests, among them the time formats data/ the three invented input files tools/ compare.py assistant/ the transcript and the patch, with a note on what you kept- Créez un nouveau dépôt à partir du dossier de votre projet, avec son historique :
Start(début), les tests de Grace et la mise à jour. Envoyez-le sur GitHub si vous avez un compte; ce n’est pas obligatoire. - Dans le README, ajoutez une courte section, La mise à jour vers marshmallow 4. Fournissez le tableau comparatif des quatre versions et un lien vers
DECISIONS.md. - Vérifiez qu’un nouveau clone avec un nouvel environnement créé à partir du fichier de verrouillage affiche
24 passed, comme celui de Kwame.
L’autre étude de cas de ce cours est Corriger un bogue dans un code inconnu.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Après la modification de l'assistant, les 15 tests réussissaient, même avec les avertissements traités comme des erreurs. Pourquoi ne pas fusionner?
Afficher la réponse
Les tests vérifient seulement les règles écrites pour 3.26.2. marshmallow 4 lit les heures avec datetime.fromisoformat. Il accepte des formes que 3.26.2 rejetait, et aucun test ne les couvrait. Les décisions enregistrées à la partie 3 montraient que 6 des 10 formats d’heure avaient changé de décision. « Les tests réussissent » signifie que les règles écrites sont respectées. Cela ne signifie pas que rien d’autre n’a changé.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Avec 4.3.1 et sans modification du code, pytest n'affichait qu'une erreur : « missing ». Combien de ruptures le projet avait-il vraiment, et comment le savoir avant la mise à jour?
Afficher la réponse
Sept : missing (dans trois champs), le validateur qui renvoie False, l’argument data_key, context, ordered, __version__ et le format d’heure. Python s’arrête à la première erreur lors du chargement d’un module. Une erreur cache donc les autres, et les ruptures silencieuses ne produisent aucune erreur. Trois sources permettaient de le savoir avant la mise à jour. Les 20 avertissements de 3.26.2 en nommaient la plupart. pytest -W error::DeprecationWarning montrait la première erreur. Et le journal des modifications de 4.0.0, mis en relation avec le code, les énumérait toutes.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Le journal des modifications suggère contextvars ou la classe expérimentale Context pour remplacer Schema(context=...). L'assistant a plutôt utilisé un argument du constructeur. Est-ce une mauvaise modification?
Afficher la réponse
Non. Le journal des modifications indique ce qui a été supprimé et propose une façon de le remplacer. Il n’interdit pas les autres. SubmissionSchema(now=now) est du Python ordinaire. Il conserve le comportement (tous les tests réussissent) et évite une API que le journal des modifications qualifie lui-même d’expérimentale. C’est un choix, donc on le consigne dans DECISIONS.md avec sa raison. Une révision vérifie qu’une modification est correcte et expliquée, pas qu’elle copie le guide.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Une nouvelle version majeure peut supprimer ou modifier des éléments. Lisez le journal des modifications et les avertissements avant l’installation.
- Exprimez d’abord le problème de l’utilisateur sous forme de tests. Enregistrez les décisions actuelles pour plus d’entrées que les tests n’en couvrent.
- Faites la mise à jour sur une branche, dans les deux fichiers de dépendances, puis installez à partir du fichier de verrouillage.
- Donnez une tâche bien délimitée à l’assistant et demandez une raison pour chaque modification. Dans cet enregistrement, les sept raisons correspondaient au journal des modifications.
- Vérifiez chaque modification selon le journal des modifications et les décisions enregistrées. La version de l’assistant réussissait tous les tests, mais changeait quand même six décisions. La version révisée en changeait trois, chacune volontairement.
- Fixez les versions, consignez la mise à jour et enregistrez-la dans un seul commit (enregistrement des modifications).
Ensuite, le travail final : ajoutez une fonctionnalité et corrigez un défaut dans un petit projet Python, avec les preuves enseignées dans ce cours.
Leçon suivante : Travail final