{"id":7796,"library":"toon-format","title":"TOON Format for Python","description":"TOON (Token-Oriented Object Notation) is a compact, human-readable data format designed for LLM prompts to reduce token usage by 30-60% compared to JSON. It achieves this by eliminating redundant punctuation and using a tabular format for uniform data structures. The Python implementation, currently in beta (v0.9.0-beta.1), provides encoding and decoding functionalities, aiming for full compliance with the TOON specification.","status":"active","version":"0.9.0-beta.1","language":"en","source_language":"en","source_url":"https://github.com/toon-format/toon-python","tags":["LLM","AI","serialization","token-efficient","JSON alternative","data format"],"install":[{"cmd":"pip install toon-format","lang":"bash","label":"Standard Installation"},{"cmd":"pip install toon-format[openai]","lang":"bash","label":"With OpenAI Integration (for token counting)"},{"cmd":"pip install git+https://github.com/toon-format/toon-python.git","lang":"bash","label":"Install from GitHub (for latest beta)"}],"dependencies":[{"reason":"Required for accurate token counting when using OpenAI integration.","package":"tiktoken","optional":true}],"imports":[{"note":"The `encode` function is directly available from the top-level `toon_format` package.","wrong":"from toon_format.encoder import encode","symbol":"encode","correct":"from toon_format import encode"},{"note":"The `decode` function is directly available from the top-level `toon_format` package.","wrong":"from toon_format.decoder import decode","symbol":"decode","correct":"from toon_format import decode"},{"note":"File I/O functions are exposed at the top level.","wrong":"from toon_format.io import load, dump","symbol":"load, dump","correct":"from toon_format import load, dump"}],"quickstart":{"code":"from toon_format import encode, decode\n\n# Encode a simple Python dictionary to TOON\ndata_object = {\"name\": \"Alice\", \"age\": 30}\ntoon_object = encode(data_object)\nprint(f\"\\nEncoded Object:\\n{toon_object}\")\n# Expected output:\n# name: Alice\n# age: 30\n\n# Encode a list of uniform dictionaries (tabular array)\ndata_list = [\n    {\"id\": 1, \"name\": \"Widget\", \"price\": 9.99},\n    {\"id\": 2, \"name\": \"Gadget\", \"price\": 19.99}\n]\ntoon_list = encode(data_list)\nprint(f\"\\nEncoded List:\\n{toon_list}\")\n# Expected output:\n# [2]{id,name,price}:\n# 1,Widget,9.99\n# 2,Gadget,19.99\n\n# Decode TOON back to Python objects\ntoon_string_to_decode = \"\"\"\nitems[2]: apple,banana\n\"\"\"\ndecoded_data = decode(toon_string_to_decode)\nprint(f\"\\nDecoded Data:\\n{decoded_data}\")\n# Expected output: {'items': ['apple', 'banana']}","lang":"python","description":"This quickstart demonstrates how to encode Python dictionaries and lists into TOON format and decode TOON strings back into Python objects using `toon_format.encode` and `toon_format.decode` functions."},"warnings":[{"fix":"Review the GitHub repository for the latest API changes before upgrading to new beta versions or the eventual 1.0.0 release. Pin specific beta versions if stability is critical.","message":"The library is currently in beta (v0.9.x), and its API may change significantly before the 1.0.0 stable release.","severity":"breaking","affected_versions":"0.9.x-beta"},{"fix":"Evaluate TOON's token efficiency for your specific data structures. For deeply nested or irregular data, standard (compacted) JSON might still be more efficient or appropriate. Use TOON primarily for structured, tabular data fed to LLMs.","message":"TOON is primarily optimized for uniform arrays of objects (tabular data) and may not always yield significant token savings or be ideal for deeply nested or highly non-uniform JSON structures.","severity":"gotcha","affected_versions":"All"},{"fix":"Always install `toon-format` via `pip install toon-format` or directly from the official GitHub repository (`pip install git+https://github.com/toon-format/toon-python.git`) to guarantee you're using the intended library. Verify import paths (`from toon_format import ...`) match the official documentation.","message":"There are multiple Python implementations related to TOON (e.g., `py-toon-format`, `python-toon`, `toons`), leading to a fragmented ecosystem. Ensure you are using the official `toon-format/toon-python` implementation for the most up-to-date and spec-compliant version.","severity":"gotcha","affected_versions":"All"},{"fix":"If you need to parse potentially malformed or lenient TOON, use `decode(toon_string, options={'strict': False})`. However, be aware that disabling strict mode might lead to unexpected parsing results for invalid TOON.","message":"The `decode` function operates in 'strict' mode by default, which means it will raise errors for any syntax inconsistencies, array length mismatches, or delimiter issues in the TOON string.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your import statement is `from toon_format import encode, decode` (using an underscore in `toon_format`) after installing `pip install toon-format`.","cause":"You likely installed the package using `pip install toon-format`, but the Python import path uses underscores, not hyphens.","error":"ModuleNotFoundError: No module named 'toon_format'"},{"fix":"Correct the TOON string so that the declared array length `[N]` precisely matches the number of data rows, or set `strict=False` during decoding (e.g., `decode(toon_string, options={'strict': False})`) to allow lenient parsing.","cause":"The TOON string you are trying to decode has an array length declared (e.g., `items[3]`) that does not match the actual number of items provided in the data rows.","error":"SyntaxError: Invalid TOON format: Array length mismatch. Expected 3 items, got 2."},{"fix":"Review your TOON string to ensure all nested objects use exactly 2 spaces per indentation level and are consistent throughout the document. Avoid using tabs for indentation.","cause":"TOON strictly enforces 2-space indentation for nested objects, similar to YAML. Inconsistent or incorrect indentation will result in a parsing error.","error":"ValueError: Invalid TOON format: Indentation error."}]}