Clarify Yaml-only wrapper usage and add examples.

Author: t-kalinowski

docs/api.md

@@ -1,14 +1,14 @@
 # API Reference
 
-The `yaml12` module exposes parsing/formatting helpers plus two small dataclasses. Arguments mirror the Rust bindings and stay strict so type errors surface early.
+The `yaml12` module exposes parsing/formatting helpers plus a single node wrapper `Yaml` (also exported as `Tagged` and `MappingKey` for compatibility). Use plain Python types whenever possible; reach for `Yaml` only when a node is tagged or when a collection appears as a mapping key. Arguments mirror the Rust bindings and stay strict so type errors surface early.
 
 ## parse_yaml(text, multi=False, handlers=None)
 
 - `text`: `str` or sequence of `str`; sequence items are joined with newlines.
 - `multi`: when `True`, parses the whole stream into a list (empty input yields `[]`); otherwise returns only the first document or `None` for empty input.
 - `handlers`: optional `dict[str, Callable]` mapping tag strings to callables; handlers apply to tagged values and keys and run on already-parsed Python values.
-- Returns parsed Python values. Non-core tags (and informative core tags like `!!timestamp`, `!!binary`, `!!set`, `!!omap`, `!!pairs`, or non-specific `!`) become `Tagged` when no handler matches. Scalar core tags (`!!str`, `!!int`, `!!bool`, `!!float`, `!!null`, `!!seq`, `!!map`) are normalized to plain Python types.
-- Unhashable mapping keys (sequences/mappings) are wrapped in `MappingKey` so they can be hashable.
+- Returns parsed Python values. Tagged nodes (non-core tags plus informative core tags like `!!timestamp`, `!!binary`, `!!set`, `!!omap`, `!!pairs`, or non-specific `!`) become `Yaml` objects when no handler matches; scalar core tags (`!!str`, `!!int`, `!!bool`, `!!float`, `!!null`, `!!seq`, `!!map`) are normalized to plain Python types.
+- Unhashable mapping keys (sequences/mappings, or tagged collections) become `Yaml(value, tag=None)` so they remain hashable; tagged scalar keys become `Yaml(value, tag)`.
 - Raises `ValueError` on YAML parse errors or invalid tag strings; `TypeError` on wrong argument types; handler exceptions propagate unchanged.
 
 ## read_yaml(path, multi=False, handlers=None)
@@ -19,7 +19,7 @@ The `yaml12` module exposes parsing/formatting helpers plus two small dataclasse
 
 ## format_yaml(value, multi=False)
 
-- Serializes a Python value (or list of documents when `multi=True`) into a YAML string. `Tagged` values keep their tags unless they target core scalar tags; `MappingKey` preserves complex mapping keys.
+- Serializes a Python value (or list of documents when `multi=True`) into a YAML string. `Yaml` nodes keep their tags unless they target core scalar tags; wrapping unhashable mapping keys in `Yaml` preserves them.
 - When `multi=False`, the returned string omits the leading document marker and trailing newline. When `multi=True`, the string starts with `---\n` and ends with `...\n`; an empty sequence emits `---\n...\n`.
 - Raises `TypeError` if `multi=True` and `value` is not a sequence, or when unsupported types are provided.
 
@@ -30,18 +30,36 @@ The `yaml12` module exposes parsing/formatting helpers plus two small dataclasse
 - Writers are tried with text first and retried as bytes if needed.
 - Raises `IOError` on write failures or `TypeError` when inputs are invalid.
 
-## Tagged
+## Yaml (aliases: Tagged, MappingKey)
 
 Frozen `dataclass` with fields:
 
 - `value`: the parsed Python value.
-- `tag`: the rendered tag string (for example `"!foo"` or `"tag:yaml.org,2002:timestamp"`).
+- `tag`: the rendered tag string (for example `"!foo"` or `"tag:yaml.org,2002:timestamp"`), or `None` when used solely to wrap an unhashable mapping key.
 
-Produced for non-core tags (and informative core tags such as timestamps or binary) when no handler applies. You can construct it manually when emitting YAML to preserve tags; core scalar tags are stripped during serialization because they carry no extra information.
+Produced for non-core tags (and informative core tags such as timestamps or binary) when no handler applies, and for any unhashable mapping key. You can construct it manually when emitting YAML to preserve tags or wrap complex keys; core scalar tags are stripped during serialization because they carry no extra information.
 
-## MappingKey
+### Usage examples
 
-Frozen `dataclass` that wraps unhashable mapping keys (sequences, mappings, or tagged values). Equality and hashing use a frozen structural view of `value`, and it proxies indexing/iteration/len to the wrapped object when applicable. Use it to emit or compare YAML mappings that rely on complex keys.
+```python
+from yaml12 import Yaml, format_yaml, parse_yaml
+
+# Tagged scalar
+text = format_yaml({"env": Yaml("prod", "!env")})
+assert "!env" in text
+assert isinstance(parse_yaml(text)["env"], Yaml)
+
+# Collection key
+data = {Yaml(["a", "b"]): "val"}
+out = format_yaml(data)
+assert parse_yaml(out)[Yaml(["a", "b"])] == "val"
+
+# Tagged collection key
+data = {Yaml(["a", "b"], "!pair"): "val"}
+out = format_yaml(data)
+key = next(iter(parse_yaml(out)))
+assert isinstance(key, Yaml) and key.tag == "!pair" and key.value == ["a", "b"]
+```
 
 ## _dbg_yaml(text)
 

docs/index.md

@@ -1,10 +1,10 @@
 # yaml12
 
-`yaml12` exposes the Rust-based `saphyr` YAML 1.2 parser and emitter to Python through a small, function-first API. The bindings keep conversions lean, support multi-document streams, preserve non-core tags through a lightweight `Tagged` dataclass, and round-trip complex mapping keys via `MappingKey`.
+`yaml12` exposes the Rust-based `saphyr` YAML 1.2 parser and emitter to Python through a small, function-first API. The bindings keep conversions lean, support multi-document streams, and materialize tagged nodes or unhashable mapping keys as a single lightweight `Yaml` dataclass (also exported as `Tagged` and `MappingKey`); otherwise you just use plain Python types.
 
 - Parse YAML text or files into familiar Python types with `parse_yaml` and `read_yaml`; handlers apply to both values and keys.
 - Serialize Python values back to YAML with `format_yaml` or write directly to disk/stdout with `write_yaml`, including non-core tags.
-- Round-trip unhashable mapping keys using `MappingKey` to keep tagged collections, sequences, and mappings stable; tagged scalar keys stay plain `Tagged`.
+- Round-trip tagged nodes and unhashable mapping keys using `Yaml`, keeping tagged scalars, tagged collections, and bare collections stable across parse/format.
 
 ## Installation
 

docs/tags.md

@@ -2,22 +2,22 @@
 
 YAML 1.2 allows tagging values with custom semantics. `yaml12` preserves those tags by default and lets you plug in your own coercions.
 
-## Tagged wrapper
+## Yaml wrapper
 
-Non-core tags that do not have a matching handler are wrapped in a frozen `Tagged` dataclass:
+Non-core tags that do not have a matching handler are wrapped in a frozen `Yaml` dataclass (also exported as `Tagged`):
 
 ```python
-from yaml12 import Tagged, parse_yaml
+from yaml12 import Yaml, parse_yaml
 
 color = parse_yaml("!color red")
-assert isinstance(color, Tagged)
+assert isinstance(color, Yaml)
 assert color.value == "red"
 assert color.tag == "!color"
 ```
 
-`Tagged` works for both scalar and collection nodes, including keys in mappings. You can serialize tagged values by passing a `Tagged` instance back into `format_yaml` or `write_yaml`. Non-specific tags (`!`) produce `Tagged("value", "!")` unless you supply a handler. Tagged scalar keys stay plain `Tagged`; tagged collections are wrapped in `MappingKey(Tagged(...))` so they remain hashable.
+`Yaml` works for both scalar and collection nodes, including keys in mappings. You can serialize tagged values by passing a `Yaml` instance back into `format_yaml` or `write_yaml`. Non-specific tags (`!`) produce `Yaml("value", "!")` unless you supply a handler. Tagged scalar keys become `Yaml(value, tag)`; tagged collections and untagged collections used as keys are wrapped in `Yaml(value, tag)` (with `tag=None` for untagged collections).
 
-Core scalar tags (`!!str`, `!!int`, `!!float`, `!!bool`, `!!null`, `!!seq`, `!!map`) are normalized to plain Python values instead of `Tagged`. Informative core tags (such as `!!timestamp`, `!!binary`, `!!set`, `!!omap`, or `!!pairs`) stay tagged so you can choose whether to handle them or preserve them verbatim. Invalid values for core tags raise `ValueError`.
+Core scalar tags (`!!str`, `!!int`, `!!float`, `!!bool`, `!!null`, `!!seq`, `!!map`) are normalized to plain Python values instead of `Yaml`. Informative core tags (such as `!!timestamp`, `!!binary`, `!!set`, `!!omap`, or `!!pairs`) stay tagged so you can choose whether to handle them or preserve them verbatim. Invalid values for core tags raise `ValueError`.
 
 ## Handler functions
 

docs/usage.md

@@ -1,6 +1,6 @@
 # Usage
 
-The Python surface of `yaml12` is intentionally small: four functions that parse and emit YAML plus helpers for non-core tags (`Tagged`) and complex mapping keys (`MappingKey`).
+The Python surface of `yaml12` is intentionally small: four functions that parse and emit YAML plus a single `Yaml` helper (also exported as `Tagged`/`MappingKey`) that you only need for two cases: tagged nodes and collection keys.
 
 ## Parse YAML text
 
@@ -15,7 +15,7 @@ assert config["items"] == ["rust", "python"]
 
 - Set `multi=True` to parse a stream of documents into a list; `multi=False` returns only the first document and ignores the rest of the stream.
 - Supply `handlers` (a `dict` mapping tag strings to callables) to coerce specific tags on the fly. Handlers see already-parsed Python values and run for tagged keys as well as values. See [Custom Tags](tags.md) for details.
-- Non-core tags without handlers become `Tagged`. Unhashable mapping keys (lists/dicts or tagged collections) are wrapped in `MappingKey` so they remain usable as dictionary keys; tagged scalar keys remain plain `Tagged`.
+- Non-core tags without handlers become `Yaml(tag=..., value=...)`. Unhashable mapping keys (lists/dicts or tagged collections) become `Yaml(value, tag=None)` so they remain usable as dictionary keys; tagged scalar keys become `Yaml` with the tag preserved.
 
 ## Read from files
 
@@ -32,7 +32,7 @@ File I/O errors raise `IOError`. Parse problems surface as `ValueError`. Invalid
 
 ## Emit YAML text
 
-`format_yaml(value, multi=False)` serializes a Python value (or list of documents when `multi=True`) into YAML text. Tagged values retain their tags unless they target core scalar tags like `!!int` or `!!str`. Unhashable mapping keys stay wrapped in `MappingKey`.
+`format_yaml(value, multi=False)` serializes a Python value (or list of documents when `multi=True`) into YAML text. `Yaml` values retain their tags unless they target core scalar tags like `!!int` or `!!str`. Unhashable mapping keys stay wrapped in `Yaml(value, tag=None)`.
 
 ```python
 from yaml12 import format_yaml
@@ -64,4 +64,23 @@ write_yaml(["first", "second"], path="out.yml", multi=True)
 
 ## Complex mapping keys
 
-YAML allows sequences, mappings, and tagged scalars as keys. Parsed results wrap any unhashable key (collections or tagged collections) in a `MappingKey` so it can live in a Python `dict` while preserving equality and hashing by structure. Tagged scalar keys remain plain `Tagged`. To emit an unhashable key, wrap it in `MappingKey` (for tagged collections, wrap the `Tagged` value itself) before passing it to `format_yaml` or `write_yaml`.
+YAML allows sequences, mappings, and tagged scalars as keys. Parsed results wrap any unhashable key (collections or tagged collections) in `Yaml(value, tag=None)` so it can live in a Python `dict` while preserving equality and hashing by structure. Tagged scalar keys remain tagged `Yaml` nodes. To emit an unhashable key, wrap it in `Yaml` (for tagged collections, set `Yaml(value, tag)`), then pass it to `format_yaml` or `write_yaml`.
+
+## Quick `Yaml` examples
+
+```python
+from yaml12 import Yaml, format_yaml, parse_yaml
+
+# Tagged value
+text = format_yaml({"mode": Yaml("prod", "!mode")})
+assert parse_yaml(text)["mode"].tag == "!mode"
+
+# Untagged collection key
+mapping = {Yaml(["a", "b"]): "v"}
+assert parse_yaml(format_yaml(mapping))[Yaml(["a", "b"])] == "v"
+
+# Tagged collection key
+mapping = {Yaml(["a", "b"], "!pair"): "v"}
+key = next(iter(parse_yaml(format_yaml(mapping))))
+assert key.tag == "!pair" and key.value == ["a", "b"]
+```