flattype 1.11.0__py3-none-any.whl

flattype/asgi.py

@@ -0,0 +1,93 @@
+"""ASGI middleware for FastAPI, Starlette, Litestar, Quart or any ASGI app. No dependencies.
+
+    from flattype.asgi import FlatMiddleware
+    app.add_middleware(FlatMiddleware)
+
+JSON responses are re-encoded as Flat Notation when the client asks for ``text/x-flat`` (and prefers it to
+JSON). Everyone else gets the JSON unchanged. ``Vary: Accept`` is always added so caches keep the two apart.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Awaitable, MutableMapping
+from typing import Any, Callable
+
+from ._encode import encode
+from .negotiate import add_vary, prefers_flat
+
+Scope = MutableMapping[str, Any]
+Message = MutableMapping[str, Any]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+_JSON = re.compile(r"[/+]json\b", re.I)
+CONTENT_TYPE = b"text/x-flat; charset=utf-8"
+
+
+def _header(headers: list[tuple[bytes, bytes]], name: bytes) -> bytes | None:
+    for k, v in headers:
+        if k.lower() == name:
+            return v
+    return None
+
+
+def _without(headers: list[tuple[bytes, bytes]], *names: bytes) -> list[tuple[bytes, bytes]]:
+    return [(k, v) for k, v in headers if k.lower() not in names]
+
+
+class FlatMiddleware:
+    """Answers in Flat Notation when the client asks for it. Encode options (``delimiter``, ``indent``, ``tabular``)
+    are passed to :func:`flattype.encode`."""
+
+    def __init__(self, app: ASGIApp, **encode_options: Any) -> None:
+        self.app = app
+        self.options = encode_options
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        accept = _header(list(scope.get("headers") or []), b"accept")
+        wanted = prefers_flat(accept.decode("latin-1") if accept else None)
+        start: Message | None = None
+        body: list[bytes] = []
+        passthrough = True
+
+        async def wrapped(message: Message) -> None:
+            nonlocal start, passthrough
+            if message["type"] == "http.response.start":
+                headers = list(message.get("headers") or [])
+                vary = _header(headers, b"vary")
+                headers = _without(headers, b"vary") + [
+                    (b"vary", add_vary(vary.decode("latin-1") if vary else None).encode("latin-1"))
+                ]
+                message = {**message, "headers": headers}
+                ctype = _header(headers, b"content-type")
+                passthrough = not (wanted and ctype is not None and _JSON.search(ctype.decode("latin-1")))
+                if passthrough:
+                    await send(message)
+                else:
+                    start = message
+                return
+            if message["type"] != "http.response.body" or passthrough:
+                await send(message)
+                return
+            body.append(message.get("body", b""))
+            if message.get("more_body", False):
+                return
+            assert start is not None
+            raw = b"".join(body)
+            try:
+                payload = encode(json.loads(raw), **self.options).encode("utf-8")
+                headers = _without(start["headers"], b"content-type", b"content-length")
+                headers += [(b"content-type", CONTENT_TYPE), (b"content-length", str(len(payload)).encode())]
+                start = {**start, "headers": headers}
+            except (ValueError, TypeError, RecursionError):
+                payload = raw  # not valid JSON after all: send it as it was
+            await send(start)
+            await send({"type": "http.response.body", "body": payload, "more_body": False})
+
+        await self.app(scope, receive, wrapped)

flattype/negotiate.py

@@ -0,0 +1,47 @@
+"""Content negotiation, with the same rules as ``@flattype/http``."""
+
+from __future__ import annotations
+
+MEDIA_TYPE = "text/x-flat"
+#: The ``Accept`` header a client sends: Flat Notation first, JSON as the fallback.
+ACCEPT = f"{MEDIA_TYPE}, application/json;q=0.9, */*;q=0.1"
+
+
+def _quality(accept: str, media_type: str) -> float:
+    best = -1.0
+    for part in accept.split(","):
+        media, *params = part.strip().split(";")
+        if media.strip().lower() != media_type:
+            continue
+        q = 1.0
+        for p in params:
+            k, _, v = p.partition("=")
+            if k.strip() == "q":
+                try:
+                    q = float(v)
+                except ValueError:
+                    q = 0.0
+        best = max(best, 0.0 if q != q else q)
+    return best
+
+
+def prefers_flat(accept: str | None) -> bool:
+    """True when the client asked for Flat Notation explicitly and prefers it to JSON.
+
+    Wildcards (``*/*``) never count, so ordinary clients keep getting JSON.
+    """
+    if not accept:
+        return False
+    flat = _quality(accept, MEDIA_TYPE)
+    return flat > 0 and flat >= _quality(accept, "application/json")
+
+
+def is_flat_type(content_type: str | None) -> bool:
+    return bool(content_type) and MEDIA_TYPE in content_type.lower()  # type: ignore[union-attr]
+
+
+def add_vary(current: str | None) -> str:
+    """Adds ``Accept`` to an existing ``Vary`` header value."""
+    if not current:
+        return "Accept"
+    return current if any(v.strip().lower() == "accept" for v in current.split(",")) else f"{current}, Accept"

flattype/starlette.py

@@ -0,0 +1,26 @@
+"""Starlette / FastAPI response class that always answers in Flat Notation. Needs ``pip install flattype[starlette]``.
+
+    from flattype.starlette import FlatResponse
+
+    @app.get("/users", response_class=FlatResponse)
+    def users():
+        return [{"id": 1, "name": "Alice"}]
+
+To answer in Flat Notation only when the client asks for it, use :class:`flattype.asgi.FlatMiddleware` instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from starlette.responses import Response
+
+from ._encode import encode
+
+
+class FlatResponse(Response):
+    media_type = "text/x-flat"
+    charset = "utf-8"
+
+    def render(self, content: Any) -> bytes:
+        return encode(content).encode("utf-8")

flattype-1.11.0.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: flattype
+Version: 1.11.0
+Summary: JSON <-> Flat Notation: compact key: value text for APIs and LLM prompts. The Python side of @flattype/* on npm.
+Project-URL: Homepage, https://karammm.github.io/flattype/docs/
+Project-URL: Documentation, https://karammm.github.io/flattype/docs/guide/python
+Project-URL: Repository, https://github.com/karammm/flattype
+Project-URL: Issues, https://github.com/karammm/flattype/issues
+Project-URL: Changelog, https://github.com/karammm/flattype/blob/main/CHANGELOG.md
+Author: karammm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,asgi,claude,fastapi,flatten,json,llm,serialization,tokens,toon
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.27; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+<h1 align="center">flattype</h1>
+
+<p align="center">
+  <b>JSON in, compact <code>key: value</code> text out.</b><br>
+  Flat Notation for Python APIs and LLM prompts: about half the size of JSON on lists, and easy for people and models to read.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/flattype/"><img src="https://img.shields.io/pypi/v/flattype?color=8b6cff" alt="PyPI"></a>
+  <a href="https://pypi.org/project/flattype/"><img src="https://img.shields.io/pypi/pyversions/flattype?color=8b6cff" alt="Python versions"></a>
+  <a href="https://github.com/karammm/flattype/actions/workflows/ci.yml"><img src="https://github.com/karammm/flattype/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/dependencies-0-2fd4b2" alt="No dependencies">
+  <a href="https://github.com/karammm/flattype/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/karammm/flattype/raw/main/docs/assets/flattype-intro.mp4">
+    <img src="https://raw.githubusercontent.com/karammm/flattype/main/docs/assets/flattype-intro.gif" width="800" alt="FlatType in 92 seconds: an API response encoded to Flat Notation, typed models, a server answering in Flat Notation or JSON, framework apps, the CLI, a FastAPI app with FlatMiddleware, and the size comparison with JSON">
+  </a><br>
+  <sub>▶ <a href="https://github.com/karammm/flattype/raw/main/docs/assets/flattype-intro.mp4">Watch the 92-second intro</a>. The Python part (step 6) is a real FastAPI app.</sub>
+</p>
+
+---
+
+This is the Python side of [FlatType](https://github.com/karammm/flattype), whose `@flattype/*` packages cover JavaScript, React, Vue, Angular, Svelte and Solid. Both write **exactly the same text**, so a FastAPI backend and a TypeScript frontend can talk Flat Notation to each other. A shared set of thousands of test cases checks this on every change.
+
+## Install
+
+```bash
+pip install flattype
+```
+
+Python 3.9+, no dependencies. `pip install "flattype[starlette]"` adds the optional `FlatResponse` class.
+
+## Quick start
+
+```python
+import flattype
+
+flattype.encode({"name": "John", "age": 30, "city": "New York"})
+# name: John
+# age: 30
+# city: New York
+
+flattype.decode("name: John\nage: 30")  # {'name': 'John', 'age': 30}
+```
+
+Lists, the shape of most API responses, become tables. Keys are written once, and nested dicts become dot paths:
+
+```python
+flattype.encode({
+    "page": 1,
+    "users": [
+        {"id": 1, "name": "Alice", "address": {"city": "Paris"}},
+        {"id": 2, "name": "Bob", "address": {"city": "Delhi"}},
+    ],
+})
+# page: 1
+# users[2]{id,name,address.city}:
+#   1, Alice, Paris
+#   2, Bob, Delhi
+```
+
+`flattype.dumps` and `flattype.loads` are aliases, if you prefer the `json` names.
+
+## FastAPI, Starlette and any ASGI app
+
+One line. Clients that ask for `text/x-flat` get Flat Notation, and everyone else gets the same JSON as before:
+
+```python
+from fastapi import FastAPI
+from flattype.asgi import FlatMiddleware
+
+app = FastAPI()
+app.add_middleware(FlatMiddleware)
+
+@app.get("/users")
+def users():
+    return {"users": USERS}  # plain FastAPI
+```
+
+```console
+$ curl localhost:3000/users
+{"users":[{"id":1,"name":"Alice Martin","role":"admin"},{"id":2,"name":"Bob Singh","role":"editor"}]}
+
+$ curl -H "Accept: text/x-flat" localhost:3000/users
+users[2]{id,name,role}:
+  1, Alice Martin, admin
+  2, Bob Singh, editor
+```
+
+- **How it decides:** only JSON responses (`application/json` or `+json`) are converted, and only when the request's `Accept` header names `text/x-flat` and prefers it to JSON. A browser's `*/*` never counts. These are the same rules as `@flattype/http`.
+- **Caching:** `Vary: Accept` is added to every response, so caches keep the two formats apart.
+- **Dependencies:** none. It's plain ASGI, so it also works with Litestar, Quart or a raw ASGI app.
+- **Clients:** on the JavaScript side, `flatFetch` from [`@flattype/http`](https://www.npmjs.com/package/@flattype/http) or the React, Vue, Angular and Svelte hooks send that header for you.
+
+To always answer in Flat Notation from one route, use the response class:
+
+```python
+from flattype.starlette import FlatResponse
+
+@app.get("/export", response_class=FlatResponse)
+def export():
+    return {"users": USERS}
+```
+
+The [FastAPI example](https://github.com/karammm/flattype/tree/main/examples/python-fastapi) runs with one command.
+
+## Typed models with Pydantic
+
+`decode` returns plain dicts and lists, so Pydantic validates them like any parsed JSON:
+
+```python
+from datetime import datetime
+from pydantic import BaseModel, TypeAdapter
+
+class User(BaseModel):
+    id: int
+    full_name: str
+    created_at: datetime
+
+users = TypeAdapter(list[User]).validate_python(flattype.decode(text)["users"])
+# [User(id=1, full_name='Alice', created_at=datetime.datetime(2026, 1, 1, 9, 0, tzinfo=TzInfo(0)))]
+```
+
+## Claude and other LLMs
+
+You pay for every character you send to a model, and on lists Flat Notation is about half the characters of JSON. `flattype.ai` has the helpers from [`@flattype/ai`](https://www.npmjs.com/package/@flattype/ai), with the same output:
+
+```python
+import anthropic
+from flattype.ai import to_prompt, output_instructions, from_model_output
+
+client = anthropic.Anthropic()
+message = client.messages.create(
+    model="claude-opus-5-5",
+    max_tokens=2048,
+    messages=[{
+        "role": "user",
+        "content": f"{to_prompt(orders, name='orders')}\n\nWhich customers ordered twice? "
+                   + output_instructions({"customers": [{"name": "Alice", "orders": 2}]}),
+    }],
+)
+reply = message.content[0].text
+customers = from_model_output(reply)  # or from_model_output(reply, Customer, many=True) with a Pydantic model
+```
+
+- **`to_prompt(data)`:** the data as Flat Notation inside a `<data>` tag, with a one-line legend that explains the format.
+- **`output_instructions(example)`:** asks the model to answer in Flat Notation, with an example of the shape you expect.
+- **`from_model_output(reply)`:** finds the data in the reply (a `<data>` block, a code fence, or plain JSON instead) and skips prose lines around it. It runs in linear time, even on hostile replies.
+- **`count_tokens(anthropic.Anthropic(), data)`:** compares JSON with Flat Notation using Claude's free token counter.
+- **`tool_result(data)` and `claude_tool_result(id, data)`:** tool results for MCP servers and the Claude API.
+
+## More
+
+**Lenient decoding** for text from models or people: `decode(text, strict=False)` fills in what's missing instead of raising. Add `skip_invalid_lines=True` to drop lines that aren't Flat Notation.
+
+**Streaming:** `Decoder` reads chunks as they arrive, and calls `on_row` for each table row as soon as its line is complete:
+
+```python
+d = flattype.Decoder(on_row=lambda row: print(row.path, row.index, row.value), keep_rows=False)
+for chunk in response.iter_text():
+    d.write(chunk)
+d.end()
+```
+
+**Shared objects and cycles:** `encode(x, refs=True)` writes an object that appears more than once only once, then `path = first.path` everywhere else. `decode(text, refs=True)` gives back the same objects, not copies. It's off by default on both ends, because a few reference lines can describe a graph that is endless when walked.
+
+```python
+team = {"lead": {"id": 1}}
+team["members"] = [team["lead"]]
+team["lead"]["team"] = team
+flattype.encode(team, refs=True)
+# lead.id: 1
+# lead.team = ~
+# members[0] = lead
+```
+
+**Other types:** `encode(x, default=fn)` works like `json.dumps(default=...)`. Tuples are written as lists. `encode`, `decode`, `delimiter="|"` / `"\t"`, `indent`, `tabular=False`, `flatten` / `unflatten` and `stats` match the JavaScript options.
+
+## Same text as JavaScript
+
+Every case in [`conformance/`](https://github.com/karammm/flattype/tree/main/conformance) is generated from `@flattype/core` and `@flattype/ai`, and the Python package must match it exactly. That's 990 encode cases, 3,215 decode cases (1,965 of them errors, compared message, line and column), 150 object graphs, and 425 prompt and model-reply cases. A few things follow from that:
+
+- **Floats are written the way JavaScript writes them**, with `1e+21`, `1e-7` and `100`. So a float with no fractional part (`30.0`) decodes as the int `30`. Floats of 1e16 or more come back as an int with JavaScript's digits: the same number once converted to float, but not exactly equal to it.
+- **Ints are exact, however large.** JavaScript would round anything past 2⁵³. A literal longer than 4,300 digits is read as a float, so it can't hit Python's slow and limited `int()` path.
+- **Error columns count code points.** JavaScript counts UTF-16 units, so the two differ only after an emoji or another character outside the Basic Multilingual Plane.
+
+## Performance
+
+It's pure Python. For 1,000 users with a nested address (Python 3.13, Apple M-series):
+
+| | Size | Encode | Decode |
+| --- | ---: | ---: | ---: |
+| `json` (minified, C accelerated) | 114 KB | 0.5 ms | 0.45 ms |
+| `flattype` | 59 KB (−48%) | 4.6 ms | 3.9 ms |
+
+The win is in bytes on the wire and tokens in a prompt, not CPU time. Linear-time tests on hostile input (long digit runs, deep paths, long lines streamed in tiny chunks, model replies full of prose or lookalike tags) run in CI.
+
+## Links
+
+- **Docs:** [karammm.github.io/flattype/docs](https://karammm.github.io/flattype/docs/), including the [format specification](https://karammm.github.io/flattype/docs/guide/format)
+- **Playground:** [karammm.github.io/flattype](https://karammm.github.io/flattype/)
+- **Security:** [policy and guarantees](https://karammm.github.io/flattype/docs/guide/security)
+- **Changes:** [CHANGELOG](https://github.com/karammm/flattype/blob/main/CHANGELOG.md)
+
+MIT © karammm

flattype-1.11.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+flattype/__init__.py,sha256=XnhlwwXSiuj9mR-s7-I_iLeZS2ROIevbva2aGemTr9U,1582
+flattype/_decode.py,sha256=OyprVm01s_A-4VfSho8n8od57eo8GM5WORvp8UivFD8,11409
+flattype/_encode.py,sha256=O5J5yexa8Ol-KmEIo1TV_UQdXh_kdwm4OD6AP9npVBE,6951
+flattype/_flatten.py,sha256=YE9ea0a4hFeD1Zvr39kAfQ3B4uxtLk3T3LN_UHo5VXs,2110
+flattype/_path.py,sha256=yG1rz8sflrwWzwzq9qKHG6CUhm7EXGZDZncgOURcy-Y,10774
+flattype/_syntax.py,sha256=PdjCQI_ily0y7oJJuAd9MQDeOyXGv4EDiOJLST1o_-g,5342
+flattype/ai.py,sha256=SZ0nQDsKxQdSR6xK_dIXRv_62gOVyoXVUFrqE-vQmdQ,6712
+flattype/asgi.py,sha256=jYUNG62L55FpnkeGisF55hcUMa0UEq2_sW-qTkQDvM8,3795
+flattype/negotiate.py,sha256=fzapsIkLAyZOfPZHJwsE2JG1uE3tJopURmlAIK6QiNY,1578
+flattype/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flattype/starlette.py,sha256=sC2MyRCH4hpLqiWAx5iPUw85iTP8o1bXV-s5QHUqVDc,708
+flattype-1.11.0.dist-info/METADATA,sha256=sPqBwBdDwH14Mp5wFEIoq5ORVyT1ElZhG8sMBNsCiY0,11294
+flattype-1.11.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+flattype-1.11.0.dist-info/licenses/LICENSE,sha256=OXM2ik92vIvE849OIfPp1fCN7TFVL6KqosdOQhKY-bE,1081
+flattype-1.11.0.dist-info/RECORD,,

flattype-1.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

flattype-1.11.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlatType.js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.