philiprehberger-flatten-json

Flatten nested JSON/dicts into dot-notation keys and unflatten back.

Installation

pip install philiprehberger-flatten-json

Usage

from philiprehberger_flatten_json import flatten, unflatten

nested = {"a": {"b": {"c": 1}}, "d": [2, 3]}

flatten(nested)
# {"a.b.c": 1, "d.0": 2, "d.1": 3}

unflatten({"a.b.c": 1, "d.0": 2, "d.1": 3})
# {"a": {"b": {"c": 1}}, "d": [2, 3]}

# Custom separator
flatten(nested, separator="/")
# {"a/b/c": 1, "d/0": 2, "d/1": 3}

# Max depth
flatten(nested, max_depth=1)
# {"a": {"b": {"c": 1}}, "d": [2, 3]}

# Prefix
flatten(nested, prefix="root")
# {"root.a.b.c": 1, "root.d.0": 2, "root.d.1": 3}

# Keep numeric keys as dict
unflatten({"a.0": 1, "a.1": 2}, list_as_dict=True)
# {"a": {"0": 1, "1": 2}}

Roundtrip

from philiprehberger_flatten_json import flatten, unflatten

data = {"users": [{"name": "Alice", "age": 30}], "meta": {"version": 2}}

flat = flatten(data)
# {"users.0.name": "Alice", "users.0.age": 30, "meta.version": 2}

restored = unflatten(flat)
# {"users": [{"name": "Alice", "age": 30}], "meta": {"version": 2}}

Path access

from philiprehberger_flatten_json import get_by_path, set_by_path

data = {"users": [{"name": "ada"}, {"name": "bob"}]}

get_by_path(data, "users.1.name")
# "bob"

get_by_path(data, "users.5.name", default="unknown")
# "unknown"

config: dict = {}
set_by_path(config, "db.host", "localhost")
set_by_path(config, "db.port", 5432)
# config == {"db": {"host": "localhost", "port": 5432}}

API

Parameters

flatten()

• data — Nested dict or list
• separator — Key separator (default ".")
• max_depth — Max depth to flatten, 0 = unlimited
• prefix — String to prepend to all keys

unflatten()

• data — Flat dict with composite keys
• separator — Key separator used during flattening
• list_as_dict — When True, numeric keys stay as dict keys instead of converting to lists

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT