vitenfsimpji/strictyaml

Type-safe YAML parser and validator.

StrictYAML

StrictYAML is a type-safe YAML parser that parses and validates a restricted subset of the YAML specification.

Priorities:

• Beautiful API
• Refusing to parse the ugly, hard to read and insecure features of YAML like the Norway problem.
• 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({'name': 'Ford Prefect', 'age': '42', 'possessions': ['Towel']})

All data is string, list or OrderedDict:

>>> load(yaml_snippet).data
{'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
{'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, as_document

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

And construct YAML documents from dicts or lists:

print(as_document({"x": 1}).as_yaml())

x: 1

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 avoid using environment variables as configuration?
• Why not use HJSON?
• Why not HOCON?
• Why not use INI files?
• Why not use JSON Schema for validation?
• Why not JSON for simple configuration files?
• Why not JSON5?
• Why not use the YAML 1.2 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 (or similar) for validation?
• Why not use SDLang?
• What is wrong with TOML?
• Why shouldn't I just use Python code for configuration?
• Why not use XML for configuration or DSLs?

Using StrictYAML

How to:

• Build a YAML document from scratch in code
• Either/or schema validation of different, equally valid different kinds of YAML
• Labeling exceptions
• Merge YAML documents
• Revalidate an already validated document
• Reading in YAML, editing it and writing it back out
• Get line numbers of YAML elements
• Parsing YAML without a schema

Compound validators:

• Fixed length sequences (FixedSeq)
• Mappings combining defined and undefined keys (MapCombined)
• Mappings with arbitrary key names (MapPattern)
• Mapping with defined keys and a custom key validator (Map)
• Using a YAML object of a parsed mapping
• Mappings with defined keys (Map)
• Optional keys with defaults (Map/Optional)
• Validating optional keys in mappings (Map)
• Sequences of unique items (UniqueSeq)
• Sequence/list validator (Seq)
• Updating document with a schema

Scalar validators:

• Boolean (Bool)
• Parsing comma separated items (CommaSeparated)
• Datetimes (Datetime)
• Decimal numbers (Decimal)
• Email and URL validators
• Empty key validation
• Enumerated scalars (Enum)
• Floating point numbers (Float)
• Hexadecimal Integers (HexInt)
• Integers (Int)
• Validating strings with regexes (Regex)
• Parsing strings (Str)

Restrictions:

• Disallowed YAML
• Duplicate keys
• Dirty load

Design justifications

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

• What is wrong with duplicate keys?
• What is wrong with explicit tags?
• What is wrong with flow-style YAML?
• The Norway Problem - why StrictYAML refuses to do implicit typing and so should you
• What is wrong with node anchors and references?
• Why does StrictYAML not parse direct representations of Python objects?
• Why does StrictYAML only parse from strings and not files?
• Why is parsing speed not a high priority for StrictYAML?
• What is syntax typing?
• Why does StrictYAML make you define a schema in Python - a Turing-complete language?

Star Contributors

• @wwoods
• @chrisburr
• @jnichols0

Other Contributors

• @eulores
• @WaltWoods
• @ChristopherGS
• @gvx
• @AlexandreDecan
• @lots0logs
• @tobbez
• @jaredsampson
• @BoboTIG

StrictYAML also includes code from ruamel.yaml, Copyright Anthon van der Neut.

Contributing

• Before writing any code, please read the tutorial on contributing to hitchdev libraries.
• Before writing any code, if you're proposing a new feature, please raise it on github. If it's an existing feature / bug, please comment and briefly describe how you're going to implement it.
• All code needs to come accompanied with a story that exercises it or a modification to an existing story. This is used both to test the code and build the documentation.