strictyaml 0.11.7

Strict, typed YAML parser

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