{"id":2512,"library":"flatten-json","title":"Flatten JSON Objects","description":"flatten-json is a Python library that efficiently flattens nested JSON objects into a single-level dictionary, making them suitable for tabular formats like Pandas DataFrames or CSV export. It also provides functionality to 'unflatten' these single-level dictionaries back into nested JSON structures. The current version is 0.1.14, with a history of regular minor updates.","status":"active","version":"0.1.14","language":"en","source_language":"en","source_url":"https://github.com/amirziai/flatten","tags":["json","flatten","unflatten","data transformation","dictionary","nested"],"install":[{"cmd":"pip install flatten-json","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"flatten","correct":"from flatten_json import flatten"},{"symbol":"unflatten","correct":"from flatten_json import unflatten"},{"symbol":"flatten_preserve_lists","correct":"from flatten_json import flatten_preserve_lists"}],"quickstart":{"code":"from flatten_json import flatten, unflatten\n\n# Example nested dictionary\nnested_dict = {\n    \"id\": 1,\n    \"user\": {\"name\": \"Alice\", \"email\": \"alice@example.com\"},\n    \"orders\": [\n        {\"order_id\": \"A1\", \"items\": [\"apple\", \"banana\"]},\n        {\"order_id\": \"A2\", \"items\": [\"orange\"]}\n    ],\n    \"metadata\": {\"last_updated\": \"2023-10-26\"}\n}\n\n# Flatten the dictionary\nflattened_dict = flatten(nested_dict)\nprint(\"\\nFlattened Dictionary:\")\nprint(flattened_dict)\n# Expected output might look like (keys sorted differently based on Python version):\n# {\n#  'id': 1,\n#  'user_name': 'Alice',\n#  'user_email': 'alice@example.com',\n#  'orders_0_order_id': 'A1',\n#  'orders_0_items_0': 'apple',\n#  'orders_0_items_1': 'banana',\n#  'orders_1_order_id': 'A2',\n#  'orders_1_items_0': 'orange',\n#  'metadata_last_updated': '2023-10-26'\n# }\n\n# Unflatten the dictionary\nunflattened_dict = unflatten(flattened_dict)\nprint(\"\\nUnflattened Dictionary:\")\nprint(unflattened_dict)\n\n# Flattening while preserving lists (available from v0.1.7+)\nfrom flatten_json import flatten_preserve_lists\nflattened_preserve_lists = flatten_preserve_lists(nested_dict)\nprint(\"\\nFlattened (preserving lists) Dictionary:\")\nprint(flattened_preserve_lists)\n# Expected output might look like:\n# {\n#  'id': 1,\n#  'user_name': 'Alice',\n#  'user_email': 'alice@example.com',\n#  'orders': [\n#   {'order_id_': 'A1', 'items_0': 'apple', 'items_1': 'banana'},\n#   {'order_id_': 'A2', 'items_0': 'orange'}\n#  ],\n#  'metadata_last_updated': '2023-10-26'\n# }","lang":"python","description":"This quickstart demonstrates the core `flatten` and `unflatten` functionalities. It also shows `flatten_preserve_lists` for scenarios where nested lists should remain lists, but their dictionary elements are still flattened. By default, `flatten` converts list items into indexed keys."},"warnings":[{"fix":"Use version `0.1.14` or later, or `0.1.12` or earlier.","message":"Version `0.1.13` was a broken release and was subsequently yanked from PyPI. Avoid installing or using this specific version.","severity":"breaking","affected_versions":"0.1.13"},{"fix":"For versions 0.1.7 and later, import and use `flatten_preserve_lists` instead of `flatten` if list preservation is desired. Otherwise, be aware of the indexed key convention.","message":"The default `flatten` function converts elements of lists into indexed keys (e.g., `list_0_item`, `list_1_item`). If you need to preserve lists as actual list structures (e.g., for compatibility with other tools or specific processing), use `flatten_preserve_lists`.","severity":"gotcha","affected_versions":"<0.1.7 (feature not present), all versions for default behavior"},{"fix":"Ensure that the keys in your flattened dictionary adhere to the `flatten-json` naming convention, particularly for list indices (e.g., `_0`, `_1`). Test `unflatten` thoroughly with your specific data before relying on it for critical operations.","message":"The `unflatten` function relies on specific key patterns (e.g., `key_0_sub_key`, `key_1_sub_key`) to reconstruct nested dictionaries and lists. If your flattened data did not originate from `flatten-json` or uses different naming conventions, `unflatten` might produce unexpected results or fail to reconstruct the original structure accurately, especially for complex nested lists.","severity":"gotcha","affected_versions":"All versions with `unflatten` (0.1.5+)"},{"fix":"Update imports to `from flatten_json import flatten` and `from flatten_json import unflatten` for clarity and consistency with modern usage.","message":"In earlier versions (prior to 0.1.5), the primary flattening function might have been referenced directly as `flatten_json.flatten_json`. While `from flatten_json import flatten` is the idiomatic Python way to import the function, older codebases might exhibit the less conventional pattern.","severity":"deprecated","affected_versions":"<0.1.5"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}