py-jsoneasy 0.0.5

jsoneasy

A lightweight, dependency-free Python library for JSON Array — read, write, compress incrementally with ease

Documentation · Changelog · Issues

---

jsoneasy provides a simple, Pythonic API for working with JSON Arrays in a memory-efficient way.

It follows the conventions of Python's standard json module — if you know json.dump and json.load, you already know how to use jsoneasy.

Fully compliant with the json specifications.

Features

Feature	Description
🌎 Familiar API	Interface similar to the standard json module (dump, load)
⚡ Streaming by default	Read and write incrementally via iterators, keeping memory usage low
🗜️ Built-in compression	Transparent support for gzip, bzip2, and xz
📦 Archive support	Read and write ZIP and TAR archives (.tar.gz, .tar.bz2, .tar.xz)
📥 Load from URLs	Pass a URL directly to load() or load_archive()
🚀 Customizable serialization	Extend via standard JSONEncoder/JSONDecoder subclasses and extra kwargs
🐍 Zero dependencies	Uses only the Python standard library — nothing else

Installation

pip install py-jsoneasy

Requires Python 3.8+. No external dependencies.

Quick Start

Write

import jsoneasy

data = [
    {"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]},
    {"name": "May", "wins": []},
]

jsoneasy.dump(data, "players.json")

Read

import jsoneasy

for item in jsoneasy.load("players.json"):
    print(item)

Read from a URL

import jsoneasy

for item in jsoneasy.load("https://restcountries.com/v3.1/all?fields=name,capital"):
    print(item)

Compressed files

The compression format is determined automatically — by file extension when writing, and by magic numbers when reading if the file extension is not recognized:

import jsoneasy

data = [{"key": "value"}]

jsoneasy.dump(data, "file.json.gz")  # gzip
jsoneasy.dump(data, "file.json.bz2")  # bzip2
jsoneasy.dump(data, "file.json.xz")  # xz

for item in jsoneasy.load("file.json.gz"):
    print(item)

Archives (ZIP / TAR)

import jsoneasy

# Write multiple files into an archive
data = [
    ("users.json", [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]),
    ("orders.json", [{"id": 1, "total": 99.90}, {"id": 2, "total": 45.00}]),
]
jsoneasy.dump_archive("data.zip", data)

# Read them back from the archive
for filename, items in jsoneasy.load_archive("data.zip", pattern="*.json"):
    print(f"--- {filename} ---")
    for item in items:
        print(item)

Multiple output files

import jsoneasy

data = [
    ("file1.json", [{"name": "Alice"}, {"name": "Bob"}]),
    ("file2.json", [{"name": "Charlie"}]),
    ("file1.json", [{"name": "Eve"}]),  # appended to file1.json
]

jsoneasy.dump_fork(data)

API Overview

Reading

Function	Description
jsoneasy.load(source, **kw)	Read from a file, URL, or file-like object
jsoneasy.load_archive(file, **kw)	Unpack JSON files from a ZIP or TAR archive

Writing

Function	Description
jsoneasy.dump(iterable, file, **kw)	Write objects to a JSON file
jsoneasy.dump_fork(paths, **kw)	Write to multiple JSON files at once
jsoneasy.dump_archive(path, data, **kw)	Pack multiple JSON files into a ZIP or TAR archive

For complete parameter documentation, see the full docs →

Custom Serialization

Extra keyword arguments are forwarded to the underlying json.JSONEncoder / json.JSONDecoder. You can also pass a custom cls subclass for full control:

import jsoneasy

data = [{"name": "Alice", "score": 9.5}, {"name": "Bob", "score": 7.2}]

jsoneasy.dump(data, "compact.json", separators=(",", ":"))  # compact output
jsoneasy.dump(data, "sorted.json", sort_keys=True)  # deterministic keys
jsoneasy.dump(data, "pretty.json", indent=2)  # indented output

Supported Formats

Type	Extensions
Plain	.json
Compressed	.json.gz, .json.bz2, .json.xz
ZIP archive	.zip
TAR archive	.tar, .tar.gz, .tar.bz2, .tar.xz

When reading, if the file extension is not recognized, jsoneasy falls back to magic-number detection to identify the compression format automatically.

Contributing

# Install dev dependencies
pip install --group=test --upgrade

# Run tests
python -m pytest tests/
python -m pytest tests/ --cov  # run with coverage reporting

# Lint
pip install --group=lint --upgrade
ruff check .

# Docs
pip install --group=doc --upgrade

# zensical usage: https://zensical.org/docs/usage/
zensical build 
zensical serve

License

MIT — see LICENSE for details.