{"id":42726753,"url":"https://github.com/toon-format/toon-python","last_synced_at":"2026-01-29T16:42:57.569Z","repository":{"id":321989584,"uuid":"1087885653","full_name":"toon-format/toon-python","owner":"toon-format","description":"🐍 Community-driven Python implementation of TOON","archived":false,"fork":false,"pushed_at":"2025-12-02T08:51:49.000Z","size":167,"stargazers_count":556,"open_issues_count":18,"forks_count":43,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-12-21T01:53:22.853Z","etag":null,"topics":["python","serialization","toon"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toon-format.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T21:01:52.000Z","updated_at":"2025-12-19T12:02:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/toon-format/toon-python","commit_stats":null,"previous_names":["toon-format/toon-python"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/toon-format/toon-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toon-format%2Ftoon-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toon-format%2Ftoon-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toon-format%2Ftoon-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toon-format%2Ftoon-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toon-format","download_url":"https://codeload.github.com/toon-format/toon-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toon-format%2Ftoon-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28881006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T16:41:59.663Z","status":"ssl_error","status_checked_at":"2026-01-29T16:39:39.641Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","serialization","toon"],"created_at":"2026-01-29T16:42:57.008Z","updated_at":"2026-01-29T16:42:57.565Z","avatar_url":"https://github.com/toon-format.png","language":"Python","readme":"# TOON Format for Python\n\n[![Tests](https://github.com/toon-format/toon-python/actions/workflows/test.yml/badge.svg)](https://github.com/toon-format/toon-python/actions)\n[![Python Versions](https://img.shields.io/pypi/pyversions/toon_format.svg)](https://pypi.org/project/toon_format/)\n\n\u003e **⚠️ Beta Status (v0.9.x):** This library is in active development and working towards spec compliance. Beta published to PyPI. API may change before 1.0.0 release.\n\nCompact, human-readable serialization format for LLM contexts with **30-60% token reduction** vs JSON. Combines YAML-like indentation with CSV-like tabular arrays. Working towards full compatibility with the [official TOON specification](https://github.com/toon-format/spec).\n\n**Key Features:** Minimal syntax • Tabular arrays for uniform data • Array length validation • Python 3.8+ • Comprehensive test coverage.\n\n```bash\n# Beta published to PyPI - install from source:\ngit clone https://github.com/toon-format/toon-python.git\ncd toon-python\nuv sync\n\n# Or install directly from GitHub:\npip install git+https://github.com/toon-format/toon-python.git\n```\n\n## Quick Start\n\n```python\nfrom toon_format import encode, decode\n\n# Simple object\nencode({\"name\": \"Alice\", \"age\": 30})\n# name: Alice\n# age: 30\n\n# Tabular array (uniform objects)\nencode([{\"id\": 1, \"name\": \"Alice\"}, {\"id\": 2, \"name\": \"Bob\"}])\n# [2,]{id,name}:\n#   1,Alice\n#   2,Bob\n\n# Decode back to Python\ndecode(\"items[2]: apple,banana\")\n# {'items': ['apple', 'banana']}\n```\n\n## CLI Usage\n\n```bash\n# Auto-detect format by extension\ntoon input.json -o output.toon      # Encode\ntoon data.toon -o output.json       # Decode\necho '{\"x\": 1}' | toon -            # Stdin/stdout\n\n# Options\ntoon data.json --encode --delimiter \"\\t\" --length-marker\ntoon data.toon --decode --no-strict --indent 4\n```\n\n**Options:** `-e/--encode` `-d/--decode` `-o/--output` `--delimiter` `--indent` `--length-marker` `--no-strict`\n\n## API Reference\n\n### `encode(value, options=None)` → `str`\n\n```python\nencode({\"id\": 123}, {\"delimiter\": \"\\t\", \"indent\": 4, \"lengthMarker\": \"#\"})\n```\n\n**Options:**\n- `delimiter`: `\",\"` (default), `\"\\t\"`, `\"|\"`\n- `indent`: Spaces per level (default: `2`)\n- `lengthMarker`: `\"\"` (default) or `\"#\"` to prefix array lengths\n\n### `decode(input_str, options=None)` → `Any`\n\n```python\ndecode(\"id: 123\", {\"indent\": 2, \"strict\": True})\n```\n\n**Options:**\n- `indent`: Expected indent size (default: `2`)\n- `strict`: Validate syntax, lengths, delimiters (default: `True`)\n\n### Token Counting \u0026 Comparison\n\nMeasure token efficiency and compare formats:\n\n```python\nfrom toon_format import estimate_savings, compare_formats, count_tokens\n\n# Measure savings\ndata = {\"users\": [{\"id\": 1, \"name\": \"Alice\"}, {\"id\": 2, \"name\": \"Bob\"}]}\nresult = estimate_savings(data)\nprint(f\"Saves {result['savings_percent']:.1f}% tokens\")  # Saves 42.3% tokens\n\n# Visual comparison\nprint(compare_formats(data))\n# Format Comparison\n# ────────────────────────────────────────────────\n# Format      Tokens    Size (chars)\n# JSON            45             123\n# TOON            28              85\n# ────────────────────────────────────────────────\n# Savings: 17 tokens (37.8%)\n\n# Count tokens directly\ntoon_str = encode(data)\ntokens = count_tokens(toon_str)  # Uses tiktoken (gpt5/gpt5-mini)\n```\n\n**Requires tiktoken:** `uv add tiktoken` (benchmark features are optional)\n\n## Format Specification\n\n| Type | Example Input | TOON Output |\n|------|---------------|-------------|\n| **Object** | `{\"name\": \"Alice\", \"age\": 30}` | `name: Alice`\u003cbr\u003e`age: 30` |\n| **Primitive Array** | `[1, 2, 3]` | `[3]: 1,2,3` |\n| **Tabular Array** | `[{\"id\": 1, \"name\": \"A\"}, {\"id\": 2, \"name\": \"B\"}]` | `[2,]{id,name}:`\u003cbr\u003e\u0026nbsp;\u0026nbsp;`1,A`\u003cbr\u003e\u0026nbsp;\u0026nbsp;`2,B` |\n| **Mixed Array** | `[{\"x\": 1}, 42, \"hi\"]` | `[3]:`\u003cbr\u003e\u0026nbsp;\u0026nbsp;`- x: 1`\u003cbr\u003e\u0026nbsp;\u0026nbsp;`- 42`\u003cbr\u003e\u0026nbsp;\u0026nbsp;`- hi` |\n\n**Quoting:** Only when necessary (empty, keywords, numeric strings, whitespace, structural chars, delimiters)\n\n**Type Normalization:** `Infinity/NaN/Functions` → `null` • `Decimal` → `float` • `datetime` → ISO 8601 • `-0` → `0`\n\n## Development\n\n```bash\n# Setup (requires uv: https://docs.astral.sh/uv/)\ngit clone https://github.com/toon-format/toon-python.git\ncd toon-python\nuv sync\n\n# Run tests (792 tests, 91% coverage, 85% enforced)\nuv run pytest --cov=toon_format --cov-report=term\n\n# Code quality\nuv run ruff check src/ tests/        # Lint\nuv run ruff format src/ tests/       # Format\nuv run mypy src/                     # Type check\n```\n\n**CI/CD:** GitHub Actions • Python 3.8-3.14 • Coverage enforcement • PR coverage comments\n\n## Project Status \u0026 Roadmap\n\nFollowing semantic versioning towards 1.0.0:\n\n- **v0.8.x** - Initial code set, tests, documentation ✅\n- **v0.9.x** - Serializer improvements, spec compliance testing, publishing setup (current)\n- **v1.0.0-rc.x** - Release candidates for production readiness\n- **v1.0.0** - First stable release with full spec compliance\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## Documentation\n\n- [📘 Full Documentation](docs/) - Complete guides and references\n- [🔧 API Reference](docs/api.md) - Detailed function documentation\n- [📋 Format Specification](docs/format.md) - TOON syntax and rules\n- [🤖 LLM Integration](docs/llm-integration.md) - Best practices for LLM usage\n- [📜 TOON Spec](https://github.com/toon-format/spec) - Official specification\n- [🐛 Issues](https://github.com/toon-format/toon-python/issues) - Bug reports and features\n- [🤝 Contributing](CONTRIBUTING.md) - Contribution guidelines\n\n## Contributors\n\n- [Xavi Vinaixa](https://github.com/xaviviro)\n- [David Pirogov](https://github.com/davidpirogov)\n- [Justar](https://github.com/Justar96)\n- [Johann Schopplich](https://github.com/johannschopplich)\n\n## License\n\nMIT License – see [LICENSE](LICENSE) for details\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoon-format%2Ftoon-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoon-format%2Ftoon-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoon-format%2Ftoon-python/lists"}