Merge pull request #7 from posit-dev/pr/core-polish

yaml12: native Yaml wrapper + tag/formatting polish

Author: t-kalinowski

README.md

@@ -21,7 +21,7 @@ YAML and parses the same way.
 The package ships prebuilt wheels for Python 3.10+ on common platforms. Install from PyPI:
 
 ```bash
-pip install yaml12
+pip install py-yaml12
 ```
 
 ## Development install

docs/index.md

@@ -14,8 +14,13 @@ For almost every use case, `yaml12` lets you work with plain builtin Python type
 
 ## Installation
 
-The project targets Python 3.10+ and builds via `maturin` (Rust
-toolchain required). From the repository root:
+Install from PyPI:
+
+```bash
+pip install py-yaml12
+```
+
+For development, install from the repository root (requires Python 3.10+ and a Rust toolchain):
 
 ```bash
 python -m venv .venv
@@ -133,7 +138,7 @@ assert parsed == {
 
 Tags, custom handlers, and non-string mapping keys work without extra
 setup when you need them. Nodes that can’t be represented as plain
-Python types are wrapped in `Yaml` (a small frozen dataclass). You’ll
+Python types are wrapped in `Yaml` (a small immutable wrapper class). You’ll
 only see `Yaml` when:
 
 - A tagged node has no matching handler; inspect `.value` and `.tag`.

docs/reference/format_yaml.md

@@ -6,6 +6,9 @@ and mapping keys; scalar core tags (`!!str`, `!!int`, `!!bool`,
 `!!float`, `!!null`, `!!seq`, `!!map`) are dropped on emit because they
 add no extra information.
 
+Mappings are emitted in insertion order (the order you inserted keys into the Python
+mapping).
+
 ## Usage
 
 ```python

docs/reference/parse_yaml.md

@@ -13,8 +13,8 @@ read_yaml(path, multi=False, handlers=None)
 
 ## Arguments
 
-- text: `str` or sequence of `str`; sequence items are joined with
-  `"\n"`. When empty, returns `None` (or `[]` when `multi=True`).
+- text: `str` or iterable of `str`; chunks are concatenated exactly as provided (no implicit
+  separators are inserted). When empty, returns `None` (or `[]` when `multi=True`).
 - path: `str`, `os.PathLike`, or readable object yielding `str` or
   UTF-8 `bytes`.
 - multi: When `True`, parse the whole stream and return a list of
@@ -31,6 +31,9 @@ handler (including informative core tags such as `!!timestamp` or
 `!!binary`) become `Yaml` objects. Unhashable mapping keys are wrapped
 in `Yaml` so they remain hashable.
 
+Mapping key order is preserved in the returned `dict` (in the same order keys appear in
+the YAML input).
+
 ## Examples
 
 ```python
@@ -60,6 +63,6 @@ lines = [
     "---",
     "# Body that is not YAML",
 ]
-parse_yaml(lines)
+parse_yaml("\n".join(lines))
 # {'title': 'Front matter only', 'params': {'answer': 42}}
 ```

docs/tags.md

@@ -12,7 +12,7 @@ always starts with `!`, and it appears before the node’s value; it is
 not part of the scalar text itself.
 
 `yaml12` preserves tags by wrapping nodes in a `Yaml` object. A `Yaml`
-is a small frozen dataclass that carries the parsed `value` (a regular
+is a small immutable wrapper class that carries the parsed `value` (a regular
 Python type) and the `tag` string. Here is an example of parsing a tagged scalar:
 
 ```python
@@ -158,7 +158,7 @@ true: true
 
 When a key can’t be represented directly as a plain Python dict key,
 `yaml12` wraps it in `Yaml`. That preserves the original key and makes
-it hashable (with equality defined by structure), so it can safely live
+it hashable (with equality defined by structure, including mapping key order), so it can safely live
 in a Python `dict`:
 
 ```python
@@ -277,7 +277,7 @@ rmd_lines = [
     "---",
     "# Body that is not YAML",
 ]
-frontmatter = parse_yaml(rmd_lines)
+frontmatter = parse_yaml("\n".join(rmd_lines))
 assert frontmatter == {"title": "Front matter only", "params": {"answer": 42}}
 ```
 
@@ -417,15 +417,17 @@ assert parse_yaml(text)["item"].tag == "tag:example.com,2024:widgets/gizmo"
 
 ### Tag URIs
 
-To bypass handle resolution, use `!<...>` with a valid URI-like string:
+To specify a verbatim tag, use `!<...>` with a valid URI-like string. For
+simple tags like `gizmo`, `yaml12` normalizes `!<gizmo>` to the local tag
+form `!gizmo`:
 
 ```python
 parsed = parse_yaml("""
 %TAG ! tag:example.com,2024:widgets/
 ---
 item: !<gizmo> foo
 """)
-assert parsed["item"].tag == "gizmo"
+assert parsed["item"].tag == "!gizmo"
 ```
 
 ### Core schema tags
@@ -472,8 +474,8 @@ def binary_handler(value):
 converted = parse_yaml(
     yaml_text,
     handlers={
-        "tag:yaml.org,2002:timestamp": ts_handler,
-        "tag:yaml.org,2002:binary": binary_handler,
+        "!!timestamp": ts_handler,
+        "!!binary": binary_handler,
     },
 )
 assert isinstance(converted[0], datetime) and isinstance(converted[2], (bytes, bytearray))

docs/usage.md

@@ -257,6 +257,8 @@ Python result (`parse_yaml()` with defaults):
   spaces.
 - All JSON is valid YAML.
 - Sequences stay Python lists; there is no vector "simplification."
+- Mapping (dict) key order is preserved on load and emit (in the order keys appear in
+  the YAML input, and in the insertion order of Python mappings you format).
 - Block scalars (`|`, `>`) always produce strings.
 - Booleans are only `true`/`false`; `null` maps to `None`.
 - Numbers can be signed, scientific, hex (`0x`), octal (`0o`), `.inf`,

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["maturin>=1.9,<2.0"]
 build-backend = "maturin"
 
 [project]
-name = "yaml12"
+name = "py-yaml12"
 description = "A modern YAML 1.2 parser and emitter for Python, written in Rust."
 readme = "README.md"
 license = { file = "LICENSE" }