flatmonkey

Round-trip-safe structural reshaping between nested and flat data — flatten nested dicts/JSON into {path: value}, unflatten back, and nest flat rows into nested records. A lightweight, round-tripping alternative to pandas.json_normalize.

Flattened keys are valid grabmonkey paths, so grab(data, key) works on any key flatmonkey produces.

Install

pip install flatmonkey

Quick start

from flatmonkey import flatten, unflatten, flatten_all, nest

d = {"user": {"name": "Ada", "roles": ["admin", "dev"]}}
flat = flatten(d)
# {'user.name': 'Ada', 'user.roles[0]': 'admin', 'user.roles[1]': 'dev'}

unflatten(flat) == d          # True — the round trip holds

# Batch:
flatten_all([{"a": {"b": 1}}, {"a": {"b": 2}}])
# [{'a.b': 1}, {'a.b': 2}]

# Nest flat rows into nested records:
nest(
    [{"order_id": 1, "product": "x", "qty": 2},
     {"order_id": 1, "product": "y", "qty": 1}],
    group_by=["order_id"],
    nest_fields={"items": ["product", "qty"]},
)
# [{'order_id': 1, 'items': [{'product': 'x', 'qty': 2}, {'product': 'y', 'qty': 1}]}]

Options

• sep="/" — choose a separator your dict keys do not contain (any single char except [ / ]).
• list_handling="index" | "stringify" | "omit" | "keep" — how list values are rendered. Only the default "index" round-trips.
• max_depth=N — stop flattening after N path segments; deeper structure is kept as a value.

CLI

flatmonkey flatten data.json -o flat.json
flatmonkey unflatten flat.json
flatmonkey nest rows.json --group-by order_id --nest items=product,qty
cat data.json | flatmonkey flatten -        # '-' reads stdin / writes stdout

Using with AI assistants

See SKILL.md for an LLM-consumable reference (decision tree, worked examples, troubleshooting).

Design tradeoffs

Some behaviours are intentional and might look surprising — see LIMITATIONS.md for the deliberate design decisions (tuple/int-key lossiness, one-way list modes, collision handling, nest carry-through).

License

MIT — see LICENSE.