{"id":21917644,"url":"https://github.com/emilstenstrom/json-traverse","last_synced_at":"2025-10-04T21:57:10.262Z","repository":{"id":62572978,"uuid":"75553013","full_name":"EmilStenstrom/json-traverse","owner":"EmilStenstrom","description":"Parse complex json structures using a simple query syntax.","archived":false,"fork":false,"pushed_at":"2016-12-18T19:01:26.000Z","size":15,"stargazers_count":29,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T01:16:38.448Z","etag":null,"topics":["json","python","tree-traversal"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EmilStenstrom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-12-04T17:34:31.000Z","updated_at":"2024-11-13T15:35:17.000Z","dependencies_parsed_at":"2022-11-03T17:30:18.250Z","dependency_job_id":null,"html_url":"https://github.com/EmilStenstrom/json-traverse","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmilStenstrom%2Fjson-traverse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmilStenstrom%2Fjson-traverse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmilStenstrom%2Fjson-traverse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmilStenstrom%2Fjson-traverse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EmilStenstrom","download_url":"https://codeload.github.com/EmilStenstrom/json-traverse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249677742,"owners_count":21309621,"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":["json","python","tree-traversal"],"created_at":"2024-11-28T19:38:48.034Z","updated_at":"2025-10-04T21:57:05.208Z","avatar_url":"https://github.com/EmilStenstrom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# json-traverse\nParse complex JSON structures using a simple query syntax.\n\n## Why should you use json-traverse?\n\n- It makes parsing JSON easy and compact\n- The code is simple, only ~100 lines of code\n- It works with both Python 2 and Python 3\n- It includes a comprehensive unit test suite\n- It has no dependencies\n\n## Installation\n\n```bash\npip install json-traverse\n```\n\n## Usage\n\nLet's say we've fetched some data and stored it in a variable called `json_data`. All lines that start with \"\u003e\u003e\u003e \" are things that you type. All other lines are output from json-traverse. Follow along by starting your terminal and typing 'python'.\n\n```python\n\u003e\u003e\u003e from __future__ import unicode_literals  # Only needed for Python 2\n\u003e\u003e\u003e from jsontraverse.parser import JsonTraverseParser\n\n\u003e\u003e\u003e # We'll use the example JSON from [http://json.org/example.html]\n\u003e\u003e\u003e json_data = \"\"\"\n{\n  \"menu\": {\n    \"id\": \"file\",\n    \"value\": \"File\",\n    \"popup\": {\n      \"menuitem\": [\n        {\"value\": \"New\", \"onclick\": \"CreateNewDoc()\"},\n        {\"value\": \"Open\", \"onclick\": \"OpenDoc()\"},\n        {\"value\": \"Close\", \"onclick\": \"CloseDoc()\"}\n      ]\n    }\n  }\n}\n\"\"\"\n\n\u003e\u003e\u003e # Create a JsonTraverseParser. We do this once and can then parse\n\u003e\u003e\u003e # the same data multiple times.\n\u003e\u003e\u003e parser = JsonTraverseParser(json_data)\n\n\u003e\u003e\u003e # Now we're ready to type our first query against the structure above.\n\n\u003e\u003e\u003e # Let's start by getting the value of the menu:\n\u003e\u003e\u003e parser.traverse(\"menu.value\")\n'File'\n\n\u003e\u003e\u003e # Easy right? Now lets get all the values from all menu items:\n\u003e\u003e\u003e parser.traverse(\"menu.popup.menuitem.value\")\n['New', 'Open', 'Close']\n\n\u003e\u003e\u003e # Only the first menuitem?\n\u003e\u003e\u003e parser.traverse(\"menu.popup.menuitem.0.value\")\n'New'\n```\n\nSee the [tests](tests/test_parsing.py) for more examples.\n\n## How does it all work? How exactly does the algoritm work?\n\n1. You send in a query in the form of a string with parts separated by a period (.).\n2. Json-traverse splits that path into several items and tries to search through the json data step by step, each step reducing the data to a smaller set.\n3. Each item in the path is first checked to see if it's an array index. If it is, the data is treated as a list and only the data matching the index is returned.\n4. If it's not an index, it's treated as a dict key instead. The data is treated as an dict and only the data inside the specified key is returned.\n5. If you specified a dict key, but the data is a list, the result is split into as many parts as there are items in the list, and the key is searched for in each part.\n6. If at any time an invalid item is tried, searching stops and a None result is returned.\n\nSee the [parser code](jsontraverse/parser.py) for more details.\n\n## Interested in helping out?\n\nI's love to see suggestions on how this library can be better. It's still early, and I'm open to changing things based on your feedback.\n\n## Develop locally and run the tests\n\n```bash\ngit clone git@github.com:EmilStenstrom/json-traverse.git\ncd json-traverse\n```\n\nInstall `tox`:\n\n```sh\npip install tox\n```\n\nThen run all the tests over all Python versions (Make sure you have python2.7, python3.3, python3.4, and python3.5 on your PATH first):\n\n```sh\ntox\n```\n\nOr just the particular version you wish to test:\n\n```sh\ntox -e py35\n```\n\nYou can also have it watch the directory for changes and re-run the tests:\n\n```sh\ntox -e py35 -- -f\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilstenstrom%2Fjson-traverse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femilstenstrom%2Fjson-traverse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femilstenstrom%2Fjson-traverse/lists"}