StrictYAML

1.7.3 · active · verified Sun Mar 29

StrictYAML is a type-safe YAML parser and validator for Python, focusing on a restricted, unambiguous subset of the YAML specification. It prioritizes a clear API, strict validation, human-readable exceptions, and the ability to round-trip (read, modify, and write) YAML while preserving comments. The current version is 1.7.3, with an active but irregular release cadence of patches and minor versions.

Warnings

breaking In version 0.5, the default parse result of `load()` changed from directly returning a Python dict/list to returning a `YAML` object. To get the dict/list representation, users must now access the `.data` attribute of the returned object.
Fix: Access the `.data` attribute (e.g., `load(yaml_str, schema).data`) to retrieve the Python dict/list.
gotcha StrictYAML intentionally refuses implicit typing (e.g., '42' is a string by default). Values are only type-cast according to an explicitly provided schema (e.g., `Int()`). This prevents common YAML surprises and security issues, but means it behaves differently from other YAML parsers.
Fix: Always define a `schema` using `strictyaml` validators (e.g., `Int()`, `Float()`, `Bool()`) if you require typed data beyond strings, lists, and dicts.
gotcha StrictYAML parses only a restricted subset of the full YAML 1.2 specification. Features like duplicate keys, explicit tags, anchors/references, and flow-style YAML (embedded JSON) are intentionally disallowed or unsupported to enhance security and readability.
Fix: Adhere to the StrictYAML subset of YAML. Avoid features like `!!str` explicit tags, `&anchor` references, and compact JSON-like syntax within your YAML files.
gotcha StrictYAML, by design, only parses YAML from strings, not directly from file paths or file-like objects. This is a deliberate choice for explicitness and security.
Fix: Read the content of your YAML file into a string first, then pass that string to `strictyaml.load()`. Example: `with open('config.yaml', 'r') as f: yaml_string = f.read(); doc = load(yaml_string, schema)`.
gotcha When no schema is provided to `strictyaml.load()`, all scalar values (numbers, booleans, dates) are interpreted as strings. Automatic type inference, common in other YAML libraries, is disabled.
Fix: Provide a schema (`strictyaml.load(yaml_str, schema)`) with appropriate validators (`Str()`, `Int()`, `Bool()`, `Datetime()`, etc.) to enable type conversion.

Install

pip install strictyaml Install with pip

Imports

load
```
from strictyaml import load
```
Map
```
from strictyaml import Map
```
Str
```
from strictyaml import Str
```
Int
```
from strictyaml import Int
```
Seq
```
from strictyaml import Seq
```
YAMLError
```
from strictyaml import YAMLError
```

Quickstart

This quickstart demonstrates how to parse a YAML string using a schema for type validation and casting, access parsed data, modify values, and handle potential YAMLError exceptions. It also shows the default behavior of parsing without a schema where all scalar values are treated as strings.

from strictyaml import load, Map, Str, Int, Seq, YAMLError

yaml_snippet = """
name: Ford Prefect
age: 42
possessions:
  - Towel
  - 'No. 2 pencil'
"""

# Define a schema for validation and type casting
schema = Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})

try:
    # Load YAML with the defined schema
    document = load(yaml_snippet, schema)
    print("Parsed data:", document.data)
    print(f"Name (string): {document['name'].data}")
    print(f"Age (int): {document['age'].data}")
    print(f"First possession: {document['possessions'][0].data}")

    # Modify a value and output YAML (comments are preserved)
    document['age'] = 43
    print("\nModified YAML:\n", document.as_yaml())

except YAMLError as e:
    print(f"YAML Error: {e}")

# Example without a schema (all scalars are strings by default)
yaml_no_schema = load(yaml_snippet)
print("\nParsed without schema (age is string):", yaml_no_schema.data['age'])

view raw JSON →