flatten-json

flatten-json is a small, focused Python library for flattening deeply nested JSON objects into single-level dictionaries and unflattening them back into their original nested form. Nested keys are joined with a configurable separator, and list indices are encoded into the flattened keys so no structure is lost.

It is especially handy for turning nested API responses or documents into flat, tabular rows suitable for pandas DataFrames, CSV export, or storage in systems that expect flat key-value data — then reconstructing the nested structure when needed.

What You Get

• A flatten() function that collapses nested JSON into a single-level dict
• unflatten() and unflatten_list() to rebuild the original nested structure
• Configurable key separator and optional root-key prefix
• List index encoding so array elements survive the round trip
• A tabular-friendly output shape ready for pandas or CSV export

Common Use Cases

• Converting nested API responses into flat rows for a pandas DataFrame
• Exporting nested JSON documents to CSV with columnar keys
• Normalizing nested data before loading it into flat storage
• Reconstructing nested objects from flat key-value records

Under The Hood

Architecture — The entire library lives in flatten_json/init.py. flatten() walks a nested structure recursively, building compound keys via a _construct_key helper that joins a previous key, separator, and current key, and encoding list positions as it descends. unflatten() reverses the process by parsing compound keys back into nested dicts and lists, with helpers like check_if_numbers_are_consecutive to detect list-shaped key groups.

Tech Stack — Pure Python with a single runtime dependency on six for Python 2/3 compatibility. It is packaged with setuptools (setup.py/setup.cfg) and has no heavy dependencies, keeping it lightweight to install anywhere.

Code Quality — The repository ships a test_flatten.py unittest suite covering flatten/unflatten round trips and edge cases. The implementation is compact and readable, with docstrings on the helper functions, though it retains Python 2 compatibility shims.

API Design — The public API is deliberately tiny: import flatten and call flatten(nested) or unflatten(flat). Optional keyword arguments (separator, root_keys_to_ignore) cover the common customization needs, so getting started requires almost no boilerplate.