{"id":14842,"library":"python-toon","title":"Python TOON (Token-Oriented Object Notation)","description":"python-toon is a Python library for encoding and decoding TOON (Token-Oriented Object Notation), a compact data format optimized for Large Language Models (LLMs). It provides bidirectional JSON-to-TOON conversion, aiming to reduce token costs by 30-60% compared to JSON. The current version is 0.1.3, featuring alignment with the official TOON specification (v1.2 for decoding) and command-line interface support. However, users should note that the original `xaviviro/python-toon` repository is officially deprecated in favor of `toon-format/toon-python` as the main community-driven implementation.","status":"deprecated","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/xaviviro/python-toon","tags":["serialization","json","llm","data-interchange","toon","token-efficiency"],"install":[{"cmd":"pip install python-toon","lang":"bash","label":"Install stable version (deprecated)"},{"cmd":"pip install toon-format/toon-python","lang":"bash","label":"Install recommended replacement (beta)"}],"dependencies":[],"imports":[{"note":"The `encode` and `decode` functions are directly importable from the `toon` package. The package name on PyPI is `python-toon` but the import path is `toon`.","wrong":"import toon.encode","symbol":"encode","correct":"from toon import encode"},{"note":"The `encode` and `decode` functions are directly importable from the `toon` package. The package name on PyPI is `python-toon` but the import path is `toon`.","symbol":"decode","correct":"from toon import decode"}],"quickstart":{"code":"from toon import encode, decode\n\n# Example 1: Encode a simple object\ndata_object = {\"name\": \"Alice\", \"age\": 30}\ntoon_output_obj = encode(data_object)\nprint(\"Encoded object:\\n\" + toon_output_obj)\n# Expected output for data_object:\n# name: Alice\n# age: 30\n\n# Example 2: Encode a tabular array (list of uniform objects)\ndata_list = [\n    {\"id\": 1, \"name\": \"Alice\", \"active\": True},\n    {\"id\": 2, \"name\": \"Bob\", \"active\": False},\n    {\"id\": 3, \"name\": \"Charlie\", \"active\": True}\n]\ntoon_output_list = encode(data_list)\nprint(\"\\nEncoded tabular list:\\n\" + toon_output_list)\n# Expected output for data_list:\n# [3,]{id,name,active}:\n# 1,Alice,true\n# 2,Bob,false\n# 3,Charlie,true\n\n# Example 3: Decode TOON back to Python\ntoon_string = \"\"\"users[3]{id,name,role}:\n1,Alice,admin\n2,Bob,user\n3,Charlie,user\"\"\"\ndecoded_data = decode(toon_string)\nprint(\"\\nDecoded data:\")\nprint(decoded_data)\n# Expected output for decoded_data:\n# {'users': [{'id': 1, 'name': 'Alice', 'role': 'admin'}, {'id': 2, 'name': 'Bob', 'role': 'user'}, {'id': 3, 'name': 'Charlie', 'role': 'user'}]}\n","lang":"python","description":"This quickstart demonstrates how to use `encode` to convert Python dictionaries and lists into TOON format, showcasing both simple objects and tabular arrays. It also shows how to use `decode` to convert a TOON string back into a Python object."},"warnings":[{"fix":"Switch to `pip install git+https://github.com/toon-format/toon-python.git` (or the PyPI version when available) and update imports from `from toon import encode, decode` to `from toon_format import encode, decode` as seen in the new library's quickstart.","message":"The `xaviviro/python-toon` library is officially deprecated. Users are advised to migrate to the `toon-format/toon-python` repository for future development and support, which may involve changes to package name and import paths.","severity":"breaking","affected_versions":"All versions (v0.1.x) of `xaviviro/python-toon`"},{"fix":"Monitor the official GitHub repository for release notes and changes. Pin dependencies to exact versions to prevent unexpected breakage in production environments.","message":"The new, recommended `toon-format/toon-python` library is currently in beta (v0.9.x), and its API may change before the 1.0.0 stable release. This means that users should expect potential breaking changes in minor versions.","severity":"gotcha","affected_versions":"All v0.x versions of `toon-format/toon-python`"},{"fix":"Use a consistent indentation strategy (e.g., 2 or 4 spaces) and configure your editor to automatically convert tabs to spaces to avoid `IndentationError` during `decode` operations.","message":"TOON, like YAML, is sensitive to indentation. Incorrect or inconsistent indentation (e.g., mixing tabs and spaces) can lead to parsing errors when manually writing or manipulating TOON strings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure TOON input strictly adheres to the TOON specification. For more lenient parsing, check if the `decode` function offers a `strict=False` option (as seen in `toon-format/toon-python` documentation for `decode` options).","message":"Decoding TOON in `strict` mode can lead to `ValueError` or `SyntaxError` if the input TOON string contains minor non-conformances, such as invalid escape sequences, missing colons, malformed headers, or array length/delimiter mismatches.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install python-toon`. If using the new official implementation, it might be `from toon_format import ...` after installing `toon-format/toon-python`.","cause":"The Python package `python-toon` is not installed, or the import statement `from toon import ...` is attempting to import from a non-existent module name.","error":"ModuleNotFoundError: No module named 'toon'"},{"fix":"Carefully inspect the TOON string for syntax errors. Refer to the TOON specification for correct format. If the error is with programmatically generated TOON, verify the encoding logic. Ensure no common Python syntax errors are accidentally introduced if the TOON string is hardcoded.","cause":"The TOON string provided to `decode()` has fundamental syntax errors, such as missing required elements, malformed structures, or incorrect character usage that violates the TOON specification.","error":"SyntaxError: invalid syntax (during decode)"},{"fix":"Review the TOON string for consistency, particularly array lengths (`[N]`) matching actual item counts and correct delimiter usage. If lenient parsing is acceptable, check the `decode` options for a `strict` parameter and set it to `False`.","cause":"The TOON string is syntactically valid but semantically incorrect or violates data integrity checks (e.g., array length mismatches, invalid delimiters) especially when strict mode is enabled during decoding.","error":"ValueError: Invalid TOON input: ..."}],"ecosystem":"pypi"}