JSONL en Python: leer, escribir y parsear
Una guía completa para trabajar con archivos JSONL (JSON Lines) en Python. Aprende a leer, escribir, parsear y procesar datos JSONL en streaming con los módulos incluidos en Python, pandas y bibliotecas de alto rendimiento.
¿Por qué usar Python para trabajar con JSONL?
Python es el lenguaje más popular para trabajar con archivos JSONL, y con razón. Incluye el módulo json para parsear JSON sin instalar nada, permite recorrer archivos con un uso eficiente de la memoria y cuenta con bibliotecas potentes como pandas y orjson para tareas más específicas. Tanto si procesas datasets de aprendizaje automático como logs de aplicaciones o respuestas de API, Python te facilita el trabajo con JSONL.
JSONL (JSON Lines) almacena un objeto JSON por línea, por lo que resulta ideal para el procesamiento en streaming, los logs en los que solo se añaden registros y el procesamiento de grandes datasets sin cargarlos por completo en memoria. La lectura de archivos línea a línea en Python encaja perfectamente con este formato. En esta guía aprenderás tres formas de leer JSONL, dos de escribirlo y cómo trabajar con archivos que no caben en memoria.
Leer archivos JSONL en Python
Hay varias formas de leer archivos JSONL en Python, según lo que necesites. El módulo estándar json sirve para la mayoría de los casos, pandas facilita el análisis de datos tabulares y los generadores son la mejor opción para archivos grandes.
La forma más sencilla es usar el módulo json incluido en Python. Abre el archivo, recórrelo línea a línea y parsea cada línea con json.loads(). Este método carga todos los registros en una lista en 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])Si tus datos JSONL son tabulares (todos los registros tienen las mismas claves), pandas puede cargarlos directamente en un DataFrame con una sola llamada a una función. Es la forma más rápida de empezar a analizar datos JSONL estructurados.
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}')Para trabajar con archivos que no caben en memoria, usa una función generadora. Así obtienes los registros de uno en uno y mantienes constante el consumo de memoria, independientemente del tamaño del archivo. Este es el patrón recomendado para los pipelines de datos en producción.
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 timeEscribir archivos JSONL en Python
Escribir archivos JSONL es sencillo: serializa cada registro como una cadena JSON y añade un salto de línea. La regla fundamental es escribir un objeto JSON por línea, sin comas al final ni un array que englobe los objetos.
Usa json.dumps() para serializar cada registro y escríbelo seguido de un salto de línea. Configura ensure_ascii=False para conservar los caracteres Unicode en la salida, como los caracteres chinos, japoneses o los emojis.
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 tus datos ya están en un DataFrame de pandas, usa to_json() con orient='records' y lines=True para exportarlos directamente a JSONL. Es la operación inversa a 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')Bibliotecas de Python para JSONL
Python ofrece varias bibliotecas para parsear JSON, cada una con un rendimiento distinto. La elección depende del tamaño del archivo y del rendimiento que necesites.
json (biblioteca estándar)
Incluido en PythonEl módulo json incluido en Python no requiere instalación y funciona en cualquier entorno. Es suficiente para la mayoría de las tareas con JSONL y admite todos los tipos de datos del estándar JSON. Su rendimiento es adecuado para archivos de hasta unos cientos de MB.
orjson
La más rápidaorjson, escrita en Rust, es la biblioteca de JSON más rápida para Python. El parseo y la serialización son de 2 a 10 veces más rápidos que con el módulo estándar json. Devuelve bytes en lugar de cadenas y admite de forma nativa dataclasses, datetime, numpy y tipos UUID.
ujson
Rápidaujson (UltraJSON) es una biblioteca de JSON escrita en C, de 2 a 5 veces más rápida que el módulo estándar json. Su API es casi idéntica a la de json, por lo que puedes usarla como sustituto directo. Ofrece un buen equilibrio entre compatibilidad y velocidad.
Procesar archivos JSONL grandes en streaming
Para procesar archivos JSONL de varios gigabytes, necesitas leer, transformar y escribir los datos por lotes en streaming. Así mantienes constante el consumo de memoria y puedes seguir el progreso del procesamiento.
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)Este patrón mantiene constante el consumo de memoria al procesar los registros en lotes de tamaño fijo. El parámetro batch_size permite ajustar el equilibrio entre el consumo de memoria y la eficiencia de E/S. En la mayoría de los sistemas funcionan bien los lotes de 1.000 a 10.000 registros. El indicador de progreso permite supervisar las tareas de larga duración.
Prueba nuestras herramientas gratuitas para JSONL
¿Prefieres no escribir código? Usa nuestras herramientas gratuitas online para ver, validar y convertir archivos JSONL directamente en tu navegador.
Estrategias para procesar gigabytes de datos JSONL: lectura en streaming, gestión de memoria, división de archivos, compresión y herramientas online.
Valida archivos JSONL línea por línea. Detecta al instante errores de sintaxis, problemas de codificación y fallos de formato.
Domina las buenas prácticas de JSONL: formato, coherencia del esquema, gestión de errores, optimización del rendimiento y organización de archivos. Evita los errores habituales con ejemplos prácticos.
Convierte archivos JSONL en un array JSON estándar. Ideal para APIs y pipelines de procesamiento de datos.
Aprende a usar el formato JSONL en JavaScript y Node.js.