![\"latest](\"https://img.shields.io/pypi/v/jsontable.svg\")
\n\n\n\n\n## How to install\n\nThe package is available through pypi. So simply go to your command line and:\n\n```bash\npip install jsontable\n```\nYou're also welcome to download the code from github and modify to suit your needs. And if you have time let me know what cool functionality you added and we can improve the project!\n\n## How it works\n\nIt works in a similar manner to JSON parsers\n1. Create a converter object\n2. Give the converter a list of paths you want to explore and how you want to name each column\n3. Give the converter a __decoded__ JSON object you want to read, and it returns a table\n\n## Usage\n\nHere is a quick example to get you going\n\n```python\nimport jsontable as jsontable\n\n#Create a list of paths you want to extract\npaths = [{\"$.id\":\"id\"},\t{\"$.name\":\"name\"}, {\"$.address.city\":\"city\"}]\n#The JSON object you want to explore\nsample = {\"id\":\"1\",\"name\":\"Foo\",\"address\":{\"city\":\"Bar\"}}\n\n#Create an instance of a converter\nconverter = jsontable.converter()\n#Set the paths you want to extract\nconverter.set_paths(paths)\n#Input a JSON to be interpreted\nconverter.convert_json(sample)\n```\n\nIn this case, you will get a table with two columns and two rows (header and first row of data) like these:\n\n```python\n[['id', 'name', 'city'], ['1', 'Foo', 'Bar']]\n```\n\nFor more examples, refer to the [tests folder](/tests)\n\n## How it works\n\n#### JSON Paths\n\nEach path you specify is a column in your final table. Each path that is setup is expanded according to the [standard JSON Path functionality](https://goessner.net/articles/JsonPath/). This is, for each path, the converter starts at the root of the JSON object and navigates each step (a.k.a node) of the path in order. When it reaches the final step in the path (a.k.a leaf), it outputs the resulting element of the JSON into the cell.\n\nThe __final cell value__ is converted based on the [standard JSON values](https://www.json.org/) as follows:\n\n|JSON Value|Conversion|Sample Output|\n|--|--|--|\n|object|stringified object |`'{\"city\":\"Bar\"}'`|\n|array|stringified array |`'[1,2,3]'`|\n|string|string|'Foo'|\n|number|number|4.7|\n|boolean|stringidied boolean|'False'|\n|null|None|None|\n|_missing value_ (i.e. the path did not find an element)|None|None|\n\nThe intention behind stringifying the object, array and boolean is to be able to pass the output to other data libraries (e.g [Pandas](https://pandas.pydata.org/)) or to a relational database. \n\n#### Array Expansion\n\n__With the exception of the final node__, array elements are automatically expanded into rows. So for example a path `'$.a.b'` applied to a JSON `{\"a\":[{\"b\":1},{\"b\":2}]}` would result into two rows `[[1],[2]]`. The array expansion functionality can be applied to the final node by explicitly using the `*` operator as a final step (e.g. `$.a.*`)\n\nExample:\n```python\npaths = [{\"$.name\":\"Name\"},{\"$.telephones.type\":\"Telephone Type\"},{\"$.telephones.number\":\"Telephone Number\"}]\nsample = {\n\t\t\t\"name\":\"Foo\",\n\t\t\t\"telephones\":[\n\t\t\t\t{\"type\":\"mobile\", \"number\":\"0000\"},\n\t\t\t\t{\"type\":\"home\", \"number\":\"1111\"}\n\t\t\t]\n\t\t}\nconverter = jsontable.converter()\nconverter.set_paths(paths)\nconverter.convert_json(sample)\n```\nResult:\n```\n[['Name', 'Telephone Number', 'Telephone Type'], ['Foo', '0000', 'mobile'], ['Foo', '1111', 'home']]\n```\n\nThe reverse of this functionality (not expand arrays if they are encountered before the end) is not implemented only due to the lack of need.\n\n#### Joining Columns\n\nSince a path may result in multiple rows, there is the need to be able to combine the result of each column into the same table. The joining mechanism is similar to an SQL join, where each cell (row-cell combination) is \"matched\" to a row in the result using a \"matching value\". The matching value in this case is the last common element of the paths. \n\nThis is best illustrated with an example, the following table shows the transformations applied to the sample JSON.\n\n```python\nsample = {\n\t\"contacts\":[\n\t\t{\n\t\t\t\"name\":\"Foo\",\n\t\t\t\"telephones\":[\n\t\t\t\t{\"type\":\"mobile\", \"number\":\"0000\"},\n\t\t\t\t{\"type\":\"home\", \"number\":\"1111\"}\n\t\t\t],\n\t\t\t\"emails\":[\n\t\t\t\t{\"type\":\"work\", \"email\":\"foo@w.com\"},\n\t\t\t\t{\"type\":\"personal\", \"email\":\"foo@p.com\"}\n\t\t\t]\n\t\t},\n\t\t{\n\t\t\t\"name\":\"Bar\",\n\t\t\t\"telephones\":[\n\t\t\t\t{\"type\":\"mobile\", \"number\":\"2222\"},\n\t\t\t\t{\"type\":\"home\", \"number\":\"3333\"}\n\t\t\t],\n\t\t\t\"emails\":[\n\t\t\t\t{\"type\":\"work\", \"email\":\"bar@w.com\"},\n\t\t\t\t{\"type\":\"personal\", \"email\":\"bar@p.com\"}\n\t\t\t]\n\t\t}\n\t]\n}\n```\n\n| Paths | Result |
|---|---|
\n\t\t\t\n[\n\t{\"$.contacts.name\":\"Name\"},\n\t{\"$.contacts.telephones.type\":\"Type\"},\n\t{\"$.contacts.telephones.number\":\"Number\"}\n]\n\t\t\t\n\t\t | \n\t\t\n\t\t\t\n[\n\t['Name', 'Type', 'Number'], \n\t['Foo', 'mobile', '0000'], \n\t['Foo', 'home', '1111'], \n\t['Bar', 'mobile', '2222'], \n\t['Bar', 'home', '3333']\n]\n\t\t\t\n\t\t | \n\t
\n\t\t\t\n[\n\t{\"$.contacts.name\":\"Name\"},\n\t{\"$.contacts.telephones.number\":\"Number\"},\n\t{\"$.contacts.emails.email\":\"Email\"}\n]\n\t\t\t\n\t\t | \n\t\t\n\t\t\t\n[\n\t['Name', 'Number', 'Email'], \n\t['Foo', '0000', 'foo@w.com'], \n\t['Foo', '1111', 'foo@w.com'],\n\t['Foo', '0000', 'foo@p.com'], \n\t['Foo', '1111', 'foo@p.com'], \n\t['Bar', '0000', 'bar@w.com'], \n\t['Bar', '1111', 'bar@w.com'],\n\t['Bar', '0000', 'bar@p.com'], \n\t['Bar', '1111', 'bar@p.com'], \n]\n\t\t\t\n\t\t | \n\t