README.rst

StrictYAML

StrictYAML is a type-safe YAML parser that parses a restricted subset of the YAML specificaton.

Priorities:

• Beautiful API
• Refusing to parse the ugly, hard to read and insecure features of YAML.
• Strict validation of markup and straightforward type casting.
• Clear, readable exceptions with code snippets and line numbers.
• Acting as a near-drop in replacement for pyyaml, ruamel.yaml or poyo.
• Ability to read in YAML, make changes and write it out again with comments preserved.
• Not speed, currently.

Simple example:

# All about the character
name: Ford Prefect
age: 42
possessions:
- Towel

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

Default parse result:

>>> load(yaml_snippet)
YAML(OrderedDict([('name', 'Ford Prefect'), ('age', '42'), ('possessions', ['Towel'])]))

All data is string, list or OrderedDict:

>>> load(yaml_snippet).data
OrderedDict([('name', 'Ford Prefect'), ('age', '42'), ('possessions', ['Towel'])])

Quickstart with schema:

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

schema = Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})

42 is now parsed as an integer:

>>> person = load(yaml_snippet, schema)
>>> person.data
OrderedDict([('name', 'Ford Prefect'), ('age', 42), ('possessions', ['Towel'])])

A YAMLError will be raised if there are syntactic problems, violations of your schema or use of disallowed YAML features:

# All about the character
name: Ford Prefect
age: 42

For example, a schema violation:

try:
    person = load(yaml_snippet, schema)
except YAMLError as error:
    print(error)

while parsing a mapping
  in "<unicode string>", line 1, column 1:
    # All about the character
     ^ (line: 1)
required key(s) 'possessions' not found
  in "<unicode string>", line 3, column 1:
    age: '42'
    ^ (line: 3)

If parsed correctly:

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

schema = Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})

You can modify values and write out the YAML with comments preserved:

person = load(yaml_snippet, schema)
person['age'] = 43
print(person.as_yaml())

# All about the character
name: Ford Prefect
age: 43
possessions:
- Towel

As well as look up line numbers:

>>> person = load(yaml_snippet, schema)
>>> person['possessions'][0].start_line
5

Install

$ pip install strictyaml

Why StrictYAML?

There are a number of formats and approaches that can achieve more or less the same purpose as StrictYAML. I've tried to make it the best one. Below is a series of documented justifications:

• Why not JSON for simple configuration files?
• Why not use HJSON?
• Why not use TOML?
• Why not use the YAML 2.0 standard? - we don't need a new standard!
• Why not use kwalify with standard YAML to validate my YAML?
• Why not use python's schema library for validation?
• Why not HOCON?
• Why not JSON5?
• Why not use XML for configuration or DSLs?
• Why shouldn't I just use python code for configuration?
• Why not use INI files?
• Why not use SDLang?
• Why not use JSON Schema for validation?

Using StrictYAML

• compound
• Validating optional keys in mappings (Map)
• Using a YAML object of a parsed mapping
• Sequences of unique items (UniqueSeq)
• Mappings with defined keys (Map)
• Mappings with arbitrary key names (MapPattern)
• Fixed length sequences (FixedSeq)
• Sequence/list validator (Seq)
• Mapping with defined keys and a custom key validator (Map)
• howto
• Revalidate an already validated document
• Merge YAML documents
• Parsing YAML without a schema
• Labeling exceptions
• Build a YAML document from scratch in code
• Reading in YAML, editing it and writing it back out
• Get line numbers of YAML elements
• Either/or schema validation of two equally valid different kinds of YAML
• scalar
• Validating strings with regexes (Regex)
• Integers (Int)
• Empty key validation
• Floating point numbers (Float)
• Decimal numbers (Decimal)
• Enumerated scalars (Enum)
• Parsing strings (Str)
• Boolean (Bool)
• Email and URL validators
• Datetimes (Datetime)
• Parsing comma separated items (CommaSeparated)
• restrictions
• Disallowed YAML
• Duplicate keys

Design justifications

There are some design decisions in StrictYAML which are controversial and/or not obvious. Those are documented here:

• What is wrong with explicit tags?
• What is wrong with explicit syntax typing in a readable configuration language?
• What is wrong with implicit typing?
• What is wrong with flow style YAML?
• Why does StrictYAML only parse from strings and not files?
• What is wrong with duplicate keys?
• Why does StrictYAML not parse direct representations of python objects?
• What is wrong with node anchors and references?
• Why does StrictYAML make you define a schema in python - a turing complete language?

Breaking changes

0.5: Data is now parsed by default as a YAML object instead of directly to dict/list. To get dict/list and ordinary values as before, get yaml_object.data.

Contributors

• @gvx
• @AlexandreDecan
• @lots0logs
• @tobbez