[](https://travis-ci.org/amirziai/flatten) [](https://badge.fury.io/py/flatten-json) [](https://www.codacy.com/app/amirziai/flatten?utm_source=github.com&utm_medium=referral&utm_content=amirziai/flatten&utm_campaign=Badge_Coverage)
# flatten_json
Flattens JSON objects in Python. ```flatten_json``` flattens the hierarchy in your object which can be useful if you want to force your objects into a table.
## Installation
```bash
pip install flatten_json
```
## flatten
### Usage
Let's say you have the following object:
```python
dic = {
"a": 1,
"b": 2,
"c": [{"d": [2, 3, 4], "e": [{"f": 1, "g": 2}]}]
}
```
which you want to flatten. Just apply ```flatten```:
```python
from flatten_json import flatten
flatten(dic)
```
Results:
```python
{'a': 1,
'b': 2,
'c_0_d_0': 2,
'c_0_d_1': 3,
'c_0_d_2': 4,
'c_0_e_0_f': 1,
'c_0_e_0_g': 2}
```
### Usage with Pandas
For the following object:
```python
dic = [
{"a": 1, "b": 2, "c": {"d": 3, "e": 4}},
{"a": 0.5, "c": {"d": 3.2}},
{"a": 0.8, "b": 1.8},
]
```
We can apply `flatten` to each element in the array and then use pandas to capture the output as a dataframe:
```python
dic_flattened = [flatten(d) for d in dic]
```
which creates an array of flattened objects:
```python
[{'a': 1, 'b': 2, 'c_d': 3, 'c_e': 4},
{'a': 0.5, 'c_d': 3.2},
{'a': 0.8, 'b': 1.8}]
```
Finally you can use ```pd.DataFrame``` to capture the flattened array:
```python
import pandas as pd
df = pd.DataFrame(dic_flattened)
```
The final result as a Pandas dataframe:
```
a b c_d c_e
0 1 2 3 4
1 0.5 NaN 3.2 NaN
2 0.8 1.8 NaN NaN
```
### Custom separator
By default `_` is used to separate nested element. You can change this by passing the desired character:
```python
flatten({"a": [1]}, '|')
```
returns:
```python
{'a|0': 1}
```
### Ignore root keys
By default `flatten` goes through all the keys in the object. If you are not interested in output from a set of keys you can pass this set as an argument to `root_keys_to_ignore`:
```python
dic = {
'a': {'a': [1, 2, 3]},
'b': {'b': 'foo', 'c': 'bar'},
'c': {'c': [{'foo': 5, 'bar': 6, 'baz': [1, 2, 3]}]}
}
flatten(dic, root_keys_to_ignore={'b', 'c'})
```
returns:
```python
{
'a_a_0': 1,
'a_a_1': 2,
'a_a_2': 3
}
```
This feature can prevent unnecessary processing which is a concern with deeply nested objects.
## unflatten
Reverses the flattening process. Example usage:
```python
from flatten_json import unflatten
dic = {
'a': 1,
'b_a': 2,
'b_b': 3,
'c_a_b': 5
}
unflatten(dic)
```
returns:
```python
{
'a': 1,
'b': {'a': 2, 'b': 3},
'c': {'a': {'b': 5}}
}
```
### Unflatten with lists
`flatten` encodes key for list values with integer indices which makes it ambiguous for reversing the process. Consider this flattened dictionary:
```python
a = {'a': 1, 'b_0': 5}
```
Both `{'a': 1, 'b': [5]}` and `{'a': 1, 'b': {0: 5}}` are legitimate answers.
Calling `unflatten_list` the dictionary is first unflattened and then in a post-processing step the function looks for a list pattern (zero-indexed consecutive integer keys) and transforms the matched values into a list.
Here's an example:
```python
from flatten_json import unflatten_list
dic = {
'a': 1,
'b_0': 1,
'b_1': 2,
'c_a': 'a',
'c_b_0': 1,
'c_b_1': 2,
'c_b_2': 3
}
unflatten_list(dic)
```
returns:
```python
{
'a': 1,
'b': [1, 2],
'c': {'a': 'a', 'b': [1, 2, 3]}
}
```
## Command line invocation
```bash
>>> echo '{"a": {"b": 1}}' | flatten_json
{"a_b": 1}
>>> echo '{"a": {"b": 1}}' > test.json
>>> cat test.json | flatten_json
{"a_b": 1}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/amirziai/flatten",
"name": "flatten-json",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "json,flatten,pandas",
"author": "Amir Ziai",
"author_email": "arziai@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/14/e9b5e4a8dd7edccc9d0791c4ed2180e50b00ab4c19b07081308814dd4e68/flatten_json-0.1.14.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/amirziai/flatten) [](https://badge.fury.io/py/flatten-json) [](https://www.codacy.com/app/amirziai/flatten?utm_source=github.com&utm_medium=referral&utm_content=amirziai/flatten&utm_campaign=Badge_Coverage) \n\n# flatten_json\nFlattens JSON objects in Python. ```flatten_json``` flattens the hierarchy in your object which can be useful if you want to force your objects into a table.\n\n## Installation\n```bash\npip install flatten_json\n```\n\n## flatten\n\n### Usage\nLet's say you have the following object:\n```python\ndic = {\n \"a\": 1,\n \"b\": 2,\n \"c\": [{\"d\": [2, 3, 4], \"e\": [{\"f\": 1, \"g\": 2}]}]\n}\n```\nwhich you want to flatten. Just apply ```flatten```:\n```python\nfrom flatten_json import flatten\nflatten(dic)\n```\n\nResults:\n```python\n{'a': 1,\n 'b': 2,\n 'c_0_d_0': 2,\n 'c_0_d_1': 3,\n 'c_0_d_2': 4,\n 'c_0_e_0_f': 1,\n 'c_0_e_0_g': 2}\n```\n\n### Usage with Pandas\nFor the following object:\n```python\ndic = [\n {\"a\": 1, \"b\": 2, \"c\": {\"d\": 3, \"e\": 4}},\n {\"a\": 0.5, \"c\": {\"d\": 3.2}},\n {\"a\": 0.8, \"b\": 1.8},\n]\n```\nWe can apply `flatten` to each element in the array and then use pandas to capture the output as a dataframe:\n```python\ndic_flattened = [flatten(d) for d in dic]\n```\nwhich creates an array of flattened objects:\n```python\n[{'a': 1, 'b': 2, 'c_d': 3, 'c_e': 4},\n {'a': 0.5, 'c_d': 3.2},\n {'a': 0.8, 'b': 1.8}]\n```\nFinally you can use ```pd.DataFrame``` to capture the flattened array:\n```python\nimport pandas as pd\ndf = pd.DataFrame(dic_flattened)\n```\nThe final result as a Pandas dataframe:\n```\n\ta\tb\tc_d\tc_e\n0\t1\t2\t3\t4\n1\t0.5\tNaN\t3.2\tNaN\n2\t0.8\t1.8\tNaN\tNaN\n```\n\n### Custom separator\nBy default `_` is used to separate nested element. You can change this by passing the desired character:\n```python\nflatten({\"a\": [1]}, '|')\n```\nreturns:\n```python\n{'a|0': 1}\n```\n\n### Ignore root keys\nBy default `flatten` goes through all the keys in the object. If you are not interested in output from a set of keys you can pass this set as an argument to `root_keys_to_ignore`:\n```python\ndic = {\n 'a': {'a': [1, 2, 3]},\n 'b': {'b': 'foo', 'c': 'bar'},\n 'c': {'c': [{'foo': 5, 'bar': 6, 'baz': [1, 2, 3]}]}\n}\nflatten(dic, root_keys_to_ignore={'b', 'c'})\n```\nreturns:\n```python\n{\n 'a_a_0': 1,\n 'a_a_1': 2,\n 'a_a_2': 3\n}\n```\nThis feature can prevent unnecessary processing which is a concern with deeply nested objects.\n\n## unflatten\nReverses the flattening process. Example usage:\n```python\nfrom flatten_json import unflatten\n\ndic = {\n 'a': 1,\n 'b_a': 2,\n 'b_b': 3,\n 'c_a_b': 5\n}\nunflatten(dic)\n```\nreturns:\n```python\n{\n 'a': 1,\n 'b': {'a': 2, 'b': 3},\n 'c': {'a': {'b': 5}}\n}\n```\n\n### Unflatten with lists\n`flatten` encodes key for list values with integer indices which makes it ambiguous for reversing the process. Consider this flattened dictionary:\n```python\na = {'a': 1, 'b_0': 5}\n```\n\nBoth `{'a': 1, 'b': [5]}` and `{'a': 1, 'b': {0: 5}}` are legitimate answers.\n \nCalling `unflatten_list` the dictionary is first unflattened and then in a post-processing step the function looks for a list pattern (zero-indexed consecutive integer keys) and transforms the matched values into a list.\n \nHere's an example:\n```python\nfrom flatten_json import unflatten_list\ndic = {\n 'a': 1,\n 'b_0': 1,\n 'b_1': 2,\n 'c_a': 'a',\n 'c_b_0': 1,\n 'c_b_1': 2,\n 'c_b_2': 3\n}\nunflatten_list(dic)\n```\nreturns:\n```python\n{\n 'a': 1,\n 'b': [1, 2],\n 'c': {'a': 'a', 'b': [1, 2, 3]}\n}\n```\n\n## Command line invocation\n```bash\n>>> echo '{\"a\": {\"b\": 1}}' | flatten_json\n{\"a_b\": 1}\n\n>>> echo '{\"a\": {\"b\": 1}}' > test.json\n>>> cat test.json | flatten_json\n{\"a_b\": 1}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Flatten JSON objects",
"version": "0.1.14",
"project_urls": {
"Homepage": "https://github.com/amirziai/flatten"
},
"split_keywords": [
"json",
"flatten",
"pandas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "63b599f20a19b839e04fffab924be192681b797b40bcf83abdfa508371c6273c",
"md5": "182c7f1d7fe641e47784265c42cf74e7",
"sha256": "75e455dbbb5be2431546024039cac094a8ed1dfedcf36ab1e7c9d01459fa410c"
},
"downloads": -1,
"filename": "flatten_json-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "182c7f1d7fe641e47784265c42cf74e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7962,
"upload_time": "2023-10-27T17:20:40",
"upload_time_iso_8601": "2023-10-27T17:20:40.455233Z",
"url": "https://files.pythonhosted.org/packages/63/b5/99f20a19b839e04fffab924be192681b797b40bcf83abdfa508371c6273c/flatten_json-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f14e9b5e4a8dd7edccc9d0791c4ed2180e50b00ab4c19b07081308814dd4e68",
"md5": "10c08ed41a82355774906a1ac82e3f40",
"sha256": "4008b1bd81743e6fcdc29ddbb640f5c1589376116e0c8f36cb4a0003d41fe102"
},
"downloads": -1,
"filename": "flatten_json-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "10c08ed41a82355774906a1ac82e3f40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7806,
"upload_time": "2023-10-27T17:20:54",
"upload_time_iso_8601": "2023-10-27T17:20:54.562094Z",
"url": "https://files.pythonhosted.org/packages/0f/14/e9b5e4a8dd7edccc9d0791c4ed2180e50b00ab4c19b07081308814dd4e68/flatten_json-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-27 17:20:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "amirziai",
"github_project": "flatten",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
">=",
"3.0.5"
]
]
},
{
"name": "six",
"specs": []
}
],
"lcname": "flatten-json"
}
JSON
