jsonstreams

library0.6.0pypypi✓ verified 85d ago

jsonstreams is a Python library designed for efficiently writing large JSON files with low memory usage. It provides a context manager-based API for incrementally constructing JSON arrays and objects. The current version is 0.6.0, and while its release cadence is infrequent, the project appears to be actively maintained.

serialization

pip install jsonstreams

github ↗package ↗

INSTALL

IMPORT

SIG · JSONSTREAMS

jsonstreams

serializationpythonv0.6.0

Install

1.6s avg

Import

17ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.017s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.016s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Stream

✓ from jsonstreams import Stream

✗ import jsonstreams

The primary class 'Stream' is typically imported directly from the top-level package.

pretty.Stream

✓ from jsonstreams.pretty import Stream

Use this import for pretty-printed JSON output.

This example demonstrates how to use `jsonstreams.Stream` to write a JSON array of objects to an in-memory buffer. The `with` statements ensure proper handling and closure of the JSON structure, which is crucial for correct output.

import io from jsonstreams import Stream # Stream to an in-memory buffer (StringIO) for demonstration output_buffer = io.StringIO() with Stream(output_buffer) as s: s.start_array() with s.array_item() as item: item.write({"id": 1, "name": "Apple", "price": 1.0}) with s.array_item() as item: item.write({"id": 2, "name": "Banana", "price": 0.5}) s.end_array() # Print the generated JSON string print(output_buffer.getvalue()) # Expected output: [{"id": 1, "name": "Apple", "price": 1.0}, {"id": 2, "name": "Banana", "price": 0.5}]

Debug

Known issues

gotcha`jsonstreams` is a JSON *writer* only. It does not provide functionality for parsing or reading existing JSON data.

fix

To read or parse JSON, use Python's built-in `json` module (e.g., `json.load()` or `json.loads()`) or a dedicated JSON parsing library.

affects: All versions

gotchaProper use of context managers (`with` statements) for `Stream`, `array_item()`, and `object_item()` is critical. Omitting them can lead to malformed JSON output or unclosed streams.

fix

Always wrap your stream and item operations within `with` statements to ensure the JSON structure is correctly opened and closed, guaranteeing valid JSON and proper resource management.

affects: All versions

gotchaThe library explicitly excludes Python versions 3.0 through 3.5. Attempting to install or use it on these versions will fail due to `Requires-Python` metadata.

fix

Ensure you are running Python 2.7 or Python 3.6 and newer to use `jsonstreams`. Upgrade your Python environment if necessary.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'Stream' object has no attribute 'read'

`jsonstreams` is designed exclusively for writing JSON. You are attempting to read data using a `Stream` object.

fix

Use Python's standard `json` module (e.g., `json.load(file_obj)`) or another JSON parsing library to read JSON data. `jsonstreams` cannot be used for this purpose.

jsonstreams.core.JsonStreamException: Cannot write directly to stream while inside an array or object.

You called `stream_object.write(...)` directly when inside an `array_item()` or `object_item()` context, which already provides its own `write()` method.

fix

When within an `array_item` or `object_item` context, ensure `write()` calls are made on the context manager object itself. Example: `with s.array_item() as item: item.write({'key': 'value'})`.

json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)

The JSON file generated by `jsonstreams` is malformed, often due to incorrect ordering of `start_array`/`end_array`, `start_object`/`end_object`, or not using `with` statements for contexts.

fix

Thoroughly review your `jsonstreams` code. Verify that all `start_` calls have corresponding `end_` calls and that all context managers (`Stream`, `array_item`, `object_item`) are used correctly with `with` statements to ensure proper JSON nesting and closure.

Upgrade

Version history

0.6.0latest on PyPI · released Mar 16, 2021

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/dcbaker/jsonstreams ↗

packagehttps://pypi.org/project/jsonstreams/ ↗