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.
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.
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.
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 timeScrivere 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.
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.
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)
IntegratoIl 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ù veloceorjson è 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
Veloceujson (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.
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.
Prova i nostri strumenti gratuiti per JSONL
Preferisci non scrivere codice? Usa i nostri strumenti online gratuiti per visualizzare, validare e convertire i file JSONL direttamente nel browser.
Strategie per elaborare gigabyte di dati JSONL: lettura in streaming, gestione della memoria, suddivisione dei file, compressione e strumenti online.
Valida i file JSONL riga per riga. Individua subito errori di sintassi e problemi di codifica o di formato.
Impara le best practice per la formattazione dei file JSONL, la coerenza dello schema, la gestione degli errori, l’ottimizzazione delle prestazioni e l’organizzazione dei file. Evita gli errori più comuni con esempi pratici.
Converti i file JSONL in un array JSON standard. Ideale per API e pipeline di elaborazione dei dati.
Scopri come utilizzare il formato JSONL in JavaScript e Node.js.