JSON Streams

0.6.0 · active · verified Fri Apr 17

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.

Common errors

```
AttributeError: 'Stream' object has no attribute 'read'
```
cause `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.
```
cause 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)
```
cause 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.

Warnings

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.
gotcha Proper 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.
gotcha The 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.

Install

pip install jsonstreams Install stable version

Imports

Stream
wrong:
```
import jsonstreams
```
correct:
```
from jsonstreams import Stream
```
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.

Quickstart

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}]

view raw JSON →