{"id":2314,"library":"toons","title":"toons: High-Performance TOON Parser and Serializer","description":"toons is a high-performance Python library for parsing and serializing TOON (Token Oriented Object Notation), implemented in Rust for speed. It offers an API that mirrors Python's built-in `json` module, making it easy to convert Python objects to TOON strings and vice-versa. TOON is a token-efficient data serialization format specifically designed to reduce token counts for Large Language Models. The current version is 0.5.4, with frequent minor releases addressing fixes and specification compliance.","status":"active","version":"0.5.4","language":"python","source_language":"en","source_url":"https://github.com/alesanfra/toons","tags":["parsing","serialization","data format","rust","performance","llm","token-efficiency"],"install":[{"cmd":"pip install toons","lang":"bash","label":"Install `toons`"}],"dependencies":[],"imports":[{"symbol":"loads","correct":"from toons import loads"},{"symbol":"dumps","correct":"from toons import dumps"}],"quickstart":{"code":"import toons\n\n# Sample Python data\ndata = {\n    \"name\": \"Alice\",\n    \"age\": 30,\n    \"tags\": [\"python\", \"rust\", \"toon\"]\n}\n\n# Serialize Python data to TOON string\ntoon_string = toons.dumps(data)\nprint(\"--- TOON String ---\")\nprint(toon_string)\n# Expected output (simplified, actual format may vary slightly based on spec):\n# name: Alice\n# age: 30\n# tags[3]: python,rust,toon\n\n# Parse TOON string back to Python data\nparsed_data = toons.loads(toon_string)\nprint(\"\\n--- Parsed Python Data ---\")\nprint(parsed_data)\n# Expected output:\n# {'name': 'Alice', 'age': 30, 'tags': ['python', 'rust', 'toon']}\n\n# Example with tabular data (common for LLMs)\nusers = [\n    {\"id\": 1, \"name\": \"Bob\", \"active\": True},\n    {\"id\": 2, \"name\": \"Charlie\", \"active\": False}\n]\ntabular_toon = toons.dumps(users)\nprint(\"\\n--- Tabular TOON String ---\")\nprint(tabular_toon)\n# Expected output (simplified):\n# [2]{id,name,active}:\n# 1,Bob,true\n# 2,Charlie,false","lang":"python","description":"This quickstart demonstrates how to serialize a Python dictionary and a list of dictionaries (tabular data) into TOON format, and then parse a TOON string back into a Python object using `toons.dumps` and `toons.loads`, mirroring the standard `json` library API."},"warnings":[{"fix":"Review the TOON Specification v3.0 for any changes relevant to your data structures and update your TOON inputs/outputs accordingly.","message":"Version 0.5.0 introduced compliance with TOON Specification v3.0, potentially causing breaking changes for users relying on data formatted under older TOON specifications (e.g., v2.0 from versions 0.3.x). Ensure your TOON data adheres to v3.0 when upgrading.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Upgrade to `toons` version 0.5.3 or later to ensure correct handling of unicode and datetime types.","message":"Older versions (prior to 0.5.3) had issues with deserialization of special unicode characters and (prior to 0.5.2) with serialization of datetime objects. If you're handling complex strings or datetimes, ensure you are on a recent version.","severity":"gotcha","affected_versions":"<0.5.3"},{"fix":"Ensure your TOON input strictly adheres to the v3.0 specification, or pass `strict=False` to `toons.loads()` for more tolerant parsing, e.g., `toons.loads(toon_str, options={'strict': False})`.","message":"By default, `toons` enforces strict compliance with the TOON v3.0 specification. Malformed TOON strings (e.g., those with incorrect indentation, invalid escape sequences, or blank lines in arrays) will raise errors during parsing. For lenient parsing, strict mode can be explicitly disabled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.5.4':81 'address':86 'api':34 'built':40 'built-in':39 'complianc':90 'convert':48 'count':72 'current':78 'data':64,93 'design':68 'easi':46 'effici':63,100 'fix':87 'format':66,94 'frequent':83 'high':3,13 'high-perform':2,12 'implement':26 'json':42 'languag':75 'larg':74 'librari':16 'llm':97 'make':44 'minor':84 'mirror':36 'model':76 'modul':43 'notat':25 'object':24,50 'offer':32 'orient':23 'pars':18,91 'parser':6 'perform':4,14,96 'python':15,37,49 'reduc':70 'releas':85 'rust':28,95 'serial':8,20,65,92 'specif':67,89 'speed':30 'string':53 'token':22,62,71,99 'token-effici':61,98 'toon':1,5,9,21,52,58 'versa':57 'version':79 'vice':56 'vice-versa':55","created_at":"2026-04-09T18:52:41.294637+00:00","updated_at":"2026-04-16T23:02:37.674956+00:00","problems":[{"fix":"Import the `toons` module directly: `import toons` then use `toons.dumps()` or `toons.loads()`.","cause":"The `toons` library provides its `dumps` and `loads` functions directly under the main `toons` module, not within a nested `toons.json` submodule.","error":"ModuleNotFoundError: No module named 'toons.json'"},{"fix":"Convert the object to a TOON-serializable type before dumping, or provide a `default` function to `toons.dumps` to handle custom types: `toons.dumps(data, default=my_serializer_function)`.","cause":"The `toons.dumps` function encountered a Python object type (e.g., a custom class instance, set, or datetime object) that it does not inherently know how to convert into a TOON primitive.","error":"TypeError: Object of type <YourClassName> is not TOON serializable"},{"fix":"Verify the input string for malformation and ensure it strictly adheres to the TOON specification before passing it to `toons.loads`.","cause":"The input string provided to `toons.loads` is not a syntactically valid TOON document or contains malformed data.","error":"toons.TOONDecodeError: Invalid TOON string"},{"fix":"Install the Rust toolchain (`rustup install stable`, `rustup update`) and any necessary system build tools (e.g., `build-essential` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows), then retry `pip install toons`.","cause":"The `toons` library, being implemented in Rust, requires the Rust toolchain and potentially system build tools to compile its Python extension during installation, which were not found or configured on your system.","error":"ERROR: Failed building wheel for toons"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.7.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/alesanfra/toons","docs":null,"changelog":null,"pypi":"https://pypi.org/project/toons/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","llm-agents","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}