Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/simonw/json-flatten
Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object
https://github.com/simonw/json-flatten
json python
Last synced: 4 days ago
JSON representation
Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object
- Host: GitHub
- URL: https://github.com/simonw/json-flatten
- Owner: simonw
- License: apache-2.0
- Created: 2019-06-22T04:38:59.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-07T04:32:44.000Z (4 months ago)
- Last Synced: 2024-10-18T07:53:35.844Z (3 months ago)
- Topics: json, python
- Language: Python
- Homepage:
- Size: 31.3 KB
- Stars: 47
- Watchers: 3
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# json-flatten
[](https://pypi.org/project/json-flatten/)
[](https://github.com/simonw/json-flatten/releases)
[](https://github.com/simonw/json-flatten/actions?query=workflow%3ATest)
[](https://github.com/simonw/json-flatten/blob/main/LICENSE)
Python functions for flattening a JSON object to a single dictionary of pairs, and unflattening that dictionary back to a JSON object.
This can be useful if you need to represent a JSON object using a regular HTML form or transmit it as a set of query string parameters.
For example:
```pycon
>>> import json_flatten
>>> json_flatten.flatten({"foo": {"bar": [1, True, None]}})
{'foo.bar.[0]$int': '1', 'foo.bar.[1]$bool': 'True', 'foo.bar.[2]$none': 'None'}
>>> json_flatten.unflatten(_)
{'foo': {'bar': [1, True, None]}}
```
The top-level object passed to `flatten()` must be a dictionary.
## JSON flattening format
### Basic principles
1. Keys are constructed using dot notation to represent nesting.
2. Type information is preserved using `$type` suffixes.
3. List indices are represented using `[index]` notation.
4. Empty objects and lists have special representations.
### Nested objects
For nested objects, keys are constructed by joining the nested keys with dots.
Example:
```json
{
"user": {
"name": "John",
"age": 30
}
}
```
Flattened:
```
user.name=John
user.age$int=30
```
### Lists
List items are represented using `[index]` notation.
Example:
```json
{
"fruits": [
"apple",
"banana",
"cherry"
]
}
```
Flattened:
```
fruits.[0]=apple
fruits.[1]=banana
fruits.[2]=cherry
```
### Nested lists
For nested lists, the index notation is repeated.
Example:
```json
{"matrix": [[1, 2], [3, 4]]}
```
Flattened:
```
matrix.[0].[0]$int=1
matrix.[0].[1]$int=2
matrix.[1].[0]$int=3
matrix.[1].[1]$int=4
```
## Type preservation
Types are preserved using `$type` suffixes:
| Type | Suffix | Example |
|------|--------|---------|
|String||`name=Cleo`|
|Integer|`$int`|`age$int=30`|
|Float|`$float`|`price$float=19.99`|
|Boolean|`$bool`|`active$bool=True`|
|Null|`$none`|`data$none=None`|
|Empty object|`$empty`|`obj$empty={}`|
|Empty list|`$emptylist`|`list$emptylist=[]`|
String values do not require a type suffix.
## Example
JSON:
```json
{
"user": {
"name": "Alice",
"age": 28,
"hobbies": [
"reading",
"swimming"
],
"address": {
"street": "123 Main St",
"city": "Anytown"
},
"active": true,
"salary": 50000.5,
"spouse": null,
"more_nesting": {
"empty_lists": [
[],
[]
],
"empty_objects": [
{},
{}
]
}
}
}
```
Flattened with `flattened = flatten(example)`
```
user.name=Alice
user.age$int=28
user.hobbies.[0]=reading
user.hobbies.[1]=swimming
user.address.street=123 Main St
user.address.city=Anytown
user.active$bool=True
user.salary$float=50000.5
user.spouse$none=None
user.more_nesting.empty_lists.[0]$emptylist=[]
user.more_nesting.empty_lists.[1]$emptylist=[]
user.more_nesting.empty_objects.[0]$empty={}
user.more_nesting.empty_objects.[1]$empty={}
```
Unflattened again with `unflattened = unflatten(flattened)`
```json
{
"user": {
"name": "Alice",
"age": 28,
"hobbies": [
"reading",
"swimming"
],
"address": {
"street": "123 Main St",
"city": "Anytown"
},
"active": true,
"salary": 50000.5,
"spouse": null,
"more_nesting": {
"empty_lists": [
[],
[]
],
"empty_objects": [
{},
{}
]
}
}
}
```