Par Jerry Fan

JSONL en Python : lire, écrire et parser des fichiers

Un guide complet pour manipuler des fichiers JSONL (JSON Lines) en Python. Apprenez à lire, écrire, parser et traiter en streaming des données JSONL avec les modules intégrés, pandas et des bibliothèques hautes performances.

Pourquoi utiliser Python pour manipuler du JSONL ?

Python est le langage le plus utilisé pour manipuler des fichiers JSONL, et ce n’est pas un hasard. Son module intégré json permet de parser du JSON sans rien installer, le parcours des fichiers consomme peu de mémoire par défaut, et son écosystème propose des bibliothèques puissantes comme pandas et orjson pour des traitements spécialisés. Que vous traitiez des jeux de données de machine learning, des logs applicatifs ou des réponses d’API, Python simplifie la manipulation du JSONL.

Le format JSONL (JSON Lines) stocke un objet JSON par ligne. Il se prête donc particulièrement bien au streaming, à la journalisation par ajout uniquement et au traitement de grands jeux de données sans tout charger en mémoire. La lecture des fichiers ligne par ligne en Python convient parfaitement à ce format. Ce guide présente trois méthodes pour lire du JSONL, deux pour en écrire, ainsi que les techniques à utiliser lorsque les fichiers sont trop volumineux pour tenir en mémoire.

Lire des fichiers JSONL en Python

Il existe plusieurs façons de lire des fichiers JSONL en Python, selon vos besoins. Le module standard json convient à la plupart des cas, pandas facilite l’analyse de données tabulaires et les générateurs sont la meilleure solution pour les fichiers volumineux.

La méthode la plus simple repose sur le module json intégré à Python. Ouvrez le fichier, parcourez-le ligne par ligne et parsez chaque ligne avec json.loads(). Cette méthode charge tous les enregistrements dans une liste en mémoire.

Lecture simple avec le module json
import json


records = []
with open('data.jsonl', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.strip()
        if line:  # Skip empty lines
            records.append(json.loads(line))


print(f'Loaded {len(records)} records')
print(records[0])

Si vos données JSONL sont tabulaires (avec les mêmes clés dans chaque enregistrement), pandas peut les charger directement dans un DataFrame en un seul appel de fonction. C’est le moyen le plus rapide de commencer à analyser des données JSONL structurées.

Lecture avec pandas
import pandas as pd


# Read entire file into a DataFrame
df = pd.read_json('data.jsonl', lines=True)
print(df.head())
print(f'Shape: {df.shape}')


# For large files, read in chunks
chunks = pd.read_json('large.jsonl', lines=True, chunksize=10000)
for chunk in chunks:
    # Process each chunk (DataFrame)
    print(f'Chunk shape: {chunk.shape}')

Pour les fichiers trop volumineux pour tenir en mémoire, utilisez une fonction génératrice. Elle fournit un enregistrement à la fois : la consommation de mémoire reste ainsi constante, quelle que soit la taille du fichier. Cette approche est recommandée pour les pipelines de données en production.

Utiliser un générateur pour les fichiers volumineux
import json
from typing import Iterator, Any


def read_jsonl(path: str) -> Iterator[dict[str, Any]]:
    """Read a JSONL file lazily, yielding one record at a time."""
    with open(path, 'r', encoding='utf-8') as f:
        for line_num, line in enumerate(f, 1):
            line = line.strip()
            if not line:
                continue
            try:
                yield json.loads(line)
            except json.JSONDecodeError as e:
                print(f'Skipping invalid JSON at line {line_num}: {e}')


# Process records one at a time
for record in read_jsonl('large_data.jsonl'):
    process(record)  # Only one record in memory at a time

Écrire des fichiers JSONL en Python

Pour écrire un fichier JSONL, il suffit de sérialiser chaque enregistrement sous forme de chaîne JSON, puis d’ajouter un caractère de saut de ligne. La règle essentielle : un objet JSON par ligne, sans virgule à la fin ni tableau englobant l’ensemble des objets.

Utilisez json.dumps() pour sérialiser chaque enregistrement, puis écrivez le résultat suivi d’un saut de ligne. Passez ensure_ascii=False pour conserver les caractères Unicode, comme les caractères chinois, japonais ou les émojis, dans le fichier de sortie.

Écriture simple avec le module json
import json


records = [
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
]


with open('output.jsonl', 'w', encoding='utf-8') as f:
    for record in records:
        f.write(json.dumps(record, ensure_ascii=False) + '\n')


print(f'Wrote {len(records)} records to output.jsonl')

Si vos données se trouvent déjà dans un DataFrame pandas, utilisez to_json() avec orient='records' et lines=True pour les exporter directement au format JSONL. C’est l’opération inverse de pd.read_json() avec lines=True.

Écriture avec pandas
import pandas as pd


df = pd.DataFrame([
    {"id": 1, "name": "Alice", "age": 30},
    {"id": 2, "name": "Bob", "age": 25},
    {"id": 3, "name": "Charlie", "age": 35},
])


# Write DataFrame to JSONL
df.to_json('output.jsonl', orient='records', lines=True, force_ascii=False)


print(f'Wrote {len(df)} records to output.jsonl')

Bibliothèques Python pour JSONL

Python propose plusieurs bibliothèques pour parser du JSON, avec des performances différentes. Le choix dépend de la taille de vos fichiers et de vos besoins en matière de performances.

json (stdlib)

Intégré

Le module json intégré à Python ne nécessite aucune installation et fonctionne partout. Il suffit pour la plupart des traitements JSONL et prend en charge tous les types JSON standard. Ses performances conviennent aux fichiers allant jusqu’à quelques centaines de Mo.

orjson

La plus rapide

Écrite en Rust, orjson est la bibliothèque JSON la plus rapide pour Python. Le parsing et la sérialisation sont 2 à 10 fois plus rapides qu’avec le module standard json. Elle renvoie des bytes plutôt que des chaînes de caractères et prend en charge nativement les dataclasses, datetime, numpy et les types UUID.

ujson

Rapide

ujson (UltraJSON) est une bibliothèque JSON écrite en C, 2 à 5 fois plus rapide que le module standard json. Son API est presque identique à celle du module intégré json, ce qui permet de le remplacer directement. C’est un bon compromis entre compatibilité et rapidité.

Traiter des fichiers JSONL volumineux en streaming

Pour traiter des fichiers JSONL de plusieurs gigaoctets, adoptez une approche en streaming : lisez, transformez et écrivez les données par lots. La consommation de mémoire reste ainsi constante et vous pouvez suivre la progression du traitement.

Traiter des fichiers JSONL volumineux en streaming
import json
import sys


def process_large_jsonl(
    input_path: str,
    output_path: str,
    batch_size: int = 1000
) -> int:
    """Stream-process a large JSONL file in batches."""
    processed = 0
    batch: list[dict] = []


    with open(input_path, 'r') as fin, \
         open(output_path, 'w') as fout:
        for line in fin:
            line = line.strip()
            if not line:
                continue
            record = json.loads(line)
            # Transform the record
            record['processed'] = True
            batch.append(record)


            if len(batch) >= batch_size:
                for r in batch:
                    fout.write(json.dumps(r) + '\n')
                processed += len(batch)
                batch.clear()
                print(f'\rProcessed {processed} records...', end='')


        # Write remaining records
        for r in batch:
            fout.write(json.dumps(r) + '\n')
        processed += len(batch)


    print(f'\nDone. Processed {processed} records total.')
    return processed


# Usage
process_large_jsonl('input.jsonl', 'output.jsonl', batch_size=5000)

Cette approche maintient une consommation de mémoire constante en traitant les enregistrements par lots de taille fixe. Le paramètre batch_size permet d’ajuster le compromis entre consommation de mémoire et efficacité des entrées-sorties. Sur la plupart des systèmes, des lots de 1 000 à 10 000 enregistrements conviennent bien. L’indicateur de progression permet de suivre les traitements longs.

Manipulez des fichiers JSONL en ligne

Consultez, validez et convertissez des fichiers JSONL jusqu’à 1 Go directement dans votre navigateur. Aucun fichier à envoyer sur un serveur : vos données restent 100% privées.

Questions fréquentes

Références