Une chaîne qui échoue vaut mieux qu'une chaîne qui devine

Diapositive 1 / 29

Ce que couvre cette leçon

• La défaillance qui n'a pas de message d'erreur
• Sept vérifications, chacune avec une défaillance réelle derrière
• Échouez au point de défaillance, non à la fin
• Ce que fait cette plateforme
• La règle à retenir
• Rapportez-le en entier
• La suite

Diapositive 2 / 29

La défaillance qui n'a pas de message d'erreur

• Rien n'a échoué — Le graphique est tracé, le pourcentage est plausible, le fichier est daté d'aujourd'hui, et le nombre…
• C'est le mode de défaillance pour lequel cette leçon existe — et il est bien plus courant qu'un plantage

Diapositive 3 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Une : les colonnes attendues sont présentes

Diapositive 4 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

REQUIRED = {"household_id", "district", "water_source", "round_trip_minutes"}
missing = REQUIRED - set(survey.columns)
if missing:
    raise ValueError(f"Export is missing columns: {sorted(missing)}")

Diapositive 5 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En R

stopifnot(all(required %in% names(survey)))

Diapositive 6 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Deux : le nombre de lignes est dans la plage attendue

Diapositive 7 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

if not 2_000 <= len(survey) <= 3_000:
    raise ValueError(f"Expected 2,000-3,000 households, got {len(survey):,}")

Diapositive 8 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• La moitié d'un export est la défaillance silencieuse la plus courante — Un téléchargement tronqué, un filtre resté…
• Trois : les codes sont les codes que vous connaissez

Diapositive 9 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

KNOWN = {"piped-into-dwelling", "piped-into-yard", "public-tap", "borehole",
         "protected-well", "protected-spring", "unprotected-well",
         "unprotected-spring", "surface-water", "tanker-truck", "rainwater"}
unknown = set(survey["water_source"].dropna()) - KNOWN
if unknown:
    raise ValueError(f"Unknown water_source values: {sorted(unknown)}")

Diapositive 10 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En R

setdiff(unique(survey$water_source), known)

Diapositive 11 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Un nouveau code est une décision, non une donnée — Quelqu'un a ajouté une option au formulaire et l'analyse doit…
• Quatre : l'identifiant est unique là où il doit l'être

Diapositive 12 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

duplicates = survey["household_id"].duplicated().sum()
if duplicates:
    raise ValueError(f"{duplicates} duplicate household_id values")

Diapositive 13 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Le registre scolaire de cette plateforme a exactement ce défaut — deux élèves y figurent deux fois après un transfert…
• Cinq : les valeurs manquantes sont là où vous les attendez

Diapositive 14 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

completeness = survey.notna().mean()
if completeness["district"] < 0.99:
    raise ValueError(f"district is {completeness['district']:.1%} complete")

Diapositive 15 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Six : les nombres sont dans une plage possible

Diapositive 16 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

implausible = survey[(survey["litres_per_person_day"] < 0)
                     | (survey["litres_per_person_day"] > 200)]
if len(implausible) > 20:
    raise ValueError(f"{len(implausible)} implausible litres values")

Diapositive 17 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Notez le seuil plutôt qu'une tolérance nulle — Onze ménages avec une erreur d'unité est un défaut documenté que cette…
• Sept : la sortie est celle que vous avez déclarée

Diapositive 18 / 29

Sept vérifications, chacune avec une défaillance réelle derrière — En Python

assert summary["n"].sum() == len(survey), "rows lost between input and summary"

Diapositive 19 / 29

Sept vérifications, chacune avec une défaillance réelle derrière

• Un nombre de lignes qui change au travers d'une jointure est l'assertion la plus utile de l'analyse de programme —…

Diapositive 20 / 29

Échouez au point de défaillance, non à la fin — En Python

def load_survey(path: pathlib.Path) -> pd.DataFrame:
    survey = pd.read_csv(path)
    check_columns(survey)
    check_rows(survey)
    check_codes(survey)
    return survey                # nothing downstream runs on a bad file

Diapositive 21 / 29

Échouez au point de défaillance, non à la fin — En R

load_survey <- function(path) {
  survey <- readr::read_csv(path)
  check_columns(survey); check_rows(survey); check_codes(survey)
  survey
}

Diapositive 22 / 29

Échouez au point de défaillance, non à la fin

• Vérifiez à la frontière — là où les données entrent, et après chaque jointure — Une vérification en fin de chaîne vous…
• Levez une erreur, n'avertissez pas — Un avertissement dans un journal que personne ne lit équivaut à aucune…

Diapositive 23 / 29

Ce que fait cette plateforme

Diapositive 24 / 29

Ce que fait cette plateforme

• Quatre autres s'exécutent dans pnpm test plutôt que dans la compilation — parce qu'elles ont besoin de node:fs et…
• L'une d'elles vérifie une relation que le graphe de références ne peut structurellement pas atteindre — Les règles de…
• Toute règle du type « chaque X a au moins un Y » exige un test de cette forme — Un graphe de références est le mauvais…

Diapositive 25 / 29

La règle à retenir

• Tout champ nommant un fichier livré exige un drapeau ready et un test de système de fichiers à côté — Cette…
• Un chemin dans un frontmatter est une chaîne de caractères, et rien dans une compilation ne peut dire s'il pointe vers…

Diapositive 26 / 29

Rapportez-le en entier — Exemple

Pipeline checks

  The loader validates every raw export before anything downstream runs:
  required columns present, 2,000-3,000 rows, water_source values within the
  known set, household_id unique, district at least 99% complete.

  Implausible litres-per-person values are tolerated up to 20 rows, which is
  the documented unit-entry defect; above that the run stops.

  Row counts are asserted across every join. A join that changes the row
  count stops the pipeline rather than producing a summary.

  All checks raise rather than warn. The March run stopped on an unknown
  water_source value ("piped-shared"), which turned out to be a new form
  option added upstream; it is now mapped explicitly in src/clean.py.

Diapositive 27 / 29

Rapportez-le en entier

• La dernière phrase est ce qui rend la section crédible — Une section de vérifications qui n'a jamais rien attrapé est…

Diapositive 28 / 29

La suite

• Tout ce qui précède suppose que vous êtes encore là.

Diapositive 29 / 29

La suite

Lire la leçon complète, avec le code exécutable Retour à la leçon