Tabular-JSON Python
This is a Python implementation of Tabular-JSON, a superset of JSON adding CSV-like tables.
Install
Install via PyPI: https://pypi.org/project/tabularjson/
pip install tabularjson
Use
from tabularjson import parse, stringify, StringifyOptions
text = """{
"id": 1,
"name": "Brandon",
"friends": (
"id", "name"
2, "Joe"
3, "Sarah"
)
}
"""
data = parse(text)
print(data)
# {
# 'id': 1,
# 'name': 'Brandon',
# 'friends': [
# {'id': 2, 'name': 'Joe'},
# {'id': 3, 'name': 'Sarah'}
# ]
# }
data["friends"].append({"id": 4, "name": "Alan"})
options: StringifyOptions = {"indentation": 4, "trailing_commas": False}
updatedText = stringify(data, options)
print(updatedText)
# {
# "id": 1,
# "name": "Brandon",
# "friends": (
# "id", "name"
# 2, "Joe"
# 3, "Sarah"
# 4, "Alan"
# )
# }
API
parse
Parse a string containing Tabular-JSON data into JSON.
Syntax:
data = parse(text)
Where:
textis a string containing Tabular-JSON datadatais the parsed data, returned by the function
Example:
from tabularjson import parse
text = """{
"id": 1,
"name": "Brandon",
"friends": (
"id", "name"
2, "Joe"
3, "Sarah"
)
}
"""
data = parse(text)
print(data)
# {
# 'id': 1,
# 'name': 'Brandon',
# 'friends': [
# {'id': 2, 'name': 'Joe'},
# {'id': 3, 'name': 'Sarah'}
# ]
# }
stringify
Stringify data into a string containing Tabular-JSON.
Syntax:
text = stringify(data, options)
Where:
datais a JSON object or arrayoptionsis an optional object which can have the following properties:indentation: int | str | Nonean integer specifying the number of spaces in the indentation, or a string containing the indentation itself, like"\t"to get tab indentation. WhenNone(default), the output will not be indented.trailing_commas: boolwhen true, the output will contain trailing commas after the last item in an array and the last key/value pair in an object.Falseby default.output_as_table: Callable[[TabularData[T], Path], bool]a callback specifying whether to an array containing tabular data as table or not. This option is explained in detail in the section Output as table below.
textis a string containing Tabular-JSON data, returned by the function
Example:
from tabularjson import stringify, StringifyOptions
data = {
"id": 1,
"name": "Brandon",
"friends": [
{"id": 2, "name": "Joe"},
{"id": 3, "name": "Sarah"}
]
}
options: StringifyOptions = {"indentation": 4, "trailing_commas": False}
text = stringify(data, options)
print(text)
# {
# "id": 1,
# "name": "Brandon",
# "friends": (
# "id", "name"
# 2, "Joe"
# 3, "Sarah"
# )
# }
Output as table
Data is tabular when it is an array containing at least one item, where every item is an object. Stringifying tabular data as a table normally results in the smallest output, but it is not always the most readable way. For example having nested tables inside a table is not very readable. Also, having a table containing a field like "comments" or "description" which contains long texts results in a very wide column, making the formatted table hard to read.
Depending on your use case, you can configure a strategy for when to output tabular data as a table. This can be done using the option output_as_table. The lambda function output_as_table(tabular_data, path) is invoked for all tabular data in the input json and returns true when the data should be stringified as a table.
The library comes with a number of built-in utility functions that can be used with output_as_table:
always(tabular_data [, path]): always serialize tabular data as a table, also when the data contains nested arrays. This is the default value of optionoutput_as_table.no_nested_arrays(tabular_data [, path]): serialize tabular data as a table when the data does not contain nested arrays.no_nested_tables(tabular_data [, path]): serialize tabular data as a table when the data does not contain nested tables. Allows nested arrays when the contain primitive values like numbers or strings.is_homogeneous(tabular_data [, path]): serialize tabular data as a table when the structure is homogeneous, that is every item has the exact same keys and nested keys.no_long_strings(tabular_data [, path [, max_length]]): serialize tabular data as a table when the data does not contain long text fields.
Usage example:
from tabularjson import stringify, is_homogeneous, StringifyOptions
data = {
"careTakers": [
{"id": 1001, "name": "Joe"},
{"id": 1002, "name": "Sarah"}
],
"animals": [
{
"animalId": 1,
"name": "Elephant",
"description": "Elephants are the largest living land animals.",
},
{
"animalId": 2,
"name": "Giraffe"
},
],
}
# Output as table only when the data is homogeneous: when all list items have the same keys
print(stringify(data, {"indentation": 2, "output_as_table": is_homogeneous}))
# {
# "careTakers": (
# "id", "name"
# 1001, "Joe"
# 1002, "Sarah"
# ),
# "animals": [
# {
# "animalId": 1,
# "name": "Elephant",
# "description": "Elephants are the largest living land animals."
# },
# {
# "animalId": 2,
# "name": "Giraffe"
# }
# ]
# }
See example2_output_as_table.py for a more detailed usage example.
License
Released under the ISC license.
Metadata
Release files for tabularjson 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tabularjson-2.0.0.tar.gz | 16.0 kB | Without provenance | Details for tabularjson-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tabularjson-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for tabularjson-2.0.0-py3-none-any.whl |
Total release size: 29.2 kB
Release files / tabularjson-2.0.0.tar.gz
| Download URL | tabularjson-2.0.0.tar.gz |
|---|---|
| Size | 16.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc98bcbd44b8e3ab91a1605fe372621c7142c1865c2a486ea31fadb23d81d8a8
|
|
BLAKE2b-256 checksum How to use checksums |
6120d303e151d489a1cba9a9750e16a92979cf7a634dfd9ee5fcde5ebe801ee6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / tabularjson-2.0.0-py3-none-any.whl
| Download URL | tabularjson-2.0.0-py3-none-any.whl |
|---|---|
| Size | 13.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11a07e6e4acb48f354d7e63cad6128ec06c8b839f0b169b08a8a4e50c0caf085
|
|
BLAKE2b-256 checksum How to use checksums |
8e375e6eddee492c37057b7e925b8e486ab76498385bd910f19d173f5c05c320
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for tabularjson 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.