Di Jerry Fan

JSONL in Python: lettura, scrittura e parsing

Una guida completa per lavorare con i file JSONL (JSON Lines) in Python. Impara a leggere, scrivere, interpretare ed elaborare in streaming i dati JSONL con i moduli della libreria standard, pandas e librerie ad alte prestazioni.

Perché usare Python per JSONL?

Python è il linguaggio più usato per lavorare con i file JSONL, e a ragione. Il modulo json della libreria standard permette di fare il parsing dei dati JSON senza installare nulla, l’iterazione sui file consuma poca memoria già per impostazione predefinita e l’ecosistema offre librerie potenti come pandas e orjson per esigenze specifiche. Che tu debba elaborare dataset per il machine learning, log applicativi o risposte di API, Python semplifica la gestione dei file JSONL.

Il formato JSONL (JSON Lines) memorizza un oggetto JSON per riga: è quindi ideale per lo streaming, per i log in modalità append-only e per elaborare dataset di grandi dimensioni senza caricarli interamente in memoria. La lettura dei file riga per riga in Python si presta perfettamente a questo formato. In questa guida imparerai tre modi per leggere i file JSONL, due per scriverli e come gestire i file che non entrano interamente in memoria.

Leggere file JSONL in Python

Esistono diversi modi per leggere i file JSONL in Python, ciascuno adatto a esigenze diverse. Il modulo json della libreria standard va bene nella maggior parte dei casi, pandas è comodo per analizzare dati tabulari e i generatori sono la scelta migliore per i file di grandi dimensioni.

Il metodo più semplice usa il modulo json della libreria standard di Python. Apri il file, scorri le righe e fai il parsing di ciascuna con json.loads(). Con questo approccio, tutti i record vengono caricati in una lista in memoria.

Lettura di base con il modulo 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])

Se i dati JSONL sono tabulari, cioè hanno le stesse chiavi in ogni record, pandas può caricarli direttamente in un DataFrame con una sola chiamata a funzione. È il modo più rapido per iniziare ad analizzare dati JSONL strutturati.

Lettura con 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}')

Per i file che non entrano interamente in memoria, usa una funzione generatore. Questa produce un record alla volta, mantenendo costante il consumo di memoria indipendentemente dalle dimensioni del file. È l’approccio consigliato per le pipeline di elaborazione dati in produzione.

Usare un generatore per i file di grandi dimensioni
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

Scrivere file JSONL in Python

Scrivere un file JSONL è semplice: serializza ogni record in una stringa JSON e aggiungi un carattere di fine riga. La regola fondamentale è avere un oggetto JSON per riga, senza virgole finali e senza racchiudere gli oggetti in un array.

Usa json.dumps() per serializzare ogni record, poi scrivilo seguito da un carattere di fine riga. Imposta ensure_ascii=False per mantenere nell’output i caratteri Unicode, come quelli cinesi e giapponesi o le emoji.

Scrittura di base con il modulo 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')

Se i dati sono già in un DataFrame pandas, usa to_json() con orient='records' e lines=True per esportarli direttamente in formato JSONL. È l’operazione inversa di pd.read_json() con lines=True.

Scrittura con 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')

Librerie Python per JSONL

Python offre diverse librerie per il parsing JSON, con prestazioni differenti. La scelta dipende dalle dimensioni dei file e dalle prestazioni di cui hai bisogno.

json (stdlib)

Integrato

Il modulo json della libreria standard di Python non richiede installazione e funziona ovunque. È sufficiente per la maggior parte delle elaborazioni JSONL e supporta tutti i tipi di dati previsti dallo standard JSON. Le prestazioni sono adeguate per file fino a qualche centinaio di MB.

orjson

Più veloce

orjson è la libreria JSON più veloce per Python ed è scritta in Rust. Il parsing e la serializzazione sono da 2 a 10 volte più veloci rispetto al modulo json della libreria standard. Restituisce bytes anziché stringhe e supporta nativamente dataclasses, datetime, numpy e i tipi UUID.

ujson

Veloce

ujson (UltraJSON) è una libreria JSON scritta in C, da 2 a 5 volte più veloce del modulo json della libreria standard. La sua API è quasi identica a quella del modulo json, quindi può sostituirlo direttamente. È un buon compromesso tra compatibilità e velocità.

Elaborare in streaming file JSONL di grandi dimensioni

Quando elabori file JSONL nell’ordine dei gigabyte, serve un approccio in streaming che legga, trasformi e scriva i dati in batch. In questo modo il consumo di memoria rimane costante e puoi seguire l’avanzamento dell’elaborazione.

Elaborare in streaming file JSONL di grandi dimensioni
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)

Questo approccio mantiene costante il consumo di memoria elaborando i record in batch di dimensioni fisse. Il parametro batch_size permette di bilanciare il consumo di memoria e l’efficienza delle operazioni di I/O. Sulla maggior parte dei sistemi, i batch da 1.000 a 10.000 record danno buoni risultati. L’indicatore di avanzamento aiuta a monitorare le elaborazioni più lunghe.

Lavora con i file JSONL online

Visualizza, valida e converti file JSONL fino a 1GB direttamente nel browser. Non devi caricare alcun file: la tua privacy è garantita al 100%.

Domande frequenti

Riferimenti