yamlsmith 0.1.1__tar.gz

yamlsmith-0.1.1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

yamlsmith-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: uv sync
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: uv sync
+      - name: Run mypy
+        run: uv run mypy src/ --strict

yamlsmith-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build distribution
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish

yamlsmith-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.env
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+coverage/
+htmlcov/
+.coverage

yamlsmith-0.1.1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to yamlsmith are documented here.
+
+## [Unreleased]
+
+## v0.1.1 (2026-03-15)
+
+### Fixed
+
+- **Pre-comment placement:** Pre-comments (standalone comment lines before a key) were incorrectly emitted as inline comments on the previous key line. They are now preserved on their own line above the key.
+- **Integer/float/bool round-trip quoting:** Plain scalars such as `5432` were quoted after a load→dump cycle. The constructor now stores `None` as the tag for implicitly resolved non-string types so the representer derives the correct tag from the Python type rather than a stale string tag stored in `RoundTripScalar`.
+- **Plain scalar quoting:** Unquoted scalars that resolve to non-string types no longer receive spurious quotes on re-emit.
+
+## v0.1.0 (2026-03-14)
+
+Initial release.
+
+### Added
+
+- YAML 1.2 scanner/tokenizer with comment metadata
+- Event-stream parser
+- Node graph composer with anchor/alias resolution
+- Constructor: YAML nodes → Python objects (`str`, `int`, `float`, `bool`, `None`, `datetime`, `bytes`)
+- Representer: Python objects → YAML nodes
+- Emitter with comment preservation and block/flow style support
+- Round-trip types: `RoundTripDict`, `RoundTripList`, `RoundTripScalar`
+- Public API: `YAML` class and `load` / `dump` / `load_all` / `dump_all` convenience functions
+- Error hierarchy: `YAMLError`, `ScannerError`, `ParserError`, `ComposerError`, `ConstructorError`, `EmitterError`
+- PEP 561 typed package (`py.typed` marker)
+- Python 3.10+ support
+- Zero runtime dependencies

yamlsmith-0.1.1/Makefile

@@ -0,0 +1,22 @@
+.PHONY: install build test lint fmt clean ci
+
+install:
+	uv sync
+
+build:
+	uv build
+
+test:
+	uv run pytest tests/ -v
+
+lint:
+	uv run ruff check src/
+	uv run mypy src/
+
+fmt:
+	uv run ruff format src/ tests/
+
+clean:
+	rm -rf dist/ build/ *.egg-info/ .pytest_cache/ .mypy_cache/
+
+ci: lint test

yamlsmith-0.1.1/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: yamlsmith
+Version: 0.1.1
+Summary: Round-trip YAML 1.2 library with comment preservation — a modern ruamel.yaml replacement
+Project-URL: Homepage, https://github.com/agentine/yamlsmith
+Project-URL: Repository, https://github.com/agentine/yamlsmith
+Project-URL: Issue Tracker, https://github.com/agentine/yamlsmith/issues
+Author: Agentine
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# yamlsmith
+
+[![PyPI](https://img.shields.io/pypi/v/yamlsmith)](https://pypi.org/project/yamlsmith/)
+[![Python](https://img.shields.io/pypi/pyversions/yamlsmith)](https://pypi.org/project/yamlsmith/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-strict-green)](https://mypy-lang.org/)
+
+Round-trip YAML 1.2 library with comment preservation — a modern, drop-in replacement for ruamel.yaml.
+
+Pure Python, zero dependencies, fully typed ([PEP 561](https://peps.python.org/pep-0561/)), Python 3.10+.
+
+---
+
+## Why yamlsmith?
+
+[ruamel.yaml](https://pypi.org/project/ruamel.yaml/) has 155M+ monthly downloads and is the only production-ready Python library for round-trip YAML with comment preservation. But it carries significant risk:
+
+- **Bus factor = 1.** Single maintainer with no governance structure.
+- **PEP 625 crisis.** The namespace package naming may prevent continued PyPI uploads.
+- **Hostile contribution model.** SourceForge/Mercurial hosting makes community contribution nearly impossible.
+- **Failed fork.** ruyaml (pycontribs) was created to address these risks and itself stalled.
+
+yamlsmith solves this: same round-trip semantics, modern codebase, zero dependencies, YAML 1.2 strict mode (no legacy boolean quirks from 1.1).
+
+---
+
+## Installation
+
+```bash
+pip install yamlsmith
+```
+
+---
+
+## Quick Start
+
+### Load and modify without losing comments
+
+```python
+from yamlsmith import load, dump
+
+text = """\
+# Database configuration
+host: localhost
+port: 5432  # default PostgreSQL port
+enabled: true
+"""
+
+data = load(text)
+data["port"] = 5433       # modify a value
+data["timeout"] = 30      # add a new key
+
+print(dump(data))
+```
+
+Output — comments preserved, structure intact:
+
+```yaml
+# Database configuration
+host: localhost
+port: 5433  # default PostgreSQL port
+enabled: true
+timeout: 30
+```
+
+### Multi-document streams
+
+```python
+from yamlsmith import load_all, dump_all
+
+text = """\
+# Document 1
+name: alice
+---
+# Document 2
+name: bob
+"""
+
+docs = load_all(text)
+docs[0]["name"] = "ALICE"
+print(dump_all(docs))
+```
+
+### File I/O
+
+```python
+from yamlsmith import YAML
+
+yaml = YAML()
+
+with open("config.yaml") as f:
+    data = yaml.load(f)
+
+data["version"] = "2.0"
+
+with open("config.yaml", "w") as f:
+    yaml.dump(data, f)
+```
+
+---
+
+## API Reference
+
+### Convenience functions
+
+```python
+from yamlsmith import load, dump, load_all, dump_all
+```
+
+| Function | Signature | Description |
+|---|---|---|
+| `load` | `(text: str \| bytes \| IO) → Any` | Load a single YAML document |
+| `dump` | `(data: Any, stream: IO \| None = None) → str` | Dump to YAML string (optionally also write to stream) |
+| `load_all` | `(text: str \| bytes \| IO) → list[Any]` | Load all documents from a multi-document stream |
+| `dump_all` | `(data: list[Any], stream: IO \| None = None) → str` | Dump a list of documents separated by `---` |
+
+All functions use round-trip mode: mappings and sequences are loaded as `RoundTripDict` / `RoundTripList` with comment metadata attached.
+
+---
+
+### `YAML` class
+
+```python
+from yamlsmith import YAML
+
+yaml = YAML(indent=2, default_flow_style=False)
+```
+
+**Constructor parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `indent` | `int` | `2` | Indentation width for block mappings and sequences |
+| `default_flow_style` | `bool` | `False` | Emit flow style (`{a: 1}`) instead of block style by default |
+
+**Methods:**
+
+| Method | Signature | Description |
+|---|---|---|
+| `load` | `(stream: str \| bytes \| IO) → Any` | Load a single YAML document |
+| `dump` | `(data: Any, stream: IO \| None = None) → str` | Dump to YAML string, optionally also write to stream |
+| `load_all` | `(stream: str \| bytes \| IO) → list[Any]` | Load all documents from a stream |
+| `dump_all` | `(data: list[Any], stream: IO \| None = None) → str` | Dump multiple documents with `---` separators |
+
+Streams may be `str`, `bytes`, or any file-like object with a `.read()` / `.write()` method.
+
+---
+
+### Round-trip types
+
+When you load YAML, mappings and sequences are returned as round-trip types that carry comment metadata:
+
+#### `RoundTripDict`
+
+A `dict` subclass preserving insertion order and YAML comments.
+
+```python
+from yamlsmith import RoundTripDict
+
+d = RoundTripDict({"a": 1, "b": 2})
+
+# Attach comments to a key
+d.set_comment("a", pre="# section header", inline="# inline note")
+
+# Read comments back
+pre, inline = d.get_comment("a")
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `set_comment` | `(key, *, pre=None, inline=None)` | Attach a pre-comment and/or inline comment to `key` |
+| `get_comment` | `(key) → tuple[str \| None, str \| None]` | Return `(pre_comment, inline_comment)` for `key` |
+
+#### `RoundTripList`
+
+A `list` subclass preserving YAML comments per item.
+
+```python
+from yamlsmith import RoundTripList
+
+lst = RoundTripList([1, 2, 3])
+
+# Attach a comment to item at index 0
+lst.set_item_comment(0, pre="# first item", inline="# note")
+
+pre, inline = lst.get_item_comment(0)
+```
+
+| Method | Signature | Description |
+|---|---|---|
+| `set_item_comment` | `(index, *, pre=None, inline=None)` | Attach a pre-comment and/or inline comment to item `index` |
+| `get_item_comment` | `(index) → tuple[str \| None, str \| None]` | Return `(pre_comment, inline_comment)` for item `index` |
+
+#### `RoundTripScalar`
+
+A wrapper for a scalar value that carries comment metadata and style information. Returned by the loader when a scalar has an inline comment or non-default quoting style.
+
+```python
+from yamlsmith import RoundTripScalar
+
+s = RoundTripScalar(42, inline_comment="# answer", style="plain")
+print(s.value)          # 42
+print(s == 42)          # True — compares by .value
+```
+
+| Attribute | Type | Description |
+|---|---|---|
+| `value` | `Any` | The underlying Python value |
+| `pre_comment` | `str \| None` | Comment line(s) before the scalar |
+| `inline_comment` | `str \| None` | Comment after the value on the same line |
+| `style` | `str \| None` | Scalar style: `plain`, `single`, `double`, `literal`, `folded` |
+| `tag` | `str \| None` | Explicit YAML tag, or `None` for implicit resolution |
+
+---
+
+### Error types
+
+All errors inherit from `YAMLError`.
+
+```python
+from yamlsmith import YAMLError, ScannerError, ParserError, ComposerError, ConstructorError, EmitterError
+
+try:
+    data = load("key: :")
+except YAMLError as e:
+    print(f"YAML error: {e}")
+```
+
+| Exception | Raised when |
+|---|---|
+| `YAMLError` | Base class for all yamlsmith errors |
+| `ScannerError` | Invalid character or token in the input stream |
+| `ParserError` | Structurally invalid YAML (bad nesting, missing values) |
+| `ComposerError` | Undefined alias reference (`*anchor` without `&anchor`) |
+| `ConstructorError` | Unknown YAML tag or type conversion failure |
+| `EmitterError` | Serialization failure during emit |
+
+---
+
+## Comment Preservation
+
+yamlsmith attaches comments to the nearest YAML node:
+
+| Comment type | Example | Stored on |
+|---|---|---|
+| Pre-comment | `# header` on its own line before a key | the key's node |
+| Inline comment | `value  # note` after a value | the value's node |
+| Post-comment | trailing comment after a block | the block node |
+| Document comment | comment before `---` or after `...` | the document node |
+
+Comments survive load → modify → dump cycles as long as the node they are attached to is not replaced with a plain Python object. If you replace a `RoundTripDict` with a plain `dict`, its comments are discarded.
+
+---
+
+## YAML 1.2 Strict Mode
+
+yamlsmith implements **YAML 1.2 only**. Legacy YAML 1.1 boolean strings are treated as plain strings:
+
+| Expression | ruamel.yaml (1.1) | yamlsmith (1.2) |
+|---|---|---|
+| `yes` | `True` | `"yes"` |
+| `no` | `False` | `"no"` |
+| `on` | `True` | `"on"` |
+| `off` | `False` | `"off"` |
+| `true` | `True` | `True` |
+| `false` | `False` | `False` |
+
+Only `true`/`True`/`TRUE` and `false`/`False`/`FALSE` are recognised as booleans.
+
+---
+
+## Migration from ruamel.yaml
+
+### Import changes
+
+| ruamel.yaml | yamlsmith |
+|---|---|
+| `from ruamel.yaml import YAML` | `from yamlsmith import YAML` |
+| `from ruamel.yaml.comments import CommentedMap` | `from yamlsmith import RoundTripDict` |
+| `from ruamel.yaml.comments import CommentedSeq` | `from yamlsmith import RoundTripList` |
+
+### API compatibility
+
+The core `YAML` class API is identical:
+
+```python
+# ruamel.yaml
+from ruamel.yaml import YAML
+yaml = YAML()
+data = yaml.load(stream)
+yaml.dump(data, stream)
+
+# yamlsmith — same calls
+from yamlsmith import YAML
+yaml = YAML()
+data = yaml.load(stream)
+yaml.dump(data, stream)
+```
+
+### Type name changes
+
+| ruamel.yaml | yamlsmith | Notes |
+|---|---|---|
+| `CommentedMap` | `RoundTripDict` | Same dict semantics |
+| `CommentedSeq` | `RoundTripList` | Same list semantics |
+| `CommentedSeq` | `RoundTripList` | Same list semantics |
+| `scalarstring.*` | `RoundTripScalar(style=...)` | Unified scalar wrapper |
+
+### Behaviour differences
+
+| Behaviour | ruamel.yaml | yamlsmith |
+|---|---|---|
+| YAML spec | 1.1 + 1.2 hybrid | 1.2 strict |
+| `yes`/`no`/`on`/`off` | booleans | plain strings |
+| `dump()` return value | `None` (writes to stream) | always returns `str` |
+| Initialisation | `YAML(typ="rt")` for round-trip | round-trip is the only mode |
+| Python object tags | `!!python/object` supported | not supported (safe by default) |
+
+### dump() return value
+
+ruamel.yaml's `dump()` writes to a stream and returns `None`. yamlsmith's `dump()` always returns the YAML string and optionally also writes to the stream if one is provided:
+
+```python
+# ruamel.yaml
+import io
+buf = io.StringIO()
+yaml.dump(data, buf)
+text = buf.getvalue()
+
+# yamlsmith — simpler
+text = yaml.dump(data)           # or:
+text = yaml.dump(data, stream=f) # also writes to f
+```
+
+---
+
+## Features
+
+- YAML 1.2 strict mode (no legacy 1.1 boolean quirks)
+- Round-trip comment preservation (pre, inline, post, document-level)
+- Block and flow style preservation
+- Anchor and alias support
+- Multi-document streams (`load_all` / `dump_all`)
+- Literal (`|`) and folded (`>`) block scalars
+- All standard YAML types: `str`, `int`, `float`, `bool`, `null`, `datetime`, `binary`
+- Octal (`0o777`) and hexadecimal (`0xFF`) integer literals
+- `inf`, `-inf`, `.nan` float values
+- Full type annotations, mypy `--strict` clean
+- PEP 561 typed package
+- Zero dependencies
+
+---
+
+## License
+
+[MIT](LICENSE)

yamlsmith-0.1.1/PLAN.md

@@ -0,0 +1,97 @@
+# yamlsmith — Round-Trip YAML 1.2 Library for Python
+
+## Target Library
+
+**ruamel.yaml** — the only production-ready Python library for round-trip YAML editing with comment preservation.
+
+| Metric | Value |
+|--------|-------|
+| Downloads | ~155M/month |
+| Maintainers | 1 (Anthon van der Neut) |
+| Dependent packages | 3,080 |
+| Latest release | v0.19.1 (Jan 2026) |
+| Hosting | SourceForge/Mercurial |
+| Community fork | ruyaml (stalled, no releases 12+ months) |
+
+### Why Replace
+
+- **Bus factor = 1.** Single maintainer with no governance structure.
+- **PEP 625 crisis.** Maintainer signaled potential inability to continue uploading to PyPI due to namespace package naming requirements.
+- **Hostile contribution model.** SourceForge/Mercurial hosting makes PRs/community contribution nearly impossible.
+- **Failed fork.** ruyaml (pycontribs) was created specifically to address these risks and has itself stalled.
+- **No alternative.** PyYAML does not support round-trip editing or comment preservation. There is no production-ready substitute.
+
+## Package Name
+
+**yamlsmith** — verified available on PyPI.
+
+## Scope
+
+A modern Python library for YAML 1.2 parsing and emitting with full round-trip fidelity: comments, ordering, formatting, and whitespace are preserved through load/modify/dump cycles.
+
+## Architecture
+
+### Core Components
+
+1. **Scanner/Tokenizer** — Stream-based YAML 1.2 tokenizer that captures comments and whitespace as metadata tokens.
+2. **Parser** — Produces an event stream (similar to SAX) from tokens, attaching comment metadata.
+3. **Composer** — Builds a document tree (node graph) from the event stream, with anchor/alias resolution.
+4. **Representer** — Maps Python objects to YAML nodes, preserving type information.
+5. **Constructor** — Maps YAML nodes back to Python objects.
+6. **Emitter** — Serializes the node graph back to YAML text, replaying preserved comments and formatting.
+7. **Public API** — Simple `load()`, `dump()`, `load_all()`, `dump_all()` functions plus a `YAML` class for configuration.
+
+### Key Design Decisions
+
+- **Pure Python, zero dependencies.** No C extensions, no Rust. Simple `pip install`.
+- **YAML 1.2 only.** No YAML 1.1 legacy support (boolean `yes/no/on/off` quirks).
+- **Round-trip by default.** The primary API preserves comments and formatting. Safe-load semantics by default (no arbitrary Python object construction).
+- **Type-annotated.** Full PEP 561 type stubs, mypy-clean.
+- **Python 3.10+.**
+
+### API Surface
+
+```python
+from yamlsmith import YAML
+
+yaml = YAML()
+
+# Round-trip load and dump
+data = yaml.load(text)
+yaml.dump(data, stream)
+
+# Convenience functions
+from yamlsmith import load, dump, load_all, dump_all
+
+data = load(text)           # round-trip mode
+text = dump(data)           # preserves comments
+```
+
+### Comment Preservation Strategy
+
+Comments attach to the nearest node:
+- **Pre-comments:** Lines before a mapping key or sequence item.
+- **Inline comments:** `# comment` on the same line as a value.
+- **Post-comments:** Trailing comments after a block.
+- **Document-level:** Comments before `---` or after `...`.
+
+Comments are stored as metadata on the node objects, not in a separate side-channel.
+
+## Deliverables
+
+1. Core YAML 1.2 scanner, parser, composer, emitter with comment preservation
+2. Python object construction/representation (dict, list, str, int, float, bool, None, datetime, binary)
+3. Round-trip API (`YAML` class + convenience functions)
+4. Anchor/alias support
+5. Multi-document support (`load_all` / `dump_all`)
+6. Flow style vs block style preservation
+7. Comprehensive test suite (YAML Test Suite compliance)
+8. PyPI package with PEP 561 type stubs
+9. README with migration guide from ruamel.yaml
+
+## Non-Goals (v1)
+
+- YAML 1.1 compatibility mode
+- Custom Python object serialization (no `!!python/object`)
+- C extension acceleration
+- Schema validation