j2toon 0.1.1

Python helpers to convert between JSON-compatible data and TOON.

j2toon

j2toon is a simple Python tool that converts JSON data into TOON format and converts it back. TOON is a human-readable data format that's easier to read and edit than JSON. You don't need to learn all the TOON rules—the tool automatically chooses the best format for your data.

Why use j2toon?

• Easy to use – just two simple functions: json2toon and toon2json
• Smart formatting – automatically formats your data in the most readable way (tables, lists, or nested blocks)
• No extra packages needed – works with just Python, no additional libraries required

Installation

Install j2toon using pip or uv:

pip install j2toon

or

  uv pip install j2toon

Usage

Here's a simple example showing how to convert JSON to TOON and back:

from j2toon import json2toon, toon2json

# Start with some JSON data
document = {
    "items": [
        {"sku": "A1", "qty": 2, "price": 9.99},
        {"sku": "B2", "qty": 1, "price": 14.5}
    ],
    "tags": ["hardware", "beta"]
}

# Convert JSON to TOON format
text = json2toon(document)
print(text)
# items[2]{sku,qty,price}:
#   A1,2,9.99
#   B2,1,14.5
# tags[2]: hardware,beta

# Convert back to JSON to verify it works
assert toon2json(text) == document

Command line

You can also use j2toon from the command line:

json2toon data.json -o data.toon        # Convert JSON to TOON
toon2json data.toon --indent 2          # Convert TOON back to JSON

Both commands support these options:

• --indent – how many spaces to use for indentation (default is 2)
• --delimiter – what character to use to separate values (default is comma)

Options

When using the functions in Python, you can customize the output with these options:

• indent – how many spaces to use for each level of nesting (default is 2)
• delimiter – what character to use to separate values in lists and tables. You can use "," (comma), "\t" (tab), or "|" (pipe)

Development

To set up the project for development:

pip install -e .
pytest

Requirements:

• Python 3.9 or higher
• Tests are in the tests/ folder and check that conversions work correctly in both directions

Maintainer

• Vishnu Prasad — [e-mail]

Learn More

For complete details about the TOON format, check out the official TOON specification. This tool focuses on the most commonly used parts of TOON to keep things simple and reliable.