Charger et stocker des données

Un fichier CSV est un texte brut organisé en enregistrements et en champs. Des virgules séparent généralement les champs, et le premier enregistrement fournit souvent les noms des colonnes. Le fichier contient des caractères, pas de schéma pandas : le lire implique donc aussi de décider ce que représentent ces caractères.

Charger et examiner un petit fichier

Supposons qu’un fichier contienne :

order_id,date,region,units,price
1001,2026-03-02,North,3,4.50
1002,2026-03-02,South,1,12.00
1003,2026-03-03,North,2,7.25

Lis-le et examine le résultat :

import pandas as pd

df = pd.read_csv("sales.csv")
print(df.head())
print(df.shape)
print(df.dtypes)
df.info()

La forme est (3, 5) : trois lignes de données et cinq colonnes. pandas infère int64 pour order_id et units, et float64 pour price. La colonne date contient toujours du texte. Dans pandas 3, les colonnes de texte inférées affichent normalement str ; les versions antérieures de pandas affichent souvent object.

Chaque vérification répond à une question différente. head() montre si les champs correspondent à leurs étiquettes. shape révèle des lignes manquantes ou une colonne supplémentaire inattendue. dtypes vérifie l’interprétation, et info() ajoute les nombres de valeurs non manquantes. Si une colonne destinée à contenir des nombres est chargée comme texte, examine les valeurs brutes : une unité, un code de valeur manquante ou une convention décimale différente peut empêcher l’inférence d’un type numérique.

Faire correspondre les étiquettes aux enregistrements

Pour un fichier sans en-tête dont la première ligne est 1001,North,3, utilise :

df = pd.read_csv(
    "orders.txt",
    header=None,
    names=["id", "region", "units"]
)

Sans ce choix, pandas prend le premier enregistrement pour l’en-tête. Ses valeurs deviennent des noms de colonnes et l’enregistrement disparaît des données. Utilise index_col="order_id" lorsqu’une colonne existante doit servir d’index aux lignes. Utilise usecols=["region", "units"] pour ne lire que ces colonnes, ou nrows=1000 pour examiner les 1 000 premières lignes de données avant de charger un gros fichier.

Laisser le lecteur CSV gérer les guillemets

L’enregistrement "Smith, Jane",Boston,10 comporte trois champs. La virgule à l’intérieur du nom entre guillemets fait partie de ce nom. Deux guillemets doubles dans un champ entre guillemets représentent un guillemet double littéral : "O'Neil ""Red""" devient O'Neil "Red". Un champ entre guillemets peut même contenir un saut de ligne : les enregistrements et les lignes physiques ne correspondent donc pas toujours.

L’appel à line.split(",") coupe le nom et ne peut pas gérer ces règles. read_csv les gère pendant l’analyse. pd.read_table utilise la tabulation comme séparateur par défaut ; pd.read_fwf gère les champs définis par des positions de caractères.

Trouver le fichier que Python recherche

Un chemin relatif est résolu à partir du répertoire de travail courant du programme. Si "data/sales.csv" est introuvable, examine ce répertoire avec Path.cwd() après from pathlib import Path. Un chemin absolu, un objet Path, une URL ou un fichier texte en mémoire comme StringIO peut aussi être passé à read_csv. Vérifie l’emplacement avant de modifier les options d’analyse : un fichier manquant et un fichier mal analysé sont deux problèmes différents.

Un séparateur de champs sépare les champs ; un séparateur décimal sépare les parties entière et décimale d’un nombre. Un séparateur de milliers groupe les chiffres. Ces trois rôles nécessitent des réglages distincts, même lorsque le même symbole remplit différents rôles selon les fichiers.

Examiner les caractères avant de choisir les options

Regarde quelques lignes brutes dans un éditeur. Une extension .csv ne garantit pas la présence de virgules et .txt n’indique pas la structure. Voici des réglages courants :

Tu peux examiner le début sans lire tout le fichier :

with open("products.csv", encoding="utf-8") as f:
    print(f.readline())
    print(f.readline())

Étudier une exportation régionale

Considère ce texte :

product;price;qty
Tea;3,50;1.200
Coffee;12,90;850

Les points-virgules séparent les champs, la virgule est le séparateur décimal et le point groupe les milliers. Indique explicitement ces trois conventions à la lecture :

df = pd.read_csv(
    "products.csv",
    sep=";",
    decimal=",",
    thousands="."
)

Les prix deviennent 3,5 et 12,9. Les quantités deviennent 1 200 et 850. Avec la virgule comme séparateur par défaut, cet en-tête ne décrit pas trois colonnes séparées par des virgules. Même après avoir choisi sep=";", le travail n’est pas terminé : les prix restent du texte et "1.200" peut devenir le nombre décimal 1,2. Ce dernier résultat est un nombre valide, mais son sens est erroné : une erreur grave peut donc survenir sans exception d’analyse.

Compare quelques valeurs chargées avec leur texte source et examine describe() pour repérer des plages invraisemblables. Une quantité attendue dans les milliers qui apparaît proche de un indique un possible problème de convention numérique. Modifier uniquement le séparateur ne le corrigera pas.

Distinguer les limites des champs du groupement des nombres

Dans un fichier dont les champs sont séparés par des virgules, un nombre groupé comme "1,234.50" doit être entre guillemets. La virgule à l’intérieur fait partie du nombre. Avec thousands=",", pandas peut lire le champ entre guillemets comme 1 234,5. Sans guillemets, la virgule crée aussi une limite de champ ; thousands ne peut pas rétablir la structure perdue de l’enregistrement.

Choisir un moteur d’analyse syntaxique compatible

Le moteur C par défaut traite rapidement les structures courantes. Le moteur Python prend en charge la détection du séparateur avec sep=None, les séparateurs sous forme d’expressions régulières et skipfooter. La détection examine un échantillon et peut mal choisir sur un rapport irrégulier : indique donc directement un séparateur connu.

Un séparateur de plus d’un caractère est généralement traité comme une expression régulière et nécessite le moteur Python ; r"\s+" est un cas particulier également pris en charge par le moteur C. Le moteur PyArrow peut lire avec des fils d’exécution parallèles, mais prend en charge un ensemble d’options différent. Par exemple, chunksize n’est pas pris en charge avec engine="pyarrow". Choisis le moteur selon les options nécessaires à ton fichier, puis vérifie la structure et les valeurs du résultat.

L’inférence de type ne peut pas savoir si 999 est une mesure ou un code indiquant une valeur inconnue. Elle ne peut pas non plus savoir si les zéros initiaux ont un sens. Utilise les définitions des données pour régler les options de lecture avant que l’inférence ne modifie ces valeurs.

Déclarer les marqueurs de valeurs manquantes là où ils s’appliquent

pandas reconnaît les champs vides et les marqueurs intégrés comme "NA", "N/A", "n/a", "NULL", "NaN" et "None". Une source peut utiliser d’autres marqueurs. Supposons que score contienne 88, "n/a", "-" et 999, 999 étant défini comme inconnu :

df = pd.read_csv(
    "scores.csv",
    na_values={"score": ["-", "999"]}
)

La colonne des scores contient maintenant 88,0 et trois valeurs manquantes. Sans déclaration des marqueurs, "-" peut maintenir la colonne sous forme de texte ; une valeur sentinelle numérique non déclarée peut entrer dans les calculs. La moyenne de 88 et 999 est de 543,5, même si le seul score connu est 88.

Un dictionnaire limite un marqueur à sa colonne. Un na_values=["999"] appliqué à tout le fichier supprimerait aussi un code de produit réel 999. Si "NA" est une véritable étiquette, utilise keep_default_na=False pour désactiver la liste des marqueurs intégrés et indique explicitement les marqueurs qui signifient réellement une valeur manquante. Avec ce réglage, inclus "" si les champs vides doivent toujours compter comme manquants.

Préserver les valeurs selon leur rôle

Lis les identifiants comme du texte :

df = pd.read_csv(
    "visits.csv",
    dtype={"site_code": str, "visits": "Int64"}
)

Un code comme "00501" doit conserver ses cinq caractères. Le lire comme un entier donne 501 ; convertir cet entier en texte ensuite produit "501", pas le code d’origine. Utilise un type numérique pour les valeurs avec lesquelles tu fais des calculs.

Les colonnes ordinaires d’entiers NumPy ne peuvent pas contenir NaN : une colonne d’effectifs avec une valeur manquante devient donc souvent float64. Le type nullable "Int64" de pandas, avec un I majuscule, conserve les valeurs entières et représente une valeur manquante par <NA>. dtype_backend="numpy_nullable" demande des types nullables pour l’ensemble du résultat. Pour un petit ensemble d’étiquettes répétées, dtype={"region": "category"} stocke les étiquettes comme catégories et peut réduire l’utilisation de la mémoire.

Préciser l’écriture des dates

Un texte qui ressemble à une date reste du texte tant qu’il n’est pas converti. Pour les dates où le jour vient en premier, comme "03/04/2026" et "13/04/2026", utilise :

df = pd.read_csv(
    "events.csv",
    parse_dates=["day"],
    date_format="%d/%m/%Y"
)

Ces valeurs deviennent le 3 avril et le 13 avril. Sans format, une hypothèse donnant la priorité au mois peut soit inverser des jours et des mois valides, soit empêcher la conversion de la colonne. dayfirst=True exprime une préférence ; un format explicite indique la structure attendue. Les dates ISO comme "2026-04-03" évitent l’ambiguïté entre jour et mois.

Après la lecture, examine dtypes, isna().sum() et le nombre de lignes. Vérifie une date dont l’interprétation distingue les conventions. Si une colonne reste du texte, la conversion n’a pas produit les dates et heures attendues ; une augmentation inattendue du nombre de valeurs manquantes peut révéler qu’une véritable étiquette a été prise pour un marqueur.

Un rapport peut mêler un tableau à des titres, des lignes vides, des commentaires, des totaux et des notes sur la source. Repère d’abord l’en-tête et les bornes des données. Sinon, un lecteur peut prendre un titre pour des noms de colonnes ou inclure un total comme observation ordinaire.

Lire uniquement le tableau

Un rapport contient ces neuf lignes physiques :

Monthly sales report
Exported 2026-04-01

region,jan,feb
North,120,135
# test row below
South,98,101
Total,218,236
Source: internal system

Les trois premières lignes précèdent l’en-tête. Les deux dernières ne sont pas des observations. Lis-le avec :

df = pd.read_csv(
    "report.csv",
    skiprows=3,
    comment="#",
    skipfooter=2,
    engine="python"
)

Le résultat comporte deux lignes. Le total de janvier est de 218 pour North et South. Conserver la ligne de totaux ajouterait 218 et donnerait 436. Avec les options par défaut, le titre à un champ peut devenir l’en-tête et provoquer une erreur d’analyse à l’arrivée des enregistrements à trois champs.

skiprows=3 compte les trois premières lignes physiques, y compris la ligne vide. Une liste comme skiprows=[0, 2] supprime des lignes à des positions précises, comptées à partir de zéro. Les lignes vides sont ignorées par défaut, et comment="#" supprime le texte des commentaires. skipfooter nécessite le moteur Python. Adapte ces réglages à la structure réelle : un nombre fixe de lignes à ignorer peut devenir incorrect si l’outil d’exportation ajoute une ligne de titre.

Examiner les enregistrements mal formés

Un enregistrement comportant trop de champs peut déclencher on_bad_lines="error", l’option par défaut. "warn" l’ignore avec un avertissement, tandis que "skip" le supprime sans avertissement. Avant de choisir l’une de ces options, examine l’enregistrement brut. Une virgule non placée entre guillemets dans un nom ou un mauvais séparateur peut créer des champs supplémentaires ; ignorer la ligne fait alors perdre une observation valide au lieu de corriger la cause.

Un nombre insuffisant de champs se traite différemment. Sous id,name,score, l’enregistrement 2,Ben est chargé avec un score manquant. Il ne déclenche pas forcément d’erreur. Vérifie les nombres de valeurs manquantes ainsi que le nombre de lignes, et compare les enregistrements conservés à la source lorsque tu exclus des lignes mal formées.

Lire des en-têtes superposés ou des positions de caractères

Deux lignes d’étiquettes de colonnes peuvent former un MultiIndex. Avec les étiquettes de groupes region,sales,sales au-dessus de ,2025,2026, header=[0, 1] produit des étiquettes comme ("sales", "2025"). Si des étiquettes sans hiérarchie conviennent mieux à l’analyse, ignore les deux lignes d’en-tête et fournis names=["region", "sales_2025", "sales_2026"].

Un texte à largeur fixe n’a pas de séparateur. Les bornes des colonnes sont des positions de caractères :

df = pd.read_fwf(
    "readings.txt",
    colspecs=[(0, 4), (4, 11), (11, 16)]
)

Ces intervalles semi-ouverts incluent chaque début et excluent sa fin. Le premier champ occupe les positions de 0 à 3, et le suivant commence à 4. widths=[4, 7, 5] décrit la même structure. L’inférence est pratique pour des échantillons réguliers ; des bornes explicites évitent qu’une valeur courte au début définisse une largeur incorrecte.

Un fichier stocke des octets, chacun ayant une valeur de 0 à 255. Un encodage définit comment les caractères sont représentés par ces octets. L’encodage convertit le texte Python en octets ; le décodage reconvertit les octets en texte. Les mêmes octets peuvent représenter des caractères différents selon la règle de décodage.

Compter séparément les caractères et les octets

text = "café"
raw = text.encode("utf-8")
print(len(text))  # 4 characters
print(len(raw))   # 5 bytes
print(raw.decode("utf-8"))  # café

Ici, l’accent ne constitue pas un deuxième caractère visible. La lettre "é" nécessite deux octets en UTF-8 : quatre caractères occupent donc cinq octets. Le nombre d’octets et le nombre de caractères répondent à des questions différentes.

ASCII définit 128 caractères, dont les lettres anglaises de base, les chiffres, la ponctuation et les codes de contrôle. Leurs valeurs d’octet sont identiques en ASCII, UTF-8, Latin-1 et Windows-1252. Ce début commun explique pourquoi un échantillon contenant uniquement du texte anglais peut sembler correct même lorsque le réglage de l’encodage est erroné.

Reconnaître les principales familles d’encodages

UTF-8 représente tous les caractères Unicode et constitue le choix habituel pour échanger du texte. Latin-1 et Windows-1252 représentent un ensemble plus réduit de caractères. Ils concordent pour de nombreuses lettres accentuées, mais diffèrent sur une partie des valeurs d’octet : Windows-1252 utilise l’octet 0x80 pour "€", là où Latin-1 comporte un caractère de contrôle. Ce ne sont pas deux noms interchangeables pour un même encodage.

Lire correctement les marques d’ordre des octets

Une marque d’ordre des octets, ou BOM, est un marqueur placé au début de certains fichiers. UTF-16 peut commencer par FF FE pour l’ordre avec l’octet de poids faible en premier ou par FE FF pour l’ordre avec l’octet de poids fort en premier. encoding="utf-16" utilise la BOM pour choisir l’ordre. Sans BOM, précise "utf-16-le" ou "utf-16-be" selon la source.

Une BOM UTF-8 est EF BB BF. open(..., encoding="utf-8-sig") de Python la supprime pendant le décodage. Dans open(), le simple "utf-8" la conserve sous la forme \ufeff, qui peut se retrouver sans qu’on s’y attende dans le premier nom d’en-tête. Le lecteur CSV de pandas gère aussi une BOM UTF-8 initiale, mais choisir utf-8-sig rend explicite la convention attendue pour le fichier.

Indiquer explicitement l’encodage

with open("notes.txt", encoding="utf-8") as f:
    text = f.read()

La valeur par défaut de open() dépend de la version de Python et du mode UTF-8. Python 3.11 à 3.14 peuvent utiliser l’encodage des paramètres régionaux ; Python 3.15 active le mode UTF-8 par défaut, avec la possibilité de le désactiver. Un encodage explicite maintient la correspondance entre le script et le format réel du fichier sur tous les ordinateurs. Il empêche aussi qu’un réglage par défaut propre à une plateforme change silencieusement la lecture des mêmes octets.

Un mauvais encodage peut provoquer une erreur visible avec UnicodeDecodeError, ou produire silencieusement un texte déformé qui semble lisible, appelé mojibake. Dans les deux cas, le problème vient d’une interprétation des octets selon la mauvaise règle. Conserve le fichier d’origine pour pouvoir le décoder à nouveau.

Diagnostiquer une erreur à partir de la source

Un CSV enregistré en Windows-1252 contient des noms de villes dont "Zürich" et "Málaga". Sa lecture en UTF-8 peut échouer à l’octet 0xfc, utilisé pour "ü" en Windows-1252. Une fois que les paramètres d’exportation de la source confirment son encodage, lis-le avec :

df = pd.read_csv("cities.csv", encoding="cp1252")
print(df["city"].head())

Examine les noms contenant des accents ou des symboles. Un échantillon composé uniquement de caractères ASCII ne permet pas de distinguer ces encodages. Un octet invalide particulier en UTF-8 suggère un ancien encodage possible ; il ne permet pas de déterminer avec certitude lequel a produit le fichier.

Reconnaître une erreur qui n’a pas déclenché d’exception

Des octets UTF-8 décodés en Windows-1252 peuvent transformer "café" en "café" et "São Paulo" en "São Paulo". Le lecteur a produit des caractères sans erreur, mais ce ne sont pas les bons. Relis les octets d’origine en UTF-8 :

df = pd.read_csv("cities.csv", encoding="utf-8")

La recherche et le remplacement corrigent un symptôme visible à la fois et peuvent manquer d’autres lettres endommagées. Ils risquent aussi de modifier une occurrence correcte d’un caractère. Un décodage correct traite la cause pour tout le fichier.

Recueillir des indices sur l’encodage

Commence par la documentation du fournisseur ou ses paramètres d’exportation. Examine un petit échantillon d’octets si nécessaire :

with open("cities.csv", "rb") as f:
    sample = f.read(200)
print(sample)

Le mode binaire préserve les octets sans les décoder. Une BOM peut fournir un indice direct. Un détecteur comme charset-normalizer estime l’encodage probable, mais un échantillon court peut correspondre à plusieurs possibilités. Vérifie le résultat avec des noms accentués et des symboles connus.

Latin-1 attribue un caractère à chaque octet : il peut donc décoder toute suite d’octets sans erreur. Cette réussite ne dit rien à elle seule sur la correction des caractères. Windows-1252 utilise aussi des caractères sur un octet, mais laisse quelques valeurs d’octet non définies et peut déclencher une erreur de décodage.

Éviter de supprimer les indices

encoding_errors="replace" remplace par "�" les octets que le décodeur ne peut pas lire. encoding_errors="ignore" les supprime. Ces options peuvent aider à examiner des données d’entrée endommagées, mais elles font perdre des informations et ne doivent pas remplacer la recherche du bon encodage. Un nom transformé en "Zrich" peut empêcher une correspondance tout aussi sûrement qu’un texte visiblement déformé.

Pour la sortie, UTF-8 prend en charge la plus large gamme de caractères. Certains tableurs le reconnaissent plus sûrement en présence d’une BOM :

df.to_csv("cities_export.csv", index=False, encoding="utf-8-sig")

Rouvre le fichier exporté dans le programme destinataire et examine les mêmes valeurs accentuées. L’objectif est d’obtenir un texte correct aux deux extrémités de l’échange.

La taille d’un fichier sur disque ne correspond pas à la mémoire qu’il nécessite. pandas construit en mémoire des tableaux, des index et des valeurs textuelles dont les types influent sur l’espace nécessaire. Mesure-le avec df.memory_usage(deep=True) ou df.info(memory_usage="deep") avant de décider comment charger davantage de données.

Réduire les données chargées en mémoire

Lis une sélection de colonnes avec usecols, examine un échantillon initial avec nrows et choisis des types adaptés avec dtype. Une catégorie peut stocker les noms de régions répétés de manière compacte. float32 utilise moins d’espace que float64, mais offre environ sept chiffres significatifs : choisis-le uniquement si cette précision convient aux mesures. Un petit aperçu aide à déterminer les types ; il ne prouve pas que toutes les lignes suivantes ont la même structure.

Traiter les blocs et conserver un résultat réduit

chunksize transforme la valeur renvoyée : au lieu d’un DataFrame, on obtient un itérateur de DataFrame. Pour calculer un total et une moyenne :

total = 0.0
count = 0
with pd.read_csv(
    "measurements.csv",
    usecols=["amount"],
    chunksize=100_000
) as reader:
    for chunk in reader:
        total += chunk["amount"].sum()
        count += chunk["amount"].count()
mean = total / count if count else float("nan")

La boucle conserve une somme cumulée et un nombre cumulé de valeurs non manquantes. Chaque bloc peut être libéré après utilisation. Rassembler tous les blocs dans une liste puis les concaténer rétablit le besoin de mémoire initial ; le traitement par blocs n’économise de la mémoire que si le travail conserve un résultat réduit ou écrit les parties traitées.

Un fichier de dix lignes lu avec chunksize=4 donne des blocs de 4, 4 et 2 lignes. Pour des montants de 1 à 10 avec les régions N, S, E qui se répètent, additionne les totaux régionaux partiels pour obtenir 22 pour N, 15 pour S et 18 pour E. Leur total est de 55.

Combiner les bonnes quantités

Les sommes et les effectifs s’additionnent. Pour combiner les minimums, on prend le plus petit des minimums partiels ; pour les maximums, on prend le plus grand des maximums partiels. Les moyennes nécessitent une pondération, car les blocs peuvent contenir des nombres différents d’observations valides.

Pour les valeurs 1, 2 et 3 dans un bloc et 10 dans un autre, les moyennes des blocs sont de 2 et 10. La moyenne de ces deux moyennes est de 6 : elle attribue le même poids au bloc d’une valeur et à celui de trois valeurs. Additionne plutôt les sommes et les effectifs : un total de 16 pour quatre observations donne une moyenne de 4. Les médianes des blocs ne contiennent pas assez d’informations pour reconstituer une médiane globale.

Lire directement les fichiers compressés

read_csv infère normalement la compression à partir d’extensions reconnues comme .gz, .bz2, .zip, .xz et .zst. Il décompresse pendant la lecture :

with pd.read_csv("measurements.csv.gz", chunksize=100_000) as reader:
    for chunk in reader:
        print(len(chunk))

Une archive ZIP utilisée ainsi doit contenir exactement un fichier de données. df.to_csv("out.csv.gz", index=False) écrit un CSV compressé avec gzip. La compression réduit l’espace disque et la taille du transfert ; elle ne supprime pas la mémoire utilisée par le tableau décodé. Pour des analyses répétées, convertir un jeu de données vérifié en Parquet évite aussi de réanalyser le texte et restitue les types de colonnes stockés.

Un classeur Excel peut contenir plusieurs feuilles, des titres et des totaux calculés. Les cellules possèdent des valeurs et des types stockés ainsi qu’une mise en forme d’affichage. Lire une feuille consiste à repérer le tableau de données et à comprendre quelles parties du classeur deviennent des valeurs du DataFrame.

Choisir la feuille et ses bornes

df = pd.read_excel(
    "quarterly.xlsx",
    sheet_name="Q1",
    skiprows=2,
    usecols="A:C",
    nrows=2
)

Supposons que la ligne 1 soit un titre fusionné, que la ligne 2 soit vide, que la ligne 3 contienne region, date et sales, et que les lignes 4 à 5 contiennent les observations. skiprows=2 fait de la ligne 3 l’en-tête ; nrows=2 s’arrête avant le total de la ligne 6. Pour North 1 200 et South 950, la somme des deux observations est de 2 150. Inclure un total mis en cache de 2 150 comme troisième observation doublerait ce montant.

Excel affiche les numéros de ligne à partir de 1 ; les positions des lignes dans pandas commencent à 0. header=2 sélectionne aussi la ligne 3 d’Excel comme en-tête. usecols="A,C,E:F" sélectionne des colonnes distinctes et une plage. L’option par défaut sheet_name=0 lit la première feuille ; un nom sélectionne une feuille précise, et sheet_name=1 sélectionne la deuxième.

sheet_name=None renvoie un dictionnaire qui associe les noms des feuilles à des DataFrame. Sélectionne une clé ou parcours les éléments avec .items() ; le dictionnaire lui-même n’est pas un DataFrame unique. Pour effectuer plusieurs lectures dans un même classeur :

with pd.ExcelFile("quarterly.xlsx") as xf:
    print(xf.sheet_names)
    q1 = pd.read_excel(xf, sheet_name="Q1")

Savoir ce que la cellule stocke réellement

Un pourcentage affiché sous la forme "15%" stocke 0,15. Un nombre affiché sur cinq chiffres peut contenir 2 139, même si l’écran montre "02139". Aucune option de lecture ne peut retrouver un zéro qui n’existe que dans la mise en forme. Stocke les identifiants comme texte dans le classeur et passe aussi dtype={"zip": str} à la lecture ; sinon, pandas peut inférer des entiers même à partir de cellules textuelles composées uniquement de chiffres.

La précision numérique d’Excel est limitée à 15 chiffres significatifs. Un identifiant de 16 chiffres saisi comme nombre peut déjà être endommagé avant sa lecture par Python. Stocke ces valeurs comme texte. Une feuille de calcul comporte au maximum 1 048 576 lignes et 16 384 colonnes : un très grand jeu de données nécessite donc un autre format.

Traiter les formules et les cellules fusionnées avec soin

pandas ne calcule pas les formules. Il lit les résultats mis en cache dans le classeur. Un tableur peut enregistrer des résultats à jour ; un fichier généré par un script peut contenir des résultats en cache manquants, provisoires ou périmés. openpyxl ne calcule pas de résultat, et XlsxWriter écrit normalement un zéro provisoire si aucune valeur ne lui est fournie. Recalcule les valeurs importantes dans pandas ou ouvre et enregistre le classeur dans un tableur avant de te fier à ses totaux mis en cache.

Seule la cellule supérieure gauche d’une plage de cellules fusionnées stocke son étiquette. Une étiquette de pays fusionnée peut donc laisser des cellules vides dans les lignes suivantes. Lorsque la structure confirme que l’étiquette s’applique à ces lignes, df["country"] = df["country"].ffill() la propage vers le bas. Examine les bornes du tableau avant de remplir les cellules.

La lecture nécessite une bibliothèque servant de moteur. openpyxl gère .xlsx et .xlsm ; xlrd gère .xls, pyxlsb gère .xlsb, odf gère .ods et calamine prend en charge plusieurs formats de tableur. Un moteur manquant déclenche une ImportError qui indique la dépendance. Les couleurs, commentaires et autres éléments de mise en forme ne sont pas chargés comme données du DataFrame.

Excel est utile lorsque des personnes doivent ouvrir et examiner un rapport dans un tableur. Un DataFrame peut devenir une feuille de calcul, ou plusieurs DataFrame peuvent partager un classeur. Choisis le chemin de destination et les noms des feuilles avant l’écriture pour que chaque tableau soit placé au bon endroit.

Écrire un ou plusieurs tableaux

weather.to_excel(
    "weather.xlsx",
    sheet_name="Weather",
    index=False
)

index=False exclut les numéros de ligne par défaut de la feuille. Sans cette option, ils apparaissent comme une première colonne supplémentaire et peuvent revenir sous la forme "Unnamed: 0" lors d’une lecture ultérieure. Ne conserve un index que s’il contient des étiquettes qui ont un sens et doivent figurer dans le rapport.

Un appel à to_excel avec un chemin écrit un classeur à cet emplacement et remplace un fichier existant. L’appeler une fois pour Weather puis une seconde fois pour Counts au même chemin peut ne laisser que le second tableau. Utilise un seul objet d’écriture pour les deux :

with pd.ExcelWriter("report.xlsx") as writer:
    weather.to_excel(writer, sheet_name="Weather", index=False)
    counts.to_excel(writer, sheet_name="Counts", index=False)

Le gestionnaire de contexte termine l’écriture et ferme le classeur à la fin du bloc. Sa lecture avec pd.read_excel("report.xlsx", sheet_name=None) renvoie un dictionnaire contenant les deux noms de feuilles. L’écriture de fichiers .xlsx nécessite openpyxl ou XlsxWriter.

Mettre à jour une feuille d’un classeur existant

Pour préserver les autres feuilles tout en en remplaçant une, utilise un objet d’écriture en mode ajout :

with pd.ExcelWriter(
    "report.xlsx",
    mode="a",
    engine="openpyxl",
    if_sheet_exists="replace"
) as writer:
    counts.to_excel(writer, sheet_name="Counts", index=False)

if_sheet_exists contrôle ce qui se passe en cas de conflit de noms. "error" arrête l’opération, "new" crée une autre feuille, "replace" remplace la feuille et "overlay" écrit dans ses cellules existantes. L’écriture en superposition n’efface pas les anciennes cellules situées hors du nouveau tableau : une mise à jour plus courte peut donc laisser d’anciennes lignes. Décide si le rapport nécessite un remplacement complet de la feuille ou une écriture en superposition soigneusement positionnée.

Faciliter la réouverture du fichier

Les noms de feuilles sont limités à 31 caractères et ne peuvent pas contenir :, \, /, ?, *, [ ou ]. Un nom court comme "Q1 Summary" convient ; "Q1/Q2" contient une barre oblique interdite. Certains moteurs émettent un avertissement au lieu de s’arrêter pour un nom trop long : choisis donc toi-même des noms compatibles.

startrow et startcol positionnent un tableau à l’aide de décalages comptés à partir de zéro. na_rep donne un marqueur visible aux valeurs manquantes. float_format="%.2f" arrondit les nombres écrits, et autofilter=True ajoute des boutons de filtre à l’en-tête dans pandas 3. Les colonnes de dates et heures sont écrites comme des dates Excel.

L’arrondi en sortie modifie les nombres stockés, pas seulement leur affichage. Conserve séparément un fichier d’analyse avec toutes les décimales lorsqu’un rapport arrondi est nécessaire. Rouvre le classeur et vérifie la liste des feuilles, les dimensions des tableaux et des valeurs représentatives. La lecture Excel est relativement lente et un aller-retour peut modifier les types de données pandas : utilise donc Parquet pour les tableaux d’analyse intermédiaires lorsque la conservation des types compte.

JSON stocke les données imbriquées sous forme de texte. Les objets contiennent des paires nom-valeur, les tableaux contiennent des valeurs ordonnées et les chaînes utilisent des guillemets doubles. Les autres valeurs sont les nombres, true, false et null. Le module json de Python convertit cette syntaxe en objets Python avant la construction d’un tableau.

Analyser et écrire du JSON valide

import json

text = '{"station":"Oslo","active":true,"temp_c":[3.5,null,4.0]}'
data = json.loads(text)
print(data["active"])   # True
print(data["temp_c"])   # [3.5, None, 4.0]

Les objets deviennent des dictionnaires, les tableaux deviennent des listes et null devient None. json.loads analyse une chaîne ; json.load lit un fichier ouvert. Les fonctions d’écriture effectuent l’opération inverse : json.dumps renvoie du texte et json.dump écrit dans un fichier.

with open("station.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

ensure_ascii=False laisse lisibles des caractères comme "ü". La valeur par défaut peut écrire le même caractère sous la forme \u00fc ; les deux formes représentent la même chaîne. Un dictionnaire Python affiché n’est pas du JSON : les guillemets simples, True, None et les virgules finales ne sont pas valides dans la syntaxe JSON. Le JSON standard ne comporte pas non plus de NaN. L’encodeur Python l’autorise par défaut, mais allow_nan=False le refuse ; pandas écrit les valeurs manquantes sous la forme null.

Adapter la structure du tableau

Un tableau JSON nécessite une orientation, c’est-à-dire une disposition des lignes, des étiquettes et des valeurs. orient="records" donne un objet par ligne :

[{"city":"Lyon","temp_c":21.5},{"city":"Osaka","temp_c":null}]

L’orientation par défaut d’un DataFrame, "columns", groupe les valeurs sous les noms de colonnes, puis sous les étiquettes de lignes. "split" stocke séparément les colonnes, l’index et les données. Précise une orientation adaptée au programme destinataire au lieu de supposer que tous les tableaux JSON ont la même forme.

from io import StringIO
import pandas as pd

df = pd.read_json(
    StringIO('[{"code":"0042","amount":9.5}]'),
    orient="records",
    dtype={"code": str}
)

Dans pandas 3, une chaîne simple passée à read_json est un chemin : place donc le texte JSON lui-même dans StringIO. Même les chaînes JSON composées uniquement de chiffres peuvent être interprétées comme des nombres ; le type de données explicite préserve "0042".

Utiliser JSON Lines pour des enregistrements séquentiels

JSON Lines contient un objet JSON complet par ligne, sans tableau englobant ni virgule entre les enregistrements :

{"id":1,"amount":9.5}
{"id":2,"amount":12.0}

Lis-le avec pd.read_json(path, lines=True) et écris-le avec df.to_json(path, orient="records", lines=True). Les options chunksize et nrows du lecteur nécessitent lines=True, qui rend les enregistrements accessibles séquentiellement.

Lors de l’exportation des dates, définis date_format="iso" pour obtenir des horodatages ISO lisibles. pandas 3.1 utilise encore par défaut les millisecondes depuis l’origine pour la sortie JSON ordinaire d’un DataFrame, mais cette valeur par défaut va changer. Une sortie explicite des dates évite de dépendre d’un lecteur qui devrait deviner ce que représente un grand entier.

Du JSON imbriqué peut décrire une commande, son client et plusieurs articles dans un même objet. Avant de l’aplatir, décide de la granularité : ce que représente une ligne. La granularité détermine quels montants peuvent être additionnés.

Aplatir d’abord les objets imbriqués

Considérons deux commandes. La commande 501 appartient à Ana et contient les articles A1 (quantité 2, prix 3,5) et B7 (quantité 1, prix 10,0). La commande 502 appartient à Ben et contient A1 (quantité 4, prix 3,5). Les informations sur les clients sont des objets imbriqués et les articles sont des listes.

orders = [
    {"order_id": 501,
     "customer": {"name": "Ana", "country": "PT"},
     "items": [{"sku": "A1", "qty": 2, "price": 3.5},
               {"sku": "B7", "qty": 1, "price": 10.0}]},
    {"order_id": 502,
     "customer": {"name": "Ben", "country": "CA"},
     "items": [{"sku": "A1", "qty": 4, "price": 3.5}]}
]
order_rows = pd.json_normalize(orders)

On obtient deux lignes et quatre colonnes : order_id, items, customer.name et customer.country. Les champs imbriqués du client deviennent des colonnes dont les noms sont séparés par des points. Les listes d’articles restent dans des cellules ; la normalisation ne transforme pas automatiquement chaque liste en lignes.

Développer une liste avec les informations de l’objet parent

items = pd.json_normalize(
    orders,
    record_path="items",
    meta=["order_id", ["customer", "name"]]
)

record_path choisit la liste dont les éléments deviennent des lignes. meta copie les valeurs de l’objet parent sur chaque ligne, avec une liste de clés pour un chemin imbriqué. Le résultat comporte trois lignes d’articles : deux pour la commande d’Ana et une pour celle de Ben. Le chiffre d’affaires est égal à la quantité multipliée par le prix : 7,0, 10,0 et 14,0, soit un total de 31,0.

Si les frais de livraison d’une commande sont de 4,00, ils sont répétés sur les deux lignes d’articles de la commande 501. Additionner ces frais répétés donne 8,00 pour une commande. Conserve les montants propres aux commandes dans un tableau des commandes distinct si tu as aussi besoin d’un tableau des articles ; garde order_id pour les relier.

Contrôler les noms et les champs manquants

sep="_" crée des noms comme customer_name. record_prefix="item_" distingue les champs des articles des champs parents de même nom. max_level=0 laisse les dictionnaires imbriqués intacts.

Un champ imbriqué ordinaire absent d’un enregistrement devient une valeur manquante dans sa colonne de sortie. Un champ manquant demandé par meta déclenche une KeyError par défaut ; errors="ignore" autorise les métadonnées manquantes et les remplace par NaN. Une liste manquante nommée par record_path doit toujours être corrigée.

Extraire le contenu des réponses d’API avant de l’aplatir

Une API peut renvoyer une enveloppe contenant count, next et results. Passe data["results"] à pd.json_normalize pour aplatir les enregistrements. Passer l’enveloppe elle-même normalise un objet englobant et laisse sa liste de résultats dans une cellule. Garde les métadonnées de pagination à disposition pour récupérer les pages suivantes, mais construis le tableau d’analyse à partir de la liste réelle des enregistrements.

Une API web accepte une requête HTTP à un point de terminaison et renvoie un code de statut, des en-têtes et un corps. De nombreuses API utilisent des corps JSON, mais la réception d’une réponse ne signifie pas qu’elle contient les données ou tous les enregistrements dont tu as besoin.

Envoyer des paramètres et vérifier la réponse

import requests

resp = requests.get(
    url,
    params={"city": "Lima", "units": "metric"},
    timeout=10
)
resp.raise_for_status()
data = resp.json()
df = pd.json_normalize(data["results"])

Ici, url est le point de terminaison documenté de l’API. params encode la chaîne de requête, ce qui permet de traiter correctement les espaces et les caractères spéciaux dans les valeurs. Requests n’a pas de délai d’expiration par défaut. Une seule valeur de délai contrôle l’attente de la connexion et celle de la lecture ; ce n’est pas une durée limite pour le téléchargement complet de la réponse.

Appelle raise_for_status() avant d’utiliser le corps. Cette méthode déclenche une erreur HTTP pour les réponses 4xx et 5xx. Un message d’erreur JSON peut être analysé correctement tout en décrivant une requête échouée ; inversement, une réponse 200 peut contenir du texte non JSON et faire échouer resp.json(). Examine resp.text lorsque le format de la réponse est inattendu.

Garder les identifiants séparément

Utilise la méthode d’authentification documentée par l’API. Pour un jeton d’accès au porteur, lis une clé depuis une variable d’environnement et envoie-la dans un en-tête :

import os

key = os.environ["WEATHER_API_KEY"]
headers = {"Authorization": "Bearer " + key}

Ne place pas les clés dans le code et les notebooks enregistrés. Si une clé a été partagée ou enregistrée dans un dépôt, révoque-la et remplace-la. Une clé donne accès ; masquer ultérieurement une valeur affichée n’annule pas son exposition.

Continuer jusqu’à la lecture de toutes les pages

Suis le mécanisme de page suivante documenté par l’API, qu’il utilise des numéros de page, des décalages ou une URL de page suivante. Collecte les enregistrements de chaque page et arrête-toi à la condition de fin indiquée. Un total de 230 enregistrements à raison de 100 par page nécessite des pages de 100, 100 et 30 enregistrements. La première page peut être parfaitement valide alors que le jeu de données est incomplet.

Compare le nombre collecté au total indiqué lorsqu’il est disponible. Respecte les limites de fréquence : 429 impose d’attendre avant une nouvelle requête, et Retry-After peut préciser le délai. Cet en-tête peut contenir un nombre de secondes ou une date HTTP. Enregistre les réponses brutes pour rendre l’analyse reproductible et éviter de télécharger les mêmes données à chaque réexécution.

Reconnaître d’autres formats de tableaux web

pd.read_html(url) renvoie une liste de DataFrame, un pour chaque tableau HTML correspondant. match="Population" limite les tableaux selon leur texte. La fonction nécessite une dépendance d’analyse HTML comme lxml ou BeautifulSoup avec html5lib. pd.read_xml lit les éléments XML répétés comme des lignes, avec lxml ou parser="etree". Consulte les conditions d’un site avant d’en extraire les données et privilégie un téléchargement officiel ou une API lorsqu’ils sont disponibles.

Une exportation CSV doit préserver les valeurs nécessaires au destinataire et rendre ses conventions explicites. Choisis si l’index des lignes constitue une donnée, comment les valeurs manquantes apparaissent et si la sortie est destinée à une analyse précise ou à un affichage arrondi.

Choisir ce qui devient une colonne

df.to_csv("weather_processed.csv", index=False)

Par défaut, l’index est écrit. Pour un tableau avec un index numéroté ordinaire, cela ajoute un premier champ sans nom ; une lecture ultérieure avec read_csv peut l’afficher sous la forme "Unnamed: 0". index=False exclut ces numéros de ligne. Lorsque l’index contient des étiquettes qui ont un sens, conserve-le et relis-le avec index_col=0.

Les valeurs manquantes deviennent normalement des champs vides. na_rep="NA" les rend visibles, mais le lecteur destinataire doit interpréter correctement ce marqueur. Dans un tableau de villes avec Lyon à 21,5 °C et Osaka à 18,25 °C, une valeur de précipitations manquante pour Osaka doit rester distincte de précipitations nulles.

Adapter la convention textuelle au destinataire

df.to_csv(
    "weather_export.csv",
    index=False,
    sep=";",
    decimal=",",
    na_rep="NA",
    date_format="%Y-%m-%d",
    encoding="utf-8"
)

Les options de séparateur et de décimale produisent des valeurs comme Lyon;21,5;0,0. La sortie de dates ISO évite toute ambiguïté entre le jour et le mois. Utilise encoding="utf-8-sig" lorsque le tableur destinataire a besoin d’une BOM pour reconnaître UTF-8.

float_format="%.1f" écrit une décimale. La valeur 18,25 devient "18.2" avec ce formatage, et les décimales supprimées ne peuvent pas être récupérées depuis le CSV. Garde toutes les décimales dans les données d’analyse ; crée un rapport arrondi distinct si nécessaire.

Vérifier ce qui est conservé après un aller-retour

Le CSV stocke des caractères sans métadonnées sur les types de données pandas. Considérons quatre colonnes : un identifiant "02139", une date et heure, une catégorie ordonnée A < B < C et des entiers nullables avec une valeur manquante. Une lecture CSV par défaut peut renvoyer l’entier 2 139, la date sous forme de texte, de simples étiquettes de catégorie sans leur ordre et des nombres à virgule flottante pour les effectifs.

Une lecture qui se termine sans erreur n’a donc pas forcément restauré le DataFrame d’origine. Conserve les options nécessaires pour reconstituer les données, notamment les identifiants textuels, la conversion des dates et les marqueurs de valeurs manquantes. L’ordre des catégories doit aussi être défini à nouveau. Pour des analyses répétées où ces types comptent, Parquet peut les préserver directement.

Ajouter des enregistrements et protéger les données brutes

df.to_csv(
    "daily_results.csv",
    mode="a",
    header=False,
    index=False
)

Cela ajoute des lignes à un fichier existant. Garde un ordre des colonnes et des conventions cohérents avec ce fichier. Avec header=True, un ajout écrit un autre en-tête au milieu, et la lecture suivante peut le traiter comme un enregistrement. Pour un nouveau fichier, écris l’en-tête une fois avant les ajouts ultérieurs.

Conserve les fichiers reçus ou téléchargés inchangés dans un emplacement réservé aux données brutes. Écris séparément les résultats calculés sous des noms descriptifs. Après avoir rouvert un fichier traité exporté, vérifie son nombre de lignes, ses colonnes, ses valeurs manquantes et des valeurs représentatives, notamment les zéros initiaux et les dates.

Le meilleur format de stockage dépend de la personne ou du programme qui lira ensuite les données et de ce qui doit être conservé pendant l’échange. Un tableau envoyé à un collègue, une réponse d’API imbriquée et un jeu de données d’analyse typé ont des besoins différents.

Comparer le stockage textuel et binaire

Les formats textuels encodent des caractères visibles. CSV est facile à examiner et largement pris en charge ; JSON représente naturellement les objets et tableaux imbriqués. CSV ne possède pas de schéma des types de colonnes, et les types de valeurs JSON ordinaires ne préservent pas tous les types de données pandas. Leur relecture nécessite une analyse et peut demander des choix explicites de types.

Les formats binaires encodent les données pour une lecture directe par des logiciels. Des formats comme Parquet et Feather stockent un schéma décrivant les colonnes et leurs types, ce qui réduit le besoin d’inférer à nouveau les types. La prise en charge des types dépend toutefois du format et du lecteur : des objets Python arbitraires ne deviennent pas portables simplement parce que le fichier est binaire.

Une organisation orientée par lignes conserve ensemble les champs d’un enregistrement. Une organisation en colonnes conserve ensemble les valeurs d’une même colonne. Une analyse a souvent besoin de quelques colonnes sur de nombreuses lignes : les lecteurs de formats en colonnes peuvent donc ignorer les colonnes inutiles. Les valeurs similaires adjacentes se compressent aussi bien. La taille des fichiers et la vitesse dépendent des données ; le résultat de compression d’un tableau n’est pas un rapport fixe valable pour tous les tableaux.

Associer chaque format à une tâche

Parquet est un format ouvert utilisé par pandas, R, Spark et DuckDB. Feather utilise Arrow IPC et convient aux échanges rapides entre Python et R ou entre des étapes locales. to_feather et read_feather permettent cet échange. HDF5 regroupe plusieurs jeux de données dans un fichier ; to_hdf de pandas nécessite PyTables.

Comprendre la limite de confiance de pickle

pickle peut enregistrer des objets Python au-delà des tableaux ordinaires, mais son chargement peut exécuter du code. Ne charge jamais un fichier pickle provenant d’une source non fiable. Utilise-le pour tes propres objets de courte durée et prévois des limites de compatibilité lorsque Python et les bibliothèques évoluent. Par exemple, pandas 3 ne prend plus en charge la lecture de fichiers pickle créés avec des versions de pandas antérieures à 1.0.

Décider selon le résultat attendu

Si un destinataire doit examiner un petit tableau sans outils particuliers, CSV est pratique. S’il a besoin de feuilles de classeur nommées, utilise Excel. Si tu dois préserver les identifiants, les catégories et les types nullables entre les sessions d’analyse, choisis Parquet. Si plusieurs programmes doivent interroger et mettre à jour des enregistrements partagés, une base de données convient mieux que l’échange de copies d’un fichier. Le choix du format dépend de l’utilisation suivante, pas de l’extension du fichier d’entrée d’origine.

Parquet stocke un tableau avec les types de ses colonnes dans un format ouvert en colonnes. Il est utile lorsqu’un DataFrame vérifié doit être chargé plusieurs fois ou transmis à d’autres outils d’analyse. pandas utilise PyArrow pour les exemples ci-dessous.

Écrire et vérifier un aller-retour avec conservation des types

df.to_parquet("sales.parquet", engine="pyarrow")
restored = pd.read_parquet("sales.parquet", engine="pyarrow")
print(restored.dtypes)

Un identifiant textuel "02139", une colonne de dates et heures, une catégorie ordonnée et des entiers nullables peuvent tous conserver leurs types lors de cet aller-retour de pandas à PyArrow puis à pandas. Contrairement à une lecture CSV, il n’est pas nécessaire de deviner le rôle de l’identifiant ni de recréer l’ordre des catégories. Examine les types et des valeurs représentatives lorsque tu utilises un nouveau programme d’écriture ou de lecture.

L’option par défaut index=None stocke un RangeIndex de manière compacte sous forme de métadonnées. Un autre index est écrit comme colonnes et restauré à la lecture. Utilise index=False lorsque l’index n’est pas nécessaire. Ce choix concerne les étiquettes de lignes indépendamment des colonnes ordinaires du tableau.

Lire moins de données et choisir la compression

small = pd.read_parquet(
    "sales.parquet",
    columns=["zip", "amount"]
)

Le lecteur peut récupérer uniquement ces colonnes depuis le stockage. Cela diffère du chargement du tableau entier suivi d’une sélection, car toute la lecture a alors déjà eu lieu. La sélection de colonnes est particulièrement utile pour les tableaux larges.

Snappy est le codec de compression par défaut. compression="zstd" ou "gzip" demande souvent plus de travail à l’écriture en échange d’un stockage plus compact, tandis que compression=None écrit des données non compressées. Mesure ce compromis avec des données représentatives : les étiquettes répétées et les mesures aléatoires ne se compressent pas de la même façon. Installe PyArrow ; le moteur alternatif fastparquet est obsolète dans pandas 3.1.

Organiser un jeu de données en partitions

df.to_parquet(
    "sales_dataset",
    engine="pyarrow",
    partition_cols=["year"],
    index=False
)
recent = pd.read_parquet(
    "sales_dataset",
    filters=[("year", "==", 2026)]
)

La destination est un répertoire contenant des sous-répertoires comme year=2025 et year=2026. La lecture du répertoire charge le jeu de données ; un filtre peut éviter les partitions sans rapport avec la sélection. Avec cette organisation, PyArrow déduit les valeurs de year des noms de répertoires et pandas reçoit généralement une colonne de partition catégorielle.

Choisis une colonne de partition comportant un petit ensemble de valeurs utiles sur lesquelles tu filtres souvent. Un identifiant unique d’enregistrement crée des milliers de minuscules partitions, ce qui augmente le travail sur les fichiers et les répertoires. L’année ou un petit ensemble de régions offre souvent une répartition plus pratique.

Ajouter des données sans corrompre le jeu de données

Un fichier Parquet unique ne permet pas l’ajout de lignes à la manière d’un CSV avec pandas. Écris de nouveaux fichiers ou de nouvelles partitions dans le répertoire du jeu de données, ou lis, combine et réécris un fichier unique. Les fichiers d’un même jeu de données doivent avoir des schémas compatibles. Si l’un stocke un code comme texte et un autre comme entier, le chargement peut échouer ou convertir les valeurs. Définis des types de données cohérents avant d’écrire chaque partie et vérifie qu’une partition ajoutée ne crée pas de copies des mêmes enregistrements déjà présents.

Une base de données relationnelle stocke des enregistrements dans des tables aux colonnes nommées. Un programme envoie une requête SQL par une connexion et reçoit un résultat que pandas peut transformer en DataFrame. La base peut sélectionner uniquement les données nécessaires avant leur transfert vers Python.

Commencer avec un fichier SQLite

import sqlite3
import pandas as pd

con = sqlite3.connect("shop.db")
try:
    df = pd.read_sql_query(
        "SELECT region, amount FROM sales", con
    )
finally:
    con.close()

SQLite fonctionne sans serveur distinct et stocke une base de données dans un fichier. La connexion crée le fichier s’il n’existe pas : une erreur dans le chemin peut donc ouvrir une nouvelle base vide au lieu de celle attendue. ":memory:" crée une base temporaire en mémoire. La requête ci-dessus renvoie les colonnes region et amount d’une table sales existante ; les noms des colonnes du résultat deviennent les étiquettes du DataFrame.

Le bloc with d’une connexion SQLite gère une transaction, mais ne ferme pas la connexion. Appelle explicitement close() une fois le travail terminé. Un bloc try/finally ferme la connexion même si la lecture déclenche une erreur.

Utiliser un moteur pour une base de données serveur

SQLAlchemy fournit des moteurs pour des systèmes comme PostgreSQL, MySQL et SQL Server, avec un pilote adapté installé. Une URL de connexion indique le dialecte, le pilote, le serveur et la base de données. Conserve-la dans une variable d’environnement :

import os
from sqlalchemy import create_engine

engine = create_engine(os.environ["ANALYSIS_DB_URL"])
try:
    with engine.connect() as conn:
        df = pd.read_sql_query(
            "SELECT region, amount FROM sales", conn
        )
finally:
    engine.dispose()

Le contexte de connexion rend la connexion au pool du moteur. dispose() libère les ressources du pool lorsque le moteur n’est plus nécessaire. Utilise un compte en lecture seule pour l’analyse et conserve les identifiants hors des notebooks et du suivi de versions. Une URL de moteur pour un fichier SQLite local peut être "sqlite:///shop.db".

Choisir le lecteur adapté à l’entrée

Avec une connexion sqlite3 simple, passe une requête complète. pd.read_sql("sales", con) envoie sales comme du SQL et échoue ; utilise plutôt pd.read_sql_query("SELECT * FROM sales", con). pandas prend en charge les connexions SQLAlchemy, ADBC et SQLite ; une connexion directe par un pilote quelconque ne constitue pas un substitut pris en charge simplement parce que le pilote peut exécuter du SQL.

Transférer le résultat nécessaire

Une requête qui renvoie une sélection de lignes et de colonnes transfère moins de données que la lecture d’une table entière suivie de la suppression de la majeure partie dans pandas. La requête fournie SELECT SUM(amount) AS total FROM sales renvoie une valeur agrégée, nommée total. La lecture d’un résultat de requête ne modifie pas la table stockée. Après le chargement, vérifie le nombre de lignes et les types comme tu le ferais pour un fichier ; les types déclarés dans la base et les types renvoyés par pandas sont liés, mais ne sont pas identiques.

Les valeurs variables doivent être placées dans des paramètres de requête. L’instruction SQL définit l’opération ; les paramètres liés fournissent la région, le seuil ou toute autre valeur utilisée pour cette exécution. Cela préserve la structure de la requête même lorsqu’une valeur contient un guillemet.

Lier les valeurs avec la syntaxe de la connexion

Pour SQLite :

query = "SELECT region, amount, sold_on FROM sales WHERE amount > ? ORDER BY amount DESC"
df = pd.read_sql_query(query, con, params=(70,))

Pour les montants des ventes 120,0 ; 75,5 ; 60,0 et 210,0, cela renvoie 210,0 ; 120,0 et 75,5 par ordre décroissant. Le tuple (70,) contient un élément ; (70) est simplement le nombre 70. SQLite accepte aussi les marqueurs de paramètres nommés, par exemple WHERE region = :r avec params={"r": "North"}.

Les règles des marqueurs de paramètres dépendent de l’interface. psycopg utilise %s ou %(name)s. Avec SQLAlchemy, place une instruction dans text et utilise des paramètres nommés :

from sqlalchemy import text

query = text("SELECT region, amount FROM sales WHERE amount >= :m")
with engine.connect() as conn:
    df = pd.read_sql_query(query, conn, params={"m": 100})

Passe les valeurs par params ; n’utilise pas le formatage Python pour les insérer dans l’instruction.

Comprendre ce que protège le paramétrage

Supposons qu’un code construise une condition avec une chaîne f et une entrée "x' OR '1'='1". La coller entre guillemets transforme la condition en region = 'x' OR '1'='1', ce qui correspond à toutes les lignes. C’est une injection SQL : une valeur est devenue une partie exécutable de la structure de la requête.

Un paramètre lié est comparé comme une seule valeur : cette même chaîne ne correspond donc qu’à une région portant littéralement ce texte. La liaison gère aussi les noms ordinaires contenant des apostrophes sans avoir à construire soi-même leur échappement. La règle s’applique aux entrées provenant de fichiers comme aux formulaires utilisateur.

Les paramètres représentent des valeurs, pas des noms de tables ou de colonnes. Un paramètre à la place d’un nom de table ne sélectionne pas cette table. Lorsqu’un programme a besoin d’un identifiant variable, choisis-le dans une liste fixe contrôlée par le code.

Maîtriser les types du résultat

SQLite stocke souvent les dates comme texte. Demande à pandas de les convertir :

df = pd.read_sql_query(
    "SELECT sold_on, visits FROM observations", con,
    parse_dates=["sold_on"],
    dtype={"visits": "Int64"}
)

La colonne de dates devient une colonne de dates et heures, et une colonne d’effectifs contenant des NULL SQL utilise des entiers nullables au lieu de devenir une colonne à virgule flottante uniquement pour représenter les valeurs manquantes. Examine le résultat pour vérifier la conversion.

Distinguer les blocs de la mise en mémoire tampon du pilote

chunksize=1000 renvoie un itérateur de DataFrame contenant chacun au plus 1 000 lignes. Un résultat de quatre lignes avec chunksize=3 donne des blocs de trois et une ligne. Garde la connexion ouverte pendant leur traitement. Certains pilotes de base de données mettent quand même tout le résultat en mémoire tampon avant que pandas ne produise les blocs ; un curseur côté serveur ou une configuration de lecture en flux peut aussi être nécessaire pour limiter la mémoire utilisée sur l’ensemble du parcours de connexion.

to_sql crée une table de base de données à partir d’un DataFrame ou écrit des lignes dans une table existante. Ses options déterminent si les données existantes sont conservées, si l’index devient une colonne et comment un ensemble d’écritures est validé.

Choisir le comportement pour une table existante

df.to_sql("sales", con, index=False)

L’option par défaut if_exists="fail" arrête l’opération lorsque sales existe déjà. Ne choisis un autre mode que si son effet correspond au chargement voulu :

delete_rows est disponible dans pandas 3. Remplacer une table supprime son ancienne définition, notamment les clés, index et contraintes ; les autorisations propres à la base de données peuvent aussi être affectées. Supprimer les lignes conserve la définition, mais efface quand même tous les enregistrements existants. Utilise ce mode pour un rechargement complet voulu, pas lorsque le DataFrame ne contient qu’un nouveau lot.

Définir les colonnes et écrire dans une transaction

Par défaut, l’index du DataFrame est écrit comme colonne. Un index sans nom devient index ; un index nommé conserve son nom. index_label lui donne un nom explicite et index=False l’exclut. Si un identifiant est déjà une colonne ordinaire, écrire les numéros de ligne par défaut n’ajoute généralement aucune information utile.

Avec SQLAlchemy, dtype peut choisir les types de la base de données :

from sqlalchemy import types

with engine.begin() as conn:
    df.to_sql(
        "sales", conn,
        if_exists="append",
        index=False,
        dtype={"sold_on": types.Date()},
        chunksize=1000
    )

engine.begin() valide la transaction si le bloc se termine correctement et l’annule en cas d’exception. Pour une table existante, le schéma stocké continue de déterminer quelles valeurs peuvent être insérées ; dtype n’est pas une commande de modification de ses colonnes. Les garanties de transaction dépendent aussi de la prise en charge des opérations utilisées par la base de données. L’ajout dans une transaction SQLAlchemy regroupe les insertions de l’exemple.

chunksize regroupe les lignes en lots. method="multi" place plusieurs lignes dans une instruction INSERT lorsque cette option est prise en charge. Elle peut améliorer ou réduire les performances selon la base de données et la taille des lots : mesure-les donc avec des données représentatives.

Vérifier l’augmentation, pas seulement la fin de l’opération

check = pd.read_sql_query("SELECT COUNT(*) AS n FROM sales", con)
print(check["n"].iloc[0])

Pour une table nouvelle ou entièrement rechargée, compare le nombre à len(df). Pour un ajout, compare l’augmentation : une table de quatre lignes qui reçoit deux lignes doit en contenir six. Le nombre de lignes renvoyé par to_sql provient du pilote ; vérifie directement les données stockées.

Exécuter deux fois un ajout répète les enregistrements, sauf si la base refuse les doublons ou si le programme ne sélectionne que les nouveaux enregistrements. Décide si l’opération est un rechargement complet ou un ajout de nouveaux enregistrements avant de la relancer. Une transaction empêche un chargement partiel en cas d’échec ; elle ne rend pas uniques les ajouts répétés qui réussissent.