examples + READMEs: typed parse + walk + build/render flow

Old example showcased a single config and round-tripped it. New
example matches the cross-binding template (java/golang/csharp/python):

* Parse — typed reads (port -> int, ratio -> float, nested db).
* Walk — `isinstance` chain across the seven Python value types,
  with the `bool`-before-`int` gotcha called out.
* Build & render — construct a config dict in code (with nested
  upstreams) and render to Ktav text.

README quickstart (en/ru/zh) reorganised into matching three blocks.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PHPCraftdream

README.md

@@ -36,34 +36,77 @@ source distribution and compiles it locally — you need a Rust toolchain
 
 ## Quick start
 
+### Parse — read typed fields straight off the dict
+
 ```python
 import ktav
 
-text = """
+src = """
+service: web
 port:i 8080
-
-upstreams: [
-    {
-        host: a.example
-        port:i 1080
-    }
-    {
-        host: b.example
-        port:i 1080
-    }
+ratio:f 0.75
+tls: true
+tags: [
+    prod
+    eu-west-1
 ]
+db.host: primary.internal
+db.timeout:i 30
 """
 
-cfg = ktav.loads(text)
-# {'port': 8080, 'upstreams': [
-#     {'host': 'a.example', 'port': 1080},
-#     {'host': 'b.example', 'port': 1080},
-# ]}
+cfg = ktav.loads(src)
+
+service: str = cfg["service"]
+port:    int = cfg["port"]
+ratio: float = cfg["ratio"]
+tls:    bool = cfg["tls"]
+tags: list[str] = cfg["tags"]
+db_host:    str = cfg["db"]["host"]
+db_timeout: int = cfg["db"]["timeout"]
+```
+
+### Walk — dispatch on the runtime type
 
-back = ktav.dumps(cfg)
-assert ktav.loads(back) == cfg
+```python
+for k, v in cfg.items():
+    if v is None:              kind = "null"
+    elif isinstance(v, bool):  kind = f"bool={v}"   # bool first — True is also an int!
+    elif isinstance(v, int):   kind = f"int={v}"
+    elif isinstance(v, float): kind = f"float={v}"
+    elif isinstance(v, str):   kind = f"str={v!r}"
+    elif isinstance(v, list):  kind = f"array({len(v)})"
+    elif isinstance(v, dict):  kind = f"object({len(v)})"
+    print(f"{k} -> {kind}")
 ```
 
+### Build & render — construct a document in code
+
+```python
+doc = {
+    "name": "frontend",
+    "port": 8443,
+    "tls": True,
+    "ratio": 0.95,
+    "upstreams": [
+        {"host": "a.example", "port": 1080},
+        {"host": "b.example", "port": 1080},
+    ],
+    "notes": None,
+}
+text = ktav.dumps(doc)
+# name: frontend
+# port:i 8443
+# tls: true
+# ratio:f 0.95
+# upstreams: [
+#     { host: a.example  port:i 1080 }
+#     { host: b.example  port:i 1080 }
+# ]
+# notes: null
+```
+
+A complete runnable version lives in [`examples/basic.py`](examples/basic.py).
+
 Four entry points mirror the standard library `json` module:
 
 | Function              | Purpose                                      |

README.ru.md

@@ -36,34 +36,68 @@ pip install ktav
 
 ## Быстрый старт
 
+### Парсинг — типизированно читаем поля
+
 ```python
 import ktav
 
-text = """
+src = """
+service: web
 port:i 8080
-
-upstreams: [
-    {
-        host: a.example
-        port:i 1080
-    }
-    {
-        host: b.example
-        port:i 1080
-    }
+ratio:f 0.75
+tls: true
+tags: [
+    prod
+    eu-west-1
 ]
+db.host: primary.internal
+db.timeout:i 30
 """
 
-cfg = ktav.loads(text)
-# {'port': 8080, 'upstreams': [
-#     {'host': 'a.example', 'port': 1080},
-#     {'host': 'b.example', 'port': 1080},
-# ]}
+cfg = ktav.loads(src)
+
+service: str = cfg["service"]
+port:    int = cfg["port"]
+ratio: float = cfg["ratio"]
+tls:    bool = cfg["tls"]
+tags: list[str] = cfg["tags"]
+db_host:    str = cfg["db"]["host"]
+db_timeout: int = cfg["db"]["timeout"]
+```
+
+### Обход — диспатч по runtime-типу
 
-back = ktav.dumps(cfg)
-assert ktav.loads(back) == cfg
+```python
+for k, v in cfg.items():
+    if v is None:              kind = "null"
+    elif isinstance(v, bool):  kind = f"bool={v}"   # bool первым — True это int!
+    elif isinstance(v, int):   kind = f"int={v}"
+    elif isinstance(v, float): kind = f"float={v}"
+    elif isinstance(v, str):   kind = f"str={v!r}"
+    elif isinstance(v, list):  kind = f"array({len(v)})"
+    elif isinstance(v, dict):  kind = f"object({len(v)})"
+    print(f"{k} -> {kind}")
 ```
 
+### Билд + рендер — собираем документ в коде
+
+```python
+doc = {
+    "name": "frontend",
+    "port": 8443,
+    "tls": True,
+    "ratio": 0.95,
+    "upstreams": [
+        {"host": "a.example", "port": 1080},
+        {"host": "b.example", "port": 1080},
+    ],
+    "notes": None,
+}
+text = ktav.dumps(doc)
+```
+
+Полный запускаемый пример — в [`examples/basic.py`](examples/basic.py).
+
 Четыре публичные функции — форма повторяет стандартный `json`:
 
 | Функция               | Назначение                                    |

README.zh.md

@@ -32,25 +32,68 @@ wheel 即可覆盖所有受支持的 CPython 版本。
 
 ## 快速开始
 
+### 解析 —— 直接从 dict 按类型读取字段
+
 ```python
 import ktav
 
-text = """
+src = """
+service: web
 port:i 8080
-
-upstreams: [
-    {
-        host: a.example
-        port:i 1080
-    }
+ratio:f 0.75
+tls: true
+tags: [
+    prod
+    eu-west-1
 ]
+db.host: primary.internal
+db.timeout:i 30
 """
 
-cfg = ktav.loads(text)
-back = ktav.dumps(cfg)
-assert ktav.loads(back) == cfg
+cfg = ktav.loads(src)
+
+service: str = cfg["service"]
+port:    int = cfg["port"]
+ratio: float = cfg["ratio"]
+tls:    bool = cfg["tls"]
+tags: list[str] = cfg["tags"]
+db_host:    str = cfg["db"]["host"]
+db_timeout: int = cfg["db"]["timeout"]
+```
+
+### 遍历 —— 按运行时类型分派
+
+```python
+for k, v in cfg.items():
+    if v is None:              kind = "null"
+    elif isinstance(v, bool):  kind = f"bool={v}"   # bool 先判断 —— True 也是 int!
+    elif isinstance(v, int):   kind = f"int={v}"
+    elif isinstance(v, float): kind = f"float={v}"
+    elif isinstance(v, str):   kind = f"str={v!r}"
+    elif isinstance(v, list):  kind = f"array({len(v)})"
+    elif isinstance(v, dict):  kind = f"object({len(v)})"
+    print(f"{k} -> {kind}")
+```
+
+### 构建并渲染 —— 用代码搭建文档
+
+```python
+doc = {
+    "name": "frontend",
+    "port": 8443,
+    "tls": True,
+    "ratio": 0.95,
+    "upstreams": [
+        {"host": "a.example", "port": 1080},
+        {"host": "b.example", "port": 1080},
+    ],
+    "notes": None,
+}
+text = ktav.dumps(doc)
 ```
 
+完整可运行示例:[`examples/basic.py`](examples/basic.py)。
+
 四个入口函数对应标准库 `json` 模块:
 
 - `ktav.loads(s)` — 解析 Ktav 字符串

examples/basic.py

@@ -1,52 +1,88 @@
-"""End-to-end example: parse a Ktav document, inspect, serialize back."""
+"""End-to-end demo: parse a Ktav document, pull out typed fields, walk
+the dynamic shape, then build a fresh document in Python and render it
+back to Ktav text.
+
+Run from the repo root:
+
+    pip install -e .            # or `pip install ktav`
+    python examples/basic.py
+"""
 
 import ktav
 
-SAMPLE = """
-# a small service config
+SRC = """
+service: web
 port:i 8080
-name: frontend
+ratio:f 0.75
+tls: true
+tags: [
+    prod
+    eu-west-1
+]
+db.host: primary.internal
+db.timeout:i 30
+"""
 
-upstreams: [
-    {
-        host: a.example
-        port:i 1080
-    }
-    {
-        host: b.example
-        port:i 1080
+
+def main() -> None:
+    cfg = ktav.loads(SRC)
+
+    # ── 1. Read typed fields straight off the dict. ────────────────────
+    service: str = cfg["service"]
+    port: int = cfg["port"]
+    ratio: float = cfg["ratio"]
+    tls: bool = cfg["tls"]
+    tags: list[str] = cfg["tags"]
+    db_host: str = cfg["db"]["host"]
+    db_timeout: int = cfg["db"]["timeout"]
+
+    print(f"service={service} port={port} tls={tls} ratio={ratio:.2f}")
+    print(f"tags={tags}")
+    print(f"db: {db_host} (timeout={db_timeout}s)\n")
+
+    # ── 2. Walk the document, dispatching on the runtime type. ─────────
+    print("shape:")
+    for k, v in cfg.items():
+        print(f"  {k:<12} -> {describe(v)}")
+
+    # ── 3. Build a config in code, render it as Ktav text. ─────────────
+    doc = {
+        "name": "frontend",
+        "port": 8443,
+        "tls": True,
+        "ratio": 0.95,
+        "upstreams": [
+            upstream("a.example", 1080),
+            upstream("b.example", 1080),
+            upstream("c.example", 1080),
+        ],
+        "notes": None,
     }
-]
+    rendered = ktav.dumps(doc)
+    print("\n--- rendered ---")
+    print(rendered, end="")
 
-# Regex needs the literal-string marker so `[` is not parsed as an array.
-ip_allowlist:: [::1]
 
-timeouts: {
-    connect:f 1.5
-    read:f 30.0
-}
-"""
+def describe(v: object) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):  # bool first — `True` is also an `int`!
+        return f"bool={v}"
+    if isinstance(v, int):
+        return f"int={v}"
+    if isinstance(v, float):
+        return f"float={v}"
+    if isinstance(v, str):
+        return f"str={v!r}"
+    if isinstance(v, list):
+        return f"array({len(v)})"
+    if isinstance(v, dict):
+        return f"object({len(v)})"
+    return type(v).__name__
 
 
-def main() -> None:
-    cfg = ktav.loads(SAMPLE)
-
-    print("ktav version:", ktav.__version__)
-    print("spec version:", ktav.__spec_version__)
-    print()
-    print(f"Service {cfg['name']!r} on port {cfg['port']}")
-    print(f"  upstreams: {len(cfg['upstreams'])}")
-    for u in cfg["upstreams"]:
-        print(f"    - {u['host']}:{u['port']}")
-    print(f"  allowlist: {cfg['ip_allowlist']!r}")
-    print(f"  connect timeout: {cfg['timeouts']['connect']}s")
-
-    # Round-trip.
-    back = ktav.dumps(cfg)
-    assert ktav.loads(back) == cfg
-    print()
-    print("--- re-serialised ---")
-    print(back)
+def upstream(host: str, port: int) -> dict:
+    return {"host": host, "port": port}
 
 
 if __name__ == "__main__":