json-flatten

library0.3.1pypypi✓ verified 84d ago

json-flatten is a Python library providing functions to convert a nested JSON object into a single-level dictionary of key-value pairs, and to reconstruct the original JSON object from that flattened representation. It's particularly useful for scenarios like converting JSON for HTML forms or query string parameters. The library is actively maintained, with releases typically addressing bug fixes and minor enhancements. The latest version is 0.3.1.

serialization data

pip install json-flatten

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · JSON-FLATTEN

json-flatten

serializationpythonv0.3.1

Install

1.5s avg

Import

—

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.3.1 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

flatten

✓ from json_flatten import flatten

✗ from json_flatten.json_flatten import flatten

The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.

unflatten

✓ from json_flatten import unflatten

✗ from json_flatten.json_flatten import unflatten

The functions are directly importable from the top-level `json_flatten` module, not from an internal submodule.

This example demonstrates how to flatten a nested dictionary (representing a JSON object) into a flat dictionary using `flatten()`, and then restore it to its original nested structure using `unflatten()`.

from json_flatten import flatten, unflatten original_json = { "name": "Alice", "details": { "age": 30, "address": { "street": "123 Main St", "city": "Anytown" }, "hobbies": ["reading", "coding", {"sport": "swimming"}] }, "active": True } # Flatten the JSON object flattened_data = flatten(original_json) print("Flattened Data:", flattened_data) # Expected output for flattened_data might look like: # { # 'name': 'Alice', # 'details.age': 30, # 'details.address.street': '123 Main St', # 'details.address.city': 'Anytown', # 'details.hobbies.[0]$str': 'reading', # 'details.hobbies.[1]$str': 'coding', # 'details.hobbies.[2].sport': 'swimming', # 'active': True # } # Unflatten the data back to its original structure unflattened_json = unflatten(flattened_data) print("Unflattened Data:", unflattened_json) # Verify round-trip (optional) assert original_json == unflattened_json

json-flatten --version

Debug

Known issues

breakingStarting from version 0.3, the `flatten()` function now explicitly checks if the input object is a dictionary. If a non-dictionary object (e.g., a list or a string) is passed, it will raise a `TypeError`.

fix

Ensure that the input to `flatten()` is always a dictionary. If you need to flatten a list of dictionaries, iterate over the list and flatten each dictionary individually.

affects: >=0.3

breakingVersion 0.2 introduced a change in the serialization format used for array keys. This update correctly handles dictionaries where keys are strings containing only digits. This means data flattened with versions prior to 0.2 might not unflatten correctly with 0.2 and later, or vice-versa, if such array keys are present.

fix

If working with existing flattened data, verify its compatibility with the current `json-flatten` version. Consider re-flattening old data with the new version if issues arise.

affects: 0.2

gotchaThe library uses a specific and detailed format for flattened keys, especially for array elements (e.g., `parent.array.[index]$type=value`) and includes type hints for round-tripping complex types like `None`, `True`/`False`, `int`, `float`, and `str`. While this ensures accurate unflattening, it differs from simpler flattening schemes and requires careful consideration if manually manipulating keys or integrating with other flattening tools.

fix

Refer to the library's documentation, particularly the 'flattened format' section, to understand the exact key representation if you intend to process or generate flattened data outside of the `json-flatten` library.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'json_flatten'

The Python module name used for importing (`json_flatten`) does not match the package name used for installation (`json-flatten`), or the library is not installed in the current environment.

fix

Install the library using the correct package name: `pip install json-flatten`

AttributeError: 'str' object has no attribute 'items'

The `flatten()` function of the `json-flatten` library expects a dictionary as its top-level input, but it received a string or another non-dictionary type.

fix

Ensure the input passed to `flatten()` is a valid Python dictionary, typically by loading a JSON string using `json.loads()` first, e.g., `flattened_data = flatten(json.loads(json_string))`

Unexpected flattened output due to key collisions or delimiter conflicts

The default dot (`.`) delimiter used by `json-flatten` to represent nested keys might conflict with dots already present in the original keys of the JSON object, leading to ambiguous paths and incorrect or unexpected flattened data.

fix

Specify a different delimiter character (e.g., `__` or `|`) when calling both `flatten()` and `unflatten()` to avoid clashes with existing keys: `flattened_data = flatten(my_json, delimiter='__')`

Upgrade

Version history

0.3.1latest on PyPI · released Sep 7, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/simonw/json-flatten ↗

packagehttps://pypi.org/project/json-flatten/ ↗

changeloghttps://github.com/simonw/json-flatten/releases ↗