yaml-reference 2.6.2__tar.gz → 2.8.0__tar.gz

{yaml_reference-2.6.2 → yaml_reference-2.8.0}/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-**yaml-reference** is a Python library that extends `ruamel.yaml` with cross-file YAML composition using custom tags (`!reference`, `!reference-all`, `!flatten`, `!merge`). It's built to be a reference implementation of the [yaml-reference-specs](https://github.com/dsillman2000/yaml-reference-specs) specification.
+**yaml-reference** is a Python library that extends `ruamel.yaml` with cross-file YAML composition using custom tags (`!reference`, `!reference-all`, `!flatten`, `!merge`, `!ignore`). It's built to be a reference implementation of the [yaml-reference-specs](https://github.com/dsillman2000/yaml-reference-specs) specification.
 
 ## Build, Test, and Lint
 
@@ -62,19 +62,21 @@ uv build
 The library is structured in two key parts:
 
 ### Core Module (`yaml_reference/__init__.py`)
-- **Reference & ReferenceAll classes**: Represent the `!reference` and `!reference-all` YAML tags as Python objects
-- **parse_yaml_with_references()**: Parses YAML, returning Reference/ReferenceAll objects without resolving them (one layer only)
-- **load_yaml_with_references()**: Fully recursively resolves all references, returning a complete Python dict
-- **Flatten & Merge classes**: Represent `!flatten` and `!merge` tag logic
-- **YAML loader setup**: Registers custom constructors with `ruamel.yaml.YAML` for each tag
+- **Reference & ReferenceAll classes**: Represent the `!reference` and `!reference-all` YAML tags as Python objects, supporting both mapping form and scalar shorthand (`!reference path/to/file.yml`, `!reference-all glob/*.yml`)
+- **Ignore, Flatten, and Merge classes**: Represent `!ignore`, `!flatten`, and `!merge` tag logic
+- **parse_yaml_with_references()**: Parses YAML and preserves composition tags as Python objects without resolving cross-file references
+- **load_yaml_with_references()**: Fully resolves references, then prunes ignored content, flattens sequences, and merges mappings to produce the final Python data structure
+- **Helper transforms**: `prune_ignores()`, `flatten_sequences()`, and `merge_mappings()` implement the post-resolution evaluation pipeline
+- **YAML loader setup**: Registers custom constructors with `ruamel.yaml.YAML` for each supported tag
 
 ### CLI Module (`yaml_reference/cli.py`)
-- Simple entry point that calls the core loading functions
+- Simple entry point that calls the core loading functions for YAML containing any supported composition tags
 - Outputs JSON to stdout (compatible with spec tests)
 - Takes optional `--allow` flag for path restrictions
 
 ### Test Structure (`tests/unit/`)
 - `test_reference.py`: Tests for `!reference` and `!reference-all` tag resolution
+- `test_ignore.py`: Tests for `!ignore` parsing and pruning behavior
 - `test_flatten.py`: Tests for `!flatten` tag behavior
 - `test_merge.py`: Tests for `!merge` tag behavior
 - `conftest.py`: Pytest fixtures and test utilities
@@ -83,33 +85,40 @@ The library is structured in two key parts:
 
 ### Security-First Path Handling
 1. **Relative paths only**: All references must use relative paths (e.g., `path: "config/db.yaml"`). Absolute paths raise `ValueError`.
-2. **Path restriction by default**: References can only access files in the same directory or subdirectories (no `..` to escape). Use `allow_paths` parameter to explicitly allow other directory trees.
+2. **Path restriction by default**: The referencing file's parent directory is always allowed. Use `allow_paths` to explicitly allow additional directory trees.
 3. **Security invariant**: Disallowed files are **never opened or read into memory**. Path filtering happens before file I/O.
-4. **Silent omission (for `!reference-all`)**: When a glob pattern matches files outside allowed paths, those files are silently dropped from results and the function returns `rc=0` (not an error).
+4. **Silent omission (for `!reference-all`)**: When a glob pattern matches files outside allowed paths, those files are silently dropped from results. Empty or fully filtered globs resolve to `[]` rather than an error.
 
 ### YAML Tag Implementation Pattern
 Each custom tag follows this pattern:
 1. Define a class with `yaml_tag` attribute
-2. Implement `@classmethod from_yaml(cls, constructor, node)` to parse from YAML
+2. Implement `@classmethod from_yaml(cls, constructor, node)` to parse from YAML, handling scalar, mapping, or sequence nodes as needed
 3. Register constructor with the YAML loader in `__init__.py`
 4. The class instance persists through `parse_yaml_with_references()`, allowing layer-by-layer resolution
 
+### Reference Tag Forms
+1. **Scalar shorthand is supported**: `!reference path/to/file.yml` and `!reference-all glob/*.yml` are valid when only `path` or `glob` is needed.
+2. **Mapping form is still required for optional fields**: Use mappings such as `{ path: "file.yml", anchor: "section" }` when specifying `anchor`.
+
 ### Reference Resolution Order
-1. **Circular reference detection** occurs during recursive resolution by tracking a "resolution stack"
+1. **Circular reference detection** occurs during recursive resolution by tracking visited file paths
 2. **Anchors** (optional parameter): If specified, extract only the anchored section from the referenced file
-3. **Recursive expansion**: `load_yaml_with_references()` recursively expands all tags, applying `!flatten` and `!merge` logic as it encounters them
+3. **Recursive expansion**: `load_yaml_with_references()` recursively resolves `!reference` and `!reference-all` first
+4. **Ignore pruning**: `!ignore` content is removed after full reference resolution so ignored values from referenced files can remove their parent keys or list items
+5. **Post-processing**: `!flatten` is evaluated after ignore pruning, and `!merge` is evaluated last
 
 ### Error Handling
-- **ValueError** for spec violations: absolute paths, circular references, invalid anchors
+- **ValueError** for spec violations: absolute paths, circular references, invalid anchors, malformed merge contents
 - **FileNotFoundError** for missing referenced files
-- **Glob errors**: Return empty list `[]` if glob matches no files (silent omission)
+- **PermissionError** for disallowed `!reference` targets
+- **Glob behavior**: `!reference-all` returns `[]` when a glob matches no files or when all matches are filtered out by path restrictions
 
 ### Spec Compliance Testing
 The project tests against `yaml-reference-specs`, a Go-based reference implementation. The spec tests verify:
-- Correct expansion of all four tags
+- Correct expansion of all supported tags
 - Proper error detection (bad paths, missing files, circular refs)
 - Path restriction enforcement
-- Edge cases like empty globs and nested composition
+- Edge cases like empty globs, ignored content, shorthand reference syntax, and nested composition
 
 Run with: `make spec-test` or `scripts/spec-test.sh`
 
@@ -127,15 +136,15 @@ Install hooks with: `pre-commit install`
 ### Adding a new tag type
 1. Create a class in `yaml_reference/__init__.py` with `yaml_tag` attribute and `from_yaml()` classmethod
 2. Register the constructor after the class definition
-3. Add resolution logic (handle in recursive expansion)
+3. Add resolution or post-processing logic in the appropriate stage (`_recursively_resolve_references()`, `prune_ignores()`, `flatten_sequences()`, or `merge_mappings()`)
 4. Write tests in `tests/unit/test_*.py` following existing patterns
 5. Update README.md with usage example
 
 ### Debugging a reference resolution issue
-1. Use `parse_yaml_with_references()` to see raw Reference objects before resolution
-2. Add print statements or use a debugger to trace the `_resolve_references()` recursive calls
-3. Check the resolution stack to verify circular reference detection is working
-4. Run a specific test with `-v` flag to see detailed assertion output
+1. Use `parse_yaml_with_references()` to inspect raw `Reference`, `ReferenceAll`, `Ignore`, `Flatten`, and `Merge` objects before evaluation
+2. Trace `_recursively_resolve_references()` to debug cross-file expansion and circular reference handling
+3. Check the post-processing stages in order: `prune_ignores()`, then `flatten_sequences()`, then `merge_mappings()`
+4. Run the most specific unit test with `-v` flag to see detailed assertion output
 
 ### Updating error messages
 Ensure error messages follow this pattern: include the problematic value, the path of the file where the error occurred, and the specific constraint violated. This helps spec tests verify proper error handling.

yaml_reference-2.8.0/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "yaml.customTags": [
+        "!reference mapping",
+        "!reference scalar",
+        "!reference-all mapping",
+        "!reference-all scalar",
+        "!flatten sequence",
+        "!merge sequence",
+        "!ignore scalar",
+        "!ignore mapping",
+        "!ignore sequence"
+    ]
+}

{yaml_reference-2.6.2 → yaml_reference-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yaml-reference
-Version: 2.6.2
+Version: 2.8.0
 Summary: Extension package built on top of  `ruamel.yaml` to support cross-file references in YAML files using tags `!reference` and `!reference-all`.
 Project-URL: Repository, https://github.com/dsillman2000/yaml-reference.git
 Author-email: David Sillman <dsillman2000@gmail.com>
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
 
 # yaml-reference
 
-Using `ruamel.yaml`, support cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, and `!merge`.
+Using `ruamel.yaml`, yaml-reference supports cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore`.
 
 Install the package from PyPI with:
 
@@ -40,9 +40,9 @@ uv add yaml-reference
 ```
 
 ## Spec
-![Spec Status](https://img.shields.io/badge/spec%20v0.2.6--4-passing-brightgreen?link=https%3A%2F%2Fgithub.com%2Fdsillman2000%2Fyaml-reference-specs%2Ftree%2Fv0.2.6-4)
+![Spec Status](https://img.shields.io/badge/spec%20v0.2.9--0-passing-brightgreen?link=https%3A%2F%2Fgithub.com%2Fdsillman2000%2Fyaml-reference-specs%2Ftree%2Fv0.2.9-0)
 
-This Python library implements the YAML specification for cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, and `!merge` as defined in the [yaml-reference-specs project](https://github.com/dsillman2000/yaml-reference-specs).
+This Python library implements the YAML specification for cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore` as defined in the [yaml-reference-specs project](https://github.com/dsillman2000/yaml-reference-specs).
 
 ## Example
 
@@ -50,15 +50,13 @@ This Python library implements the YAML specification for cross-file references
 # root.yaml
 version: "3.1"
 services:
-  - !reference
-    path: "services/website.yaml"
+  - !reference "services/website.yaml"
 
   - !reference
     path: "services/database.yaml"
 
 networkConfigs:
-  !reference-all
-  glob: "networks/*.yaml"
+  !reference-all "networks/*.yaml"
 
 tags: !flatten
   - !reference { path: "common/tags.yaml" }
@@ -69,6 +67,14 @@ config: !merge
   - !reference { path: "config/defaults.yaml" }
   - !reference { path: "config/overrides.yaml" }
 
+.anchors: !ignore
+  commonTags: &commonTags
+    - common:http
+    - common:security
+  dbDefaults: &dbDefaults
+    host: localhost
+    port: 5432
+
 ```
 
 Supposing there are `services/website.yaml` and `services/database.yaml` files in the same directory as `root.yaml`, and a `networks` directory with YAML files, the above will be expanded to account for the referenced files with the following Python code:
@@ -99,6 +105,57 @@ print(data["networkConfigs"])
 data = parse_yaml_with_references("root.yaml", allow_paths=["/allowed/path"])
 ```
 
+For `!reference` and `!reference-all`, both mapping and scalar shorthand forms are supported. These are equivalent:
+
+```yaml
+# Scalar shorthand
+service: !reference "services/api.yaml"
+
+# Mapping form
+service: !reference { path: "services/api.yaml" }
+
+# Scalar shorthand
+networks: !reference-all "networks/*.yaml"
+
+# Mapping form
+networks: !reference-all { glob: "networks/*.yaml" }
+```
+
+Use the mapping form when you need optional arguments such as `anchor`; use the scalar shorthand when you only need `path` or `glob`.
+
+### Multi-Document YAML
+
+yaml-reference distinguishes between a single YAML document whose root value is a sequence and a YAML file that contains multiple documents separated by `---`.
+
+- `!reference` requires the target file to contain exactly one YAML document. If the referenced file contains multiple documents, loading fails with a `ValueError`.
+- `!reference-all` expands matched files document-by-document. A single-document file contributes one list element, while a multi-document file contributes one element per document in document order.
+- When `anchor` is used with `!reference-all`, the anchored value is extracted from every document in each matched file, preserving file order and then document order.
+- If the root input file contains multiple documents, `load_yaml_with_references()` returns a Python list with one resolved output element per document. Root documents tagged with `!ignore` are omitted entirely.
+
+### The `!ignore` Tag
+
+The `!ignore` tag marks YAML content that should be parsed but omitted from the final resolved output. The most common use case is a hidden section of reusable anchors that should remain available for aliases elsewhere in the document without being emitted in the resolved result.
+
+```yaml
+.anchors: !ignore
+  commonLabels: &commonLabels
+    app: payments
+    team: platform
+  defaultResources: &defaultResources
+    requests:
+      cpu: "100m"
+      memory: "128Mi"
+
+service:
+  metadata:
+    labels: *commonLabels
+  resources: *defaultResources
+```
+
+When loaded with `load_yaml_with_references`, the `.anchors` key is removed entirely, but the anchors it defined remain usable by aliases elsewhere in the document.
+
+Ignored items are also pruned before `!flatten` and `!merge` are evaluated, so an ignored sequence entry inside either tag is simply omitted from the flattened or merged result.
+
 ### The `!merge` Tag
 
 The `!merge` tag combines multiple YAML mappings (dictionaries) into a single mapping. This is useful for composing configuration from multiple sources or applying overrides. When you use `!merge`, you provide a sequence of mappings that will be merged together, with later mappings overriding keys from earlier ones.
@@ -177,20 +234,25 @@ Note that the `app_name` and `cache_settings` fields from `config.yaml` are not
 
 ### VSCode squigglies
 
-To get rid of red squigglies in VSCode when using the `!reference`, `!reference-all`, `!flatten`, and `!merge` tags, you can add the following to your `settings.json` file:
+To get rid of red squigglies in VSCode when using the `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore` tags, you can add the following to your `settings.json` file:
 
 ```json
     "yaml.customTags": [
+        "!reference scalar",
         "!reference mapping",
+        "!reference-all scalar",
         "!reference-all mapping",
         "!flatten sequence",
-        "!merge sequence"
+        "!merge sequence",
+        "!ignore scalar",
+        "!ignore sequence",
+        "!ignore mapping"
     ]
 ```
 
 ## CLI interface
 
-There is a CLI interface for this package which can be used to read a YAML file which contains `!reference` tags and dump its contents as pretty-printed JSON with references expanded. This is useful for generating a single file for deployment or other purposes. Note that the keys of mappings will be sorted alphabetically. This CLI interface is used to test the contract of this package against the `yaml-reference-specs` project.
+There is a CLI interface for this package which can be used to read a YAML file which contains composition tags such as `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore`, and dump its contents as pretty-printed JSON with references expanded and ignored content removed. This is useful for generating a single file for deployment or other purposes. Note that the keys of mappings will be sorted alphabetically. This CLI interface is used to test the contract of this package against the `yaml-reference-specs` project.
 
 ```bash
 $ yaml-reference-cli -h

{yaml_reference-2.6.2 → yaml_reference-2.8.0}/README.md

@@ -1,6 +1,6 @@
 # yaml-reference
 
-Using `ruamel.yaml`, support cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, and `!merge`.
+Using `ruamel.yaml`, yaml-reference supports cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore`.
 
 Install the package from PyPI with:
 
@@ -14,9 +14,9 @@ uv add yaml-reference
 ```
 
 ## Spec
-![Spec Status](https://img.shields.io/badge/spec%20v0.2.6--4-passing-brightgreen?link=https%3A%2F%2Fgithub.com%2Fdsillman2000%2Fyaml-reference-specs%2Ftree%2Fv0.2.6-4)
+![Spec Status](https://img.shields.io/badge/spec%20v0.2.9--0-passing-brightgreen?link=https%3A%2F%2Fgithub.com%2Fdsillman2000%2Fyaml-reference-specs%2Ftree%2Fv0.2.9-0)
 
-This Python library implements the YAML specification for cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, and `!merge` as defined in the [yaml-reference-specs project](https://github.com/dsillman2000/yaml-reference-specs).
+This Python library implements the YAML specification for cross-file references and YAML composition in YAML files using tags `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore` as defined in the [yaml-reference-specs project](https://github.com/dsillman2000/yaml-reference-specs).
 
 ## Example
 
@@ -24,15 +24,13 @@ This Python library implements the YAML specification for cross-file references
 # root.yaml
 version: "3.1"
 services:
-  - !reference
-    path: "services/website.yaml"
+  - !reference "services/website.yaml"
 
   - !reference
     path: "services/database.yaml"
 
 networkConfigs:
-  !reference-all
-  glob: "networks/*.yaml"
+  !reference-all "networks/*.yaml"
 
 tags: !flatten
   - !reference { path: "common/tags.yaml" }
@@ -43,6 +41,14 @@ config: !merge
   - !reference { path: "config/defaults.yaml" }
   - !reference { path: "config/overrides.yaml" }
 
+.anchors: !ignore
+  commonTags: &commonTags
+    - common:http
+    - common:security
+  dbDefaults: &dbDefaults
+    host: localhost
+    port: 5432
+
 ```
 
 Supposing there are `services/website.yaml` and `services/database.yaml` files in the same directory as `root.yaml`, and a `networks` directory with YAML files, the above will be expanded to account for the referenced files with the following Python code:
@@ -73,6 +79,57 @@ print(data["networkConfigs"])
 data = parse_yaml_with_references("root.yaml", allow_paths=["/allowed/path"])
 ```
 
+For `!reference` and `!reference-all`, both mapping and scalar shorthand forms are supported. These are equivalent:
+
+```yaml
+# Scalar shorthand
+service: !reference "services/api.yaml"
+
+# Mapping form
+service: !reference { path: "services/api.yaml" }
+
+# Scalar shorthand
+networks: !reference-all "networks/*.yaml"
+
+# Mapping form
+networks: !reference-all { glob: "networks/*.yaml" }
+```
+
+Use the mapping form when you need optional arguments such as `anchor`; use the scalar shorthand when you only need `path` or `glob`.
+
+### Multi-Document YAML
+
+yaml-reference distinguishes between a single YAML document whose root value is a sequence and a YAML file that contains multiple documents separated by `---`.
+
+- `!reference` requires the target file to contain exactly one YAML document. If the referenced file contains multiple documents, loading fails with a `ValueError`.
+- `!reference-all` expands matched files document-by-document. A single-document file contributes one list element, while a multi-document file contributes one element per document in document order.
+- When `anchor` is used with `!reference-all`, the anchored value is extracted from every document in each matched file, preserving file order and then document order.
+- If the root input file contains multiple documents, `load_yaml_with_references()` returns a Python list with one resolved output element per document. Root documents tagged with `!ignore` are omitted entirely.
+
+### The `!ignore` Tag
+
+The `!ignore` tag marks YAML content that should be parsed but omitted from the final resolved output. The most common use case is a hidden section of reusable anchors that should remain available for aliases elsewhere in the document without being emitted in the resolved result.
+
+```yaml
+.anchors: !ignore
+  commonLabels: &commonLabels
+    app: payments
+    team: platform
+  defaultResources: &defaultResources
+    requests:
+      cpu: "100m"
+      memory: "128Mi"
+
+service:
+  metadata:
+    labels: *commonLabels
+  resources: *defaultResources
+```
+
+When loaded with `load_yaml_with_references`, the `.anchors` key is removed entirely, but the anchors it defined remain usable by aliases elsewhere in the document.
+
+Ignored items are also pruned before `!flatten` and `!merge` are evaluated, so an ignored sequence entry inside either tag is simply omitted from the flattened or merged result.
+
 ### The `!merge` Tag
 
 The `!merge` tag combines multiple YAML mappings (dictionaries) into a single mapping. This is useful for composing configuration from multiple sources or applying overrides. When you use `!merge`, you provide a sequence of mappings that will be merged together, with later mappings overriding keys from earlier ones.
@@ -151,20 +208,25 @@ Note that the `app_name` and `cache_settings` fields from `config.yaml` are not
 
 ### VSCode squigglies
 
-To get rid of red squigglies in VSCode when using the `!reference`, `!reference-all`, `!flatten`, and `!merge` tags, you can add the following to your `settings.json` file:
+To get rid of red squigglies in VSCode when using the `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore` tags, you can add the following to your `settings.json` file:
 
 ```json
     "yaml.customTags": [
+        "!reference scalar",
         "!reference mapping",
+        "!reference-all scalar",
         "!reference-all mapping",
         "!flatten sequence",
-        "!merge sequence"
+        "!merge sequence",
+        "!ignore scalar",
+        "!ignore sequence",
+        "!ignore mapping"
     ]
 ```
 
 ## CLI interface
 
-There is a CLI interface for this package which can be used to read a YAML file which contains `!reference` tags and dump its contents as pretty-printed JSON with references expanded. This is useful for generating a single file for deployment or other purposes. Note that the keys of mappings will be sorted alphabetically. This CLI interface is used to test the contract of this package against the `yaml-reference-specs` project.
+There is a CLI interface for this package which can be used to read a YAML file which contains composition tags such as `!reference`, `!reference-all`, `!flatten`, `!merge`, and `!ignore`, and dump its contents as pretty-printed JSON with references expanded and ignored content removed. This is useful for generating a single file for deployment or other purposes. Note that the keys of mappings will be sorted alphabetically. This CLI interface is used to test the contract of this package against the `yaml-reference-specs` project.
 
 ```bash
 $ yaml-reference-cli -h

{yaml_reference-2.6.2 → yaml_reference-2.8.0}/tests/unit/test_flatten.py

@@ -130,6 +130,21 @@ data: !flatten
     assert data["data"] == [1, 2, 3, 4, 5, 6]
 
 
+def test_flatten_combined_with_multi_document_reference_all(stage_files):
+    files = {
+        "main.yml": """
+data: !flatten
+    - !reference-all { glob: ./entries.yml }
+""",
+        "entries.yml": "---\n- [1, 2]\n---\n- [3, 4]\n",
+    }
+    stg = stage_files(files)
+
+    data = load_yaml_with_references(stg / "main.yml")
+
+    assert data["data"] == [1, 2, 3, 4]
+
+
 def test_parse_flatten_tag(stage_files):
     """Test that !flatten tags are parsed correctly without resolution."""
     files = {
@@ -197,6 +212,21 @@ def test_flatten_with_scalars(stage_files):
     assert data["data"] == [1, 2, 3, 4, 5, 6, 7]
 
 
+def test_flatten_ignores_ignored_sequence_items(stage_files):
+    """Test that !ignore items inside a !flatten sequence are omitted from the flattened result."""
+    files = {
+        "test.yml": """
+data: !flatten
+  - [1, 2]
+  - !ignore [99, 100]
+  - [3, 4]
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data["data"] == [1, 2, 3, 4]
+
+
 def test_flatten_mixed_objects_references(stage_files):
     """Test flattening a sequence of objects, references, and reference-all tags."""
     files = {

yaml_reference-2.8.0/tests/unit/test_ignore.py

@@ -0,0 +1,184 @@
+from yaml_reference import (
+    Ignore,
+    load_yaml_with_references,
+    parse_yaml_with_references,
+    prune_ignores,
+)
+
+
+def test_ignore_parse_produces_ignore_object(stage_files):
+    """Test that !ignore tags are parsed into Ignore objects by parse_yaml_with_references."""
+    files = {
+        "test.yml": "key: !ignore some_value",
+    }
+    stg = stage_files(files)
+    data = parse_yaml_with_references(stg / "test.yml")
+    assert isinstance(data["key"], Ignore)
+
+
+def test_ignore_dict_value_removed(stage_files):
+    """Test that a dict value tagged with !ignore is removed from the output."""
+    files = {
+        "test.yml": """\
+keep: hello
+drop: !ignore world
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert "keep" in data
+    assert data["keep"] == "hello"
+    assert "drop" not in data
+
+
+def test_ignore_list_item_removed(stage_files):
+    """Test that a list item tagged with !ignore is removed from the output."""
+    files = {
+        "test.yml": """\
+items:
+  - one
+  - !ignore two
+  - three
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data["items"] == ["one", "three"]
+
+
+def test_ignore_standalone_value_becomes_none(stage_files):
+    """Test that a standalone (non-list, non-dict) !ignore value is replaced with None."""
+    files = {
+        "test.yml": "!ignore standalone",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data is None
+
+
+def test_ignore_multiple_items_in_list(stage_files):
+    """Test that multiple !ignore items in a list are all removed."""
+    files = {
+        "test.yml": """\
+items:
+  - !ignore a
+  - b
+  - !ignore c
+  - d
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data["items"] == ["b", "d"]
+
+
+def test_ignore_multiple_keys_in_dict(stage_files):
+    """Test that multiple !ignore values in a dict are all removed."""
+    files = {
+        "test.yml": """\
+a: !ignore 1
+b: 2
+c: !ignore 3
+d: 4
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data == {"b": 2, "d": 4}
+
+
+def test_ignore_mapping_value(stage_files):
+    """Test that a mapping tagged with !ignore is removed."""
+    files = {
+        "test.yml": """\
+keep:
+  x: 1
+drop: !ignore
+  y: 2
+  z: 3
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert "keep" in data
+    assert "drop" not in data
+
+
+def test_ignore_sequence_value(stage_files):
+    """Test that a sequence tagged with !ignore is removed when used as a dict value."""
+    files = {
+        "test.yml": """\
+keep: [1, 2]
+drop: !ignore [3, 4]
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data == {"keep": [1, 2]}
+
+
+def test_ignore_does_not_affect_non_tagged_content(stage_files):
+    """Test that !ignore only affects tagged content and leaves everything else intact."""
+    files = {
+        "test.yml": """\
+name: yaml-reference
+version: 1.0
+description: !ignore internal note
+tags:
+  - alpha
+  - !ignore beta
+  - gamma
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert data["name"] == "yaml-reference"
+    assert data["version"] == 1.0
+    assert "description" not in data
+    assert data["tags"] == ["alpha", "gamma"]
+
+
+def test_ignore_in_referenced_file(stage_files):
+    """Test that !ignore tags in a referenced file are pruned during resolution."""
+    files = {
+        "root.yml": "contents: !reference { path: ./inner.yml }",
+        "inner.yml": """\
+public: visible
+private: !ignore hidden
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "root.yml")
+    assert data["contents"] == {"public": "visible"}
+    assert "private" not in data["contents"]
+
+
+def test_prune_ignores_standalone(stage_files):
+    """Test prune_ignores() directly on a structure containing Ignore objects."""
+    data = {
+        "a": Ignore("should be removed"),
+        "b": 42,
+        "c": [1, Ignore("also removed"), 3],
+    }
+    result = prune_ignores(data)
+    assert "a" not in result
+    assert result["b"] == 42
+    assert result["c"] == [1, 3]
+
+
+def test_ignore_preserves_none_values(stage_files):
+    """Test that existing null/None values in YAML are preserved (not confused with ignored values)."""
+    files = {
+        "test.yml": """\
+present: ~
+also_present: null
+dropped: !ignore something
+""",
+    }
+    stg = stage_files(files)
+    data = load_yaml_with_references(stg / "test.yml")
+    assert "present" in data
+    assert data["present"] is None
+    assert "also_present" in data
+    assert data["also_present"] is None
+    assert "dropped" not in data