Quand utiliser ce workflow

Utilisez ce workflow lorsque le périmètre de la migration est bien défini et que des tests permettent de comparer le comportement avant et après la migration. Fournissez à Codex les consignes de migration, le module et le code qui l’appelle, des jeux de données de test figés pour vérifier le contrat, ainsi qu’un environnement cloud prêt à l’emploi. Demandez-lui une modification ciblée, accompagnée des résultats de vérification et d’une procédure de retour en arrière.

L’exemple fait passer un seul modèle de validation d’un service de gestion des commandes de Pydantic v1 à la v2. Il comprend l’implémentation d’origine, une étape de préparation qui assure la compatibilité et le module final. Les tests couvrent le routeur FastAPI utilisé par le service, le gestionnaire d’erreurs, la sérialisation des réponses, la route voisine restée en v1 et le document OpenAPI public. L’exemple ne comprend ni migration de base de données ni déploiement.

Préparez l’environnement cloud

1. Choisissez Travailler dans > Cloud, puis sélectionnez un environnement publié.

2. Pour en créer un, sélectionnez Créer un environnement, choisissez les dépôts GitHub et demandez à Codex de préparer l’environnement d’exécution, les dépendances et les services de test isolés.

3. Consultez le rapport de configuration, corrigez les problèmes signalés par les vérifications, puis sélectionnez Publier avant de lancer une nouvelle tâche.

• Suivez le guide des environnements cloud.
• Consignez les instructions propres au dépôt dans AGENTS.md.

Si les dépendances ou la configuration des services changent, modifiez l’environnement réutilisable, testez-le, puis sélectionnez Republier.

Validez l’environnement mis à jour dans une nouvelle tâche. L’actualisation du dépôt conserve les caches de dépendances sans relancer les commandes d’installation ou de démarrage. Les tâches existantes conservent leur propre état.

Configurez séparément les destinations réseau et les identifiants nécessaires.

À chaque étape, consignez la référence de l’environnement et de sa configuration, le commit du code source, la version de Python jusqu’au numéro de correctif, les versions du framework et des dépendances, la version du gestionnaire de paquets et l’empreinte du fichier de verrouillage. Vérifiez ces versions dans la nouvelle tâche avant d’en utiliser les résultats.

Exécutez l’exemple

Téléchargez l’exemple complet de migration. Il comprend trois projets uv autonomes, leurs fichiers uv.lock avec les versions résolues, les implémentations de l’application, un adaptateur commun pour les erreurs et le schéma, des jeux de test HTTP figés et le script de vérification du contrat.

Utilisez Python 3.11, 3.12 ou 3.13 et installez uv, puis exécutez les commandes suivantes :

unzip sample.zip
cd migrate-a-validation-module
uv run --project support/target --python python3 --frozen python run.py --compare-stages --output evidence

Le script de comparaison crée un .venv distinct pour chaque étape et installe les dépendances avec uv sync --frozen. Toutes les étapes utilisent l’interpréteur Python qui a lancé le script et les mêmes jeux de test pour HTTP et le schéma. Les versions des dépendances restent verrouillées.

Python 3.14 et les versions ultérieures sont exclus, car la couche de compatibilité avec Pydantic v1 ne les prend pas en charge. Si l’exécution réussit, elle se termine par :

PASS: legacy, prepared, target HTTP/schema/serialization contracts match
Native model schemas differ; the existing public schema adapter is preserved.

Consultez evidence/legacy.json, prepared.json, target.json et summary.json. Ces fichiers contiennent les réponses observées, les versions de l’environnement d’exécution, les empreintes du code source, des jeux de test et des fichiers de verrouillage, les commandes, les codes de sortie et les chemins des journaux bruts.

Le script teste les points de terminaison HTTP de l’application d’exemple via FastAPI et son TestClient, dans le même processus. Exécutez-le dans la tâche dans le cloud de votre choix et conservez les résultats de vérification de cette tâche.

Exécutez python3 run.py sans --compare-stages uniquement pour vérifier le modèle cible dans un environnement où Pydantic v2 est installé. Ce mode autonome vérifie sept cas de validation et de sérialisation. Il ne teste pas les échanges HTTP et ne compare pas les résultats entre les étapes. Pour vérifier une migration, utilisez la commande de comparaison complète ci-dessus.

La comparaison complète vérifie 23 cas HTTP à chaque étape, ainsi que le document OpenAPI public et la sérialisation des réponses. Elle a réussi en local avec Python 3.11, 3.12 et 3.13. Le fichier README.md de l’archive indique les versions testées et l’historique des exécutions. Exécutez la comparaison actuelle dans votre environnement cloud pour y consigner les résultats.

Distinguez les trois configurations de dépendances

Les versions préparée et cible ont des fichiers de verrouillage des dépendances identiques. La migration du module modifie le modèle et la méthode qui le sérialise directement, sans changer les dépendances de l’environnement.

L’étape de préparation fait l’objet d’une modification distincte, soumise à une revue de code. Elle adapte aussi les routes qui restent en v1 : avant la validation de la réponse, leurs adaptateurs produisent avec dict(by_alias=True) des dictionnaires dont les clés sont les alias. Renvoyer directement le modèle v1 dans un environnement v2 risque de faire disparaître les alias publics.

Dans la version cible, l’adaptateur des commandes utilise model_dump(by_alias=True), et la route voisine en v1 conserve l’adaptateur introduit lors de la préparation.

Le guide de migration de FastAPI précise que seules les versions 0.119.0 à 0.127.x prennent temporairement en charge la coexistence de routes v1 et v2. La version 0.128.0 a supprimé cette prise en charge.

Cet exemple fixe délibérément la version à 0.119.0 pour illustrer cette transition. Pour une application FastAPI plus récente, utilisez exclusivement la v2 dans le périmètre de la migration. Désignez un responsable de la couche de compatibilité temporaire et précisez à quelle condition elle devra être supprimée. N’imbriquez pas de modèles v1 et v2. Cette couche de compatibilité ne permet pas de migrer vers Python 3.14.

Examinez les tests de contrat

Les cas HTTP figés couvrent les requêtes valides, les notes omises ou explicitement définies à null, les identifiants absents ou invalides, la présence de plusieurs champs inconnus, les combinaisons d’erreurs de champs, les notes invalides, le JSON mal formé, les types de contenu incorrects, l’absence de corps de requête, les alias, les corps de requête de type tableau ou chaîne, ainsi que la route voisine restée en v1. Les tests comparent les codes de statut, l’en-tête Content-Type et l’intégralité des réponses JSON après analyse, sans supprimer de champs d’erreur ni modifier les types attendus.

Depuis la version d’origine, l’application définit elle-même le format de ses réponses d’erreur et son document OpenAPI public. Les adaptateurs d’erreurs et de schéma restent en place. La version cible conserve l’ordre des erreurs d’origine : d’abord les erreurs portant sur les champs déclarés, puis les clés inconnues par ordre alphabétique.

Les tests comparent le tableau error.fields dans son intégralité et dans l’ordre reçu, sans trier les réponses observées. Le script consigne séparément le schéma natif de chaque modèle et vérifie que ces schémas diffèrent. L’équivalence du schéma public n’implique pas que les schémas générés par la dépendance soient identiques.

Le service conserve le comportement d’origine pour les entrées : il accepte comme objet un tableau de paires tel que [["order_id", "ord_123"]]. Le tableau [] et une chaîne JSON vide sont tous deux convertis en objets vides et déclenchent une erreur d’identifiant manquant. Une chaîne non vide reste un corps de requête invalide. Le modèle cible continue d’accepter les valeurs que dict(value) parvient à convertir. Pour limiter les entrées aux seuls objets, le responsable du contrat doit approuver ce changement. Modifier le résultat attendu du test ne suffit pas.

Dans votre dépôt, figez les réponses effectivement renvoyées avant de modifier le code. Conservez les champs facultatifs avec leurs valeurs par défaut explicites, le degré de rigueur de la validation et le traitement des champs inconnus. Testez le gestionnaire d’erreurs utilisé par l’application et la sérialisation des réponses.

Les erreurs de validation brutes diffèrent selon les versions. Le guide Pydantic : migration vers la v2 décrit aussi les changements concernant les alias, la conversion implicite des types, les champs facultatifs et les fonctions de validation personnalisées. La v2 ne convertit pas les exceptions TypeError levées dans ces fonctions en ValidationError.

Examinez le script de vérification du contrat

Cet extrait provient du fichier run.py de l’archive. Après avoir extrait le ZIP, exécutez les fichiers complets. L’archive contient les configurations de chaque étape avec leurs dépendances verrouillées, ainsi que les jeux de test HTTP.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172class OrderInput(BaseModel):
    internal_order_id: StrictStr = Field(alias="order_id")
    customer_note: StrictStr | None = None
    model_config = ConfigDict(extra="forbid", populate_by_name=False)

    @model_validator(mode="before")
    @classmethod
    def preserve_legacy_mapping(cls, value):
        # v1 tries dict(value), so pairs, [] and "" can become objects.
        # Preserve successful conversions without changing failed-input errors.
        if not isinstance(value, dict):
            try:
                return dict(value)
            except (TypeError, ValueError):
                return value
        return value


def serialize_order(payload):
    return OrderInput(**payload).model_dump(by_alias=True)


def preserve_legacy_error_order(fields):
    # v1 reports declared-field errors first and unknown keys alphabetically.
    # v2 keeps unknown keys in input order; preserve the existing HTTP contract.
    known = [field for field in fields if field["code"] != "extra_forbidden"]
    extra = sorted(
        (field for field in fields if field["code"] == "extra_forbidden"),
        key=lambda field: field["path"],
    )
    return known + extra


def check_target_model():
    for payload, expected in (
        ({"order_id": "ord_123"}, {"order_id": "ord_123", "customer_note": None}),
        (
            {"order_id": "ord_123", "customer_note": "Leave at desk"},
            {"order_id": "ord_123", "customer_note": "Leave at desk"},
        ),
        (
            {"order_id": "ord_123", "customer_note": None},
            {"order_id": "ord_123", "customer_note": None},
        ),
    ):
        assert serialize_order(payload) == expected
    for payload, expected in (
        ({}, [("order_id", "missing")]),
        ({"order_id": 123}, [("order_id", "string_type")]),
        (
            {"order_id": "ord_123", "customer_note": 17},
            [("customer_note", "string_type")],
        ),
        (
            {"order_id": "ord_123", "unexpected": True},
            [("unexpected", "extra_forbidden")],
        ),
    ):
        try:
            OrderInput(**payload)
        except ValidationError as error:
            assert [
                (item["loc"][0], item["type"]) for item in error.errors()
            ] == expected
        else:
            raise AssertionError(f"Accepted invalid order: {payload}")
    print("PASS: target model validation and serialization (7 cases)")
    print("Model-only checks; use --compare-stages for HTTP migration parity.")


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--output", type=Path, default=ROOT / "evidence")
    parser.add_argument("--compare-stages", action="store_true")
    args = parser.parse_args()
    if not args.compare_stages:
        check_target_model()
        return
    args.output.mkdir(parents=True, exist_ok=True)
    reports = []
    commands = []
    for stage in ("legacy", "prepared", "target"):
        project = Path("support") / stage
        stage_commands = [
            [
                "uv",
                "sync",
                "--project",
                str(project),
                "--python",
                sys.executable,
                "--frozen",
            ],
            [
                "uv",
                "run",
                "--project",
                str(project),
                "--python",
                sys.executable,
                "--frozen",
                "python",
                "test/run_stage.py",
                stage,
                str(args.output / f"{stage}.json"),
            ],
        ]
        for command in stage_commands:
            completed = subprocess.run(
                command, cwd=ROOT, capture_output=True, text=True
            )
            label = f"{stage}-{len(commands)}"
            (args.output / f"{label}.log").write_text(
                completed.stdout + completed.stderr
            )
            commands.append(
                {
                    "command": command,
                    "exit_code": completed.returncode,
                    "log": f"{label}.log",
                }
            )
            (args.output / "commands.json").write_text(
                json.dumps(commands, indent=2, sort_keys=True) + "\n"
            )
            if completed.returncode:
                print(completed.stdout + completed.stderr, file=sys.stderr)
                raise SystemExit(completed.returncode)
            print(completed.stdout, end="")
        reports.append(json.loads((args.output / f"{stage}.json").read_text()))
    assert all(report["python"] == platform.python_version() for report in reports)
    for report in reports[1:]:
        for key in (
            "observations",
            "public_openapi",
            "direct_call",
            "fixture_sha256",
            "schema_fixture_sha256",
        ):
            assert report[key] == reports[0][key], f"Parity failed: {key}"
    assert reports[1]["lock_sha256"] == reports[2]["lock_sha256"]
    native_schema_differs = (
        reports[0]["native_model_schema"] != reports[2]["native_model_schema"]
    )
    assert native_schema_differs, "The example should expose native schema drift"
    manifest = {
        str(path.relative_to(ROOT)): digest(path)
        for path in sorted(ROOT.rglob("*"))
        if path.is_file()
        and not path.resolve().is_relative_to(args.output.resolve())
        and not any(
            part in {".venv", "__pycache__", "evidence", ".ruff_cache"}
            for part in path.relative_to(ROOT).parts
        )
    }
    summary = {
        "status": "pass",
        "scope": "synthetic in-process FastAPI TestClient execution",
        "stages": [report["stage"] for report in reports],
        "http_cases_per_stage": reports[0]["http_cases"],
        "native_model_schema_differs": native_schema_differs,
        "public_http_and_schema_parity": True,
        "commands": commands,
        "source_sha256": manifest,
    }
    (args.output / "summary.json").write_text(
        json.dumps(summary, indent=2, sort_keys=True) + "\n"
    )
    print("PASS: legacy, prepared, target HTTP/schema/serialization contracts match")
    print(
        "Native model schemas differ; the existing public schema adapter is preserved."
    )

Exécutez le workflow dans votre dépôt

1. Rédigez les consignes de migration. Indiquez le module, le code qui l’appelle directement, le responsable, les versions approuvées, les tests de contrat, le code hors périmètre et la procédure de retour en arrière. Arrêtez-vous si la migration de ce module exige une mise à niveau plus large des dépendances ou modifie le comportement public.
2. Établissez la référence de départ. Demandez à Codex de lire AGENTS.md, les consignes de migration, les recommandations officielles, les fichiers de verrouillage, le code appelant et les tests. Consignez le commit de départ et les versions installées. Si des vérifications échouent dès le départ, expliquez ces échecs ou corrigez-en la cause avant de conclure à l’équivalence des résultats.
3. Préparez la compatibilité séparément. Si des dépendances partagées lient le module à d’autres parties du code, examinez d’abord les modifications de préparation. Vérifiez que les tests réussissent avec les mêmes données sur la version d’origine et sur la version de référence préparée.
4. Migrez un seul module. Utilisez le prompt de départ proposé sur cette page. Modifiez le module et son adaptateur direct. Préservez les modules hors périmètre et indiquez quel code de compatibilité subsiste.
5. Exécutez les mêmes tests. Comparez les résultats de la version de référence et de la version finale avec les mêmes jeux de test HTTP et de schéma, sans modifier les résultats attendus. Exécutez les tests d’intégration et les vérifications de lint et de types concernés. Enregistrez leurs sorties en précisant l’état final du code source et des dépendances auquel elles correspondent.
6. Vérifiez le dossier de revue. Examinez le diff, les résultats observés, les écarts non résolus, la couche de compatibilité restante et la procédure de retour en arrière. Créez une pull request en brouillon uniquement si les outils et les permissions du dépôt le permettent. Laissez à la personne chargée de la revue le soin de fusionner les modifications, de les déployer et d’engager la migration d’un autre module.

Consignez les vérifications effectuées

Pour chaque critère, consignez les éléments de vérification suivants :

Criterion: [behavior and test]
Environment: [setup reference; actual runtime and dependency versions]
Before: [commit/diff ID; command; exit code; observed result; evidence path]
After: [final commit/diff ID; command; exit code; observed result; evidence path]
Status: [pass / fail / blocked / not run]
Limits: [untested behavior, missing prerequisite, or required owner decision]

Un import réussi, une vérification de lint réussie ou un instantané régénéré ne suffisent pas à établir que l’API conserve le même comportement. Consignez séparément les différences intentionnelles et relancez les vérifications si le code source final change. Lorsque vous adaptez l’exemple, incluez dans les tests de contrat les services de votre application et le code appelant.