Metadata-Version: 2.4
Name: philiprehberger-flatten-json
Version: 0.2.6
Summary: Flatten nested JSON/dicts into dot-notation keys and unflatten back
Project-URL: Homepage, https://github.com/philiprehberger/py-flatten-json#readme
Project-URL: Repository, https://github.com/philiprehberger/py-flatten-json
Project-URL: Issues, https://github.com/philiprehberger/py-flatten-json/issues
Project-URL: Changelog, https://github.com/philiprehberger/py-flatten-json/blob/main/CHANGELOG.md
Author: Philip Rehberger
License-Expression: MIT
License-File: LICENSE
Keywords: dot-notation,flatten,json,nested,unflatten
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# philiprehberger-flatten-json

[![Tests](https://github.com/philiprehberger/py-flatten-json/actions/workflows/publish.yml/badge.svg)](https://github.com/philiprehberger/py-flatten-json/actions/workflows/publish.yml)
[![PyPI version](https://img.shields.io/pypi/v/philiprehberger-flatten-json.svg)](https://pypi.org/project/philiprehberger-flatten-json/)
[![License](https://img.shields.io/github/license/philiprehberger/py-flatten-json)](LICENSE)

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

## Installation

```bash
pip install philiprehberger-flatten-json
```

## Usage

```python
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

```python
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}}
```

## API

| Function | Description |
|---|---|
| `flatten(data, *, separator=".", max_depth=0, prefix="")` | Flatten nested dict/list into dot-notation keys |
| `unflatten(data, *, separator=".", list_as_dict=False)` | Restore nested structure from flat dict |

### 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

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

## License

MIT
