{"id":18557695,"url":"https://github.com/aosingh/json-flattener","last_synced_at":"2025-05-15T14:11:26.702Z","repository":{"id":98969066,"uuid":"303160642","full_name":"aosingh/json-flattener","owner":"aosingh","description":"Python utility to flatten a JSON object","archived":false,"fork":false,"pushed_at":"2020-10-14T14:52:35.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-17T11:43:58.909Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aosingh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-11T16:12:47.000Z","updated_at":"2020-11-18T20:32:37.000Z","dependencies_parsed_at":"2023-04-16T08:47:16.262Z","dependency_job_id":null,"html_url":"https://github.com/aosingh/json-flattener","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aosingh%2Fjson-flattener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aosingh%2Fjson-flattener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aosingh%2Fjson-flattener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aosingh%2Fjson-flattener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aosingh","download_url":"https://codeload.github.com/aosingh/json-flattener/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355409,"owners_count":22057356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T21:37:46.215Z","updated_at":"2025-05-15T14:11:24.844Z","avatar_url":"https://github.com/aosingh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# jflat [![Travis](https://travis-ci.com/aosingh/json-flattener.svg?branch=main)](https://travis-ci.com/github/aosingh/json-flattener)\n[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)]((https://www.python.org/downloads/release/python-370/)) [![Python 3.7](https://img.shields.io/badge/python-3.7-blue.svg)](https://www.python.org/downloads/release/python-370/) [![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/downloads/release/python-380/)\n[![PyPy3](https://img.shields.io/badge/python-PyPy3-blue.svg)](https://www.pypy.org/index.html)\n\nPython utility to flatten a JSON object\n\n## Install\n\n`jflat` can be installed using `pip` and `virtualenv`. \n\n1. Create a local directory where you would like to work from \n\n    ```bash\n    mkdir jflat_test\n    \n    cd jflat_test\n    ```\n   \n2. Create an isolated Python virtual environment. \n  `virtualenv` can be installed using pip as explained [here](https://virtualenv.pypa.io/en/latest/installation.html)\n\n    ```bash\n    virtualenv --python=python3 .venv\n    \n    source .venv/bin/activate\n   \n    pip install --upgrade pip\n   ```\n\n3. Install `jflat` from source using `pip`\n    ```bash\n    pip install git+https://github.com/aosingh/json-flattener.git#egg=jflat\n    ```\n\n### Dependencies\n\nDependencies are defined as install requirements in `setup.py`. You need not install them separately.\nWe use the following external libraries.\n\n- click\n    - To create a Command Line Interface (CLI) for `jflat`\n- pytest\n    - To run unit tests\n\n\n## CLI\n\n```bash\n\nUsage: jflat [OPTIONS] [JSON_STRING]\n\nOptions:\n\n  --log-level [CRITICAL|FATAL|ERROR|WARN|WARNING|INFO|DEBUG|NOTSET]\n  --out-file TEXT                 Path to the output JSON file\n  --sort-keys / --no-sort-keys    [default: False]\n  --help                          Show this message and exit.\n\n```\n\n## Examples\n\n### Simple json string\n\nAt times it is convenient to test with an inline JSON string. Make sure you enclose the \nJSON string in single quotes as shown below\n\n```bash\njflat '{\"username\":\"xyz\",\"password\":{\"hash\": \"e8c400f94e807f0d374d9c971bec018\"}}'\n\n```\n\nThe following output will be written to stdout.\n\n```json5\n{\n  \"password.hash\": \"e8c400f94e807f0d374d9c971bec018\",\n  \"username\": \"xyz\"\n}\n```\n\n### File input \n\nAdditionally, `jflat` can accept input from a file. \nLet's say our input file `input.json` looks like below\n\n```json5\n{\n    \"friends\": {\n        \"1\": {\n            \"name\": \"Mr. X\",\n            \"age\": 13,\n            \"hobbies\": {\n                \"football\": true,\n                \"vedic maths\": false,\n                \"origami\": true\n            }\n        },\n        \"2\": {\n            \"name\": \"Mr. Y\",\n            \"age\": 56,\n            \"hobbies\": {\n                \"football\": false,\n                \"vedic maths\": true,\n                \"origami\": false\n            }\n        }\n    }\n}\n\n```\n\nInvoke the JSON flat command as shown below\n\n```bash\njflat \u003c input.json\n```\nYou will see the flattened JSON object printed to stdout\n\n```json5\n{\n  \"friends.2.hobbies.origami\": false,\n  \"friends.2.hobbies.vedic maths\": true,\n  \"friends.2.hobbies.football\": false,\n  \"friends.2.age\": 56,\n  \"friends.2.name\": \"Mr. Y\",\n  \"friends.1.hobbies.origami\": true,\n  \"friends.1.hobbies.vedic maths\": false,\n  \"friends.1.hobbies.football\": true,\n  \"friends.1.age\": 13,\n  \"friends.1.name\": \"Mr. X\"\n}\n```\n\n### Sort keys\n\nPass the `--sort-keys` flag to sort the keys alphabetically in the flattened JSON.\n\n```bash\njflat \u003c input.json --sort-keys\n```\n```json5\n{\n  \"friends.1.age\": 13,\n  \"friends.1.hobbies.football\": true,\n  \"friends.1.hobbies.origami\": true,\n  \"friends.1.hobbies.vedic maths\": false,\n  \"friends.1.name\": \"Mr. X\",\n  \"friends.2.age\": 56,\n  \"friends.2.hobbies.football\": false,\n  \"friends.2.hobbies.origami\": false,\n  \"friends.2.hobbies.vedic maths\": true,\n  \"friends.2.name\": \"Mr. Y\"\n}\n\n```\n\n### Save the output to a file\n\nThe default behavior is to write the flattened JSON object to stdout. If you want to save the flattened JSON object to a file, you can use the `--out-file` option. An example\nis shown below\n\n```bash5\njflat \u003c input.json --sort-keys --out-file=output.json\n```\n\nVerify the contents of the output file\n\n```bash\ncat output.json\n```\n\n```json5\n\n{\n  \"friends.1.age\": 13,\n  \"friends.1.hobbies.football\": true,\n  \"friends.1.hobbies.origami\": true,\n  \"friends.1.hobbies.vedic maths\": false,\n  \"friends.1.name\": \"Mr. X\",\n  \"friends.2.age\": 56,\n  \"friends.2.hobbies.football\": false,\n  \"friends.2.hobbies.origami\": false,\n  \"friends.2.hobbies.vedic maths\": true,\n  \"friends.2.name\": \"Mr. Y\"\n}\n```\n\n## Continuous Integration (CI)\n\nThe code repository is integrated with Travis CI. As shown below, in the build matrix, the build process tests\nfor Linux and different Python 3 versions. \n\n```yaml\nlanguage: python\nmatrix:\n  include:\n    - os: linux\n      python: 3.6\n    - os: linux\n      python: 3.7\n    - os: linux\n      python: 3.8\n    - os: linux\n      python: pypy3\n```\n\nAdditionally, github workflow is configured to run all tests with the latest version of `Ubuntu` and Python 3\n\n\n## Unit Test \u0026 Coverage\n\nUnit tests are integrated with the build process. We use `coverage` to run the test cases and generate a coverage report.\n\n\n```bash\ncoverage run -m pytest --verbose\n```\n\n```bash\ncoverage report -i -m\n\nName                        Stmts   Miss  Cover   Missing\n---------------------------------------------------------\njflat/__init__.py               1      0   100%\njflat/cli.py                   28      1    96%   38\njflat/flattener.py             25      0   100%\njflat/tests/__init__.py         0      0   100%\njflat/tests/test_jflat.py      98      0   100%\n---------------------------------------------------------\nTOTAL                         152      1    99%\n\n```\n\n## API\n\nThe Python API can be used to access the flattened Python dictionary directly. \n\n```python\nfrom jflat.flattener import JSONFlattener\n\ndata = {\n        \"friends\": {\n            \"1\": {\n                \"name\": \"Mr. X\",\n                \"age\": 13,\n                \"hobbies\":{\n                    \"football\": True,\n                    \"vedic maths\": False,\n                    \"origami\": True\n                }\n            },\n            \"2\": {\n                \"name\": \"Mr. Y\",\n                \"age\": 56,\n                \"hobbies\": {\n                    \"football\": False,\n                    \"vedic maths\": True,\n                    \"origami\": False\n                }\n            }\n        }\n    }\n\nj = JSONFlattener(data=data)\nflattened_dict = j()\n\nprint(flattened_dict)\n\n\u003e\u003e\u003e {'friends.1.age': 13,\n     'friends.1.hobbies.football': True,\n     'friends.1.hobbies.origami': True,\n     'friends.1.hobbies.vedic maths': False,\n     'friends.1.name': 'Mr. X',\n     'friends.2.age': 56,\n     'friends.2.hobbies.football': False,\n     'friends.2.hobbies.origami': False,\n     'friends.2.hobbies.vedic maths': True,\n     'friends.2.name': 'Mr. Y'}         \n\n```\n\n\n## Notes\n\n- Standard python library `json` is used to parse the input JSON object and also\nserialize the flattened dict.\n\n- Iterative Depth First Search (DFS) is used to flatten the JSON object.\n \n- The following JSON types are tested.\n    - boolean\n    - null\n    - number\n    - object\n    - string\n    \n- In the current implementation, if the JSON object has an array, the array will be skipped.\n\n- The name `jflat` is inspired from command-line JSON processor `jq`. \n\n\n## TODO\n\n- Determine the maximum level of nesting supported.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faosingh%2Fjson-flattener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faosingh%2Fjson-flattener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faosingh%2Fjson-flattener/lists"}