Autor: Jerry Fan

JSONL w Pythonie: odczyt, zapis i parsowanie

Kompletny przewodnik po pracy z plikami JSONL (JSON Lines) w Pythonie. Dowiedz się, jak odczytywać, zapisywać, parsować i przetwarzać strumieniowo dane JSONL za pomocą wbudowanych modułów, pandas i bibliotek o wysokiej wydajności.

Dlaczego warto pracować z JSONL w Pythonie?

Python jest najpopularniejszym językiem do pracy z plikami JSONL — i nie bez powodu. Wbudowany moduł json pozwala od razu parsować JSON, iterowanie po pliku domyślnie zużywa niewiele pamięci, a biblioteki takie jak pandas i orjson ułatwiają bardziej specjalistyczne zadania. Niezależnie od tego, czy przetwarzasz zbiory danych do uczenia maszynowego, logi aplikacji czy odpowiedzi API, obsługa JSONL w Pythonie jest prosta.

W formacie JSONL (JSON Lines) każda linia zawiera jeden obiekt JSON. Dzięki temu format ten świetnie nadaje się do przetwarzania strumieniowego, dopisywania kolejnych wpisów do logów oraz przetwarzania dużych zbiorów danych bez wczytywania ich w całości do pamięci. Odczyt plików linia po linii w Pythonie doskonale pasuje do tego formatu. W tym przewodniku poznasz trzy sposoby odczytu JSONL, dwa sposoby zapisu oraz metody pracy z plikami, które nie mieszczą się w pamięci.

Odczyt plików JSONL w Pythonie

Pliki JSONL można odczytywać w Pythonie na kilka sposobów, zależnie od potrzeb. Standardowy moduł json sprawdza się w większości zastosowań, pandas ułatwia analizę danych tabelarycznych, a generatory najlepiej nadają się do dużych plików.

Najprościej skorzystać z wbudowanego modułu json. Otwórz plik, przejdź po nim linia po linii i sparsuj każdą z nich za pomocą json.loads(). W tym rozwiązaniu wszystkie rekordy trafiają do listy przechowywanej w pamięci.

Prosty odczyt za pomocą modułu 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])

Jeśli dane JSONL mają strukturę tabelaryczną (każdy rekord ma te same klucze), pandas pozwala wczytać je bezpośrednio do obiektu DataFrame jednym wywołaniem funkcji. To najszybszy sposób, by rozpocząć analizę ustrukturyzowanych danych JSONL.

Odczyt za pomocą 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}')

Jeśli plik nie mieści się w pamięci, użyj funkcji generatorowej. Udostępnia ona po jednym rekordzie, dzięki czemu zużycie pamięci pozostaje stałe niezależnie od rozmiaru pliku. To zalecane podejście w produkcyjnych procesach przetwarzania danych.

Generator do odczytu dużych plików
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

Zapis plików JSONL w Pythonie

Zapis plików JSONL jest prosty: serializuj każdy rekord do ciągu znaków w formacie JSON i dodaj znak nowej linii. Najważniejsza zasada: jeden obiekt JSON na linię, bez przecinków na końcu i bez ujmowania całości w tablicę.

Użyj json.dumps(), aby zserializować każdy rekord, a następnie zapisz go i dodaj znak nowej linii. Ustaw ensure_ascii=False, aby zachować w wyniku znaki Unicode, takie jak znaki chińskie, japońskie czy emoji.

Prosty zapis za pomocą modułu 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')

Jeśli dane masz już w obiekcie DataFrame biblioteki pandas, użyj to_json() z orient='records' i lines=True, aby wyeksportować je bezpośrednio do formatu JSONL. To operacja odwrotna do odczytu za pomocą pd.read_json() z lines=True.

Zapis za pomocą 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')

Biblioteki Pythona do pracy z JSONL

W Pythonie dostępnych jest kilka bibliotek do parsowania JSON, które różnią się wydajnością. Wybór zależy od rozmiaru pliku i wymagań dotyczących szybkości przetwarzania.

json (stdlib)

Wbudowany

Wbudowany moduł json jest częścią Pythona, więc nie wymaga osobnej instalacji i działa w każdym środowisku. Wystarcza do większości zadań związanych z JSONL i obsługuje wszystkie standardowe typy JSON. Jego wydajność jest wystarczająca przy plikach o rozmiarze do kilkuset MB.

orjson

Najszybsza

orjson to najszybsza biblioteka do obsługi JSON w Pythonie, napisana w języku Rust. Zapewnia 2-10x szybsze parsowanie i serializację niż standardowy moduł json. Zwraca bajty zamiast ciągów znaków i natywnie obsługuje dataclasses, datetime, numpy oraz typy UUID.

ujson

Szybka

ujson (UltraJSON) to biblioteka do obsługi JSON napisana w C, która działa 2-5x szybciej niż standardowy moduł json. Jej API jest niemal identyczne z API wbudowanego modułu json, więc można jej użyć jako bezpośredniego zamiennika. To dobry kompromis między zgodnością a szybkością.

Strumieniowe przetwarzanie dużych plików JSONL

Przy przetwarzaniu plików JSONL o rozmiarze wielu gigabajtów potrzebujesz podejścia strumieniowego: odczytuj, przekształcaj i zapisuj dane partiami. Dzięki temu zużycie pamięci pozostaje stałe, a postęp pracy można śledzić na bieżąco.

Strumieniowe przetwarzanie dużych plików JSONL
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)

W tym rozwiązaniu rekordy są przetwarzane w partiach o stałym rozmiarze, co zapewnia stałe zużycie pamięci. Parametr batch_size pozwala dobrać proporcje między zużyciem pamięci a wydajnością operacji I/O. W większości systemów dobrze sprawdzają się partie od 1000 do 10 000 rekordów. Wskaźnik postępu ułatwia monitorowanie zadań, które trwają długo.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez przesyłania plików na serwer, z zachowaniem 100% prywatności.

Najczęściej zadawane pytania

Źródła