Skip to main content

StrictYAML

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

Priorities:

  • Readability of YAML.

  • Ease of use of API.

  • Secure by default.

  • Strict validation of markup and straightforward type casting.

  • Clear, human readable exceptions with line numbers.

  • Acting as a drop in replacement for pyyaml, ruamel.yaml or poyo.

  • Roundtripping.

  • Letting you worry about more interesting things than parsing config files.

Simple example:

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

Default parse result:

>>> strictyaml.load(yaml)
YAML({'possessions': ['Towel'], 'age': '42', 'name': 'Ford Prefect'})

>>> strictyaml.load(yaml).data
{"name": "Ford Prefect", "age": "42", "possessions": ["Towel", ]}   # All data is str, list or dict

Using a schema:

>>> from strictyaml import load, Map, Str, Int, Seq
>>> person = load(yaml, Map({"name": Str(), "age": Int(), "possessions": Seq(Str())})) \
>>> person.data == {"name": "Ford Prefect", "age": 42, "possessions": ["Towel", ]}     # 42 is now an int

Once parsed you can change values and roundtrip the whole YAML, with comments preserved:

>>> 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['possessions'][0].start_line
5

Install It

$ pip install strictyaml

FAQ

From learning programmers:

If you’re looking at this and thinking “why not do/use X instead?” that’s a healthy response, and you deserve answers. These are probably the questions you’re asking:

Map Patterns

If you’re not sure what the key name is going to be in a map but you know what type the keys and values will be, use “MapPattern”.

emails:
  arthur: arthur@earth.gov
  zaphod: zaphod@beeblebrox.com
  ford: ford@megadodo-publications.com
>>> from strictyaml import load, Map, MapPattern, Str
>>> load(yaml, Map({"emails": MapPattern({Str(), Str()})}) \
  == {"emails": {"arthur": "arthur@earth.gov", "zaphod": "zaphod@beeblebrox.com", "ford": "ford@megadodo-publications.com"}}

Optional values

If you want to use a mapping with a number of required keys and a number of optional keys use “Optional”:

arthur:
  email: arthur@earth.gov
zaphod:
  email: zaphod@beeblebrox.com
  job: President of the Galaxy
ford:
  email: ford@ursa-minor.com
  job: Freelance "journalist"

This would be parsed like so:

>>> from strictyaml import load, MapPattern, Map, Str, Optional
>>> load(yaml, MapPattern(Str(), Map({"email": Str(), Optional("job"): Str()}))) \
  == {
         "arthur": {'email': 'arthur@earth.gov',},
         "zaphod": {'email': 'zaphod@beeblebrox.com', 'job': 'President of the Galaxy'},
         "ford": {'email': 'ford@ursa-minor.com', 'job': 'Freelance "journalist"'},
     }

Either/Or

If, for example, you want to parse something as a list of strings or an individual string, you can use a pipe operator to distinguish between them - like so: |

zaphod:
  email: zaphod@beeblebrox.com
  victims: Good taste
ford:
  email: ford@ursa-minor.com
  victims: Journalistic integrity
arthur:
  email: arthur@earth.gov
  victims:
    - A bowl of petunias
    - Agrajag
    - A sperm whale

This would be parsed like so:

>>> from strictyaml import load, Seq, Map, Str, Optional
>>> load(yaml, MapPattern(Str(), Map({"email": Str(), "victims": Str() | Seq(Str())}))) \
  == {
         "zaphod": {'email': 'zaphod@beeblebrox.com', 'victims': 'President of the Galaxy'},
         "arthur": {'email': 'arthur@earth.gov', 'victims': 'Journalistic integrity'},
         "ford": {'email': 'ford@ursa-minor.com', 'victims': ['A bowl of petunias', 'Agrajag', 'A sperm whale', ]},
     }

Numbers

StrictYAML will parse a string into integers, floating point or decimal (non-floating point) numbers if you specify it:

>>> import from strictyaml import load, Map
>>> load("int: 42", Map({"int": strictyaml.Int()})) == {"int": 42}
>>> load("float: 42.3333", Map({"float": strictyaml.Float()})) == {"float": 42.3333}
>>> load("price: 35.42811", Map({"price": strictyaml.Decimal()})) == {"price": decimal.Decimal('35.42811')}

Booleans

Upper case or lower case - it doesn’t matter. Yes, on and true are treated as True and no, off and false are treated as False.

>>> load("booltrue: yes", Map({"booltrue": strictyaml.Bool()})) == {"booltrue": True}
>>> load("boolfalse: no", Map({"boolfalse": strictyaml.Bool()})) == {"booltrue": True}
>>> load("booltrue: true", Map({"booltrue": strictyaml.Bool()})) == {"booltrue": True}
>>> load("boolfalse: False", Map({"boolfalse": strictyaml.Bool()})) == {"booltrue": False}

Empty values

Empty values can be be validated and returned as None, {} and []:

>>> load("empty: ", Map({"empty": strictyaml.EmptyNone()})) == {"empty": None}
>>> load("empty: ", Map({"empty": strictyaml.EmptyDict()})) == {"empty": {}}
>>> load("empty: ", Map({"empty": strictyaml.EmptyList()})) == {"empty": []}

Enums

>>> load("day: monday", Map({"day": strictyaml.Enum(["monday", "tuesday", "wednesday"])})) == {"day": "monday"}

Datetimes

This datetime parser uses dateutil’s datetime parser, which is used, among others, by arrow, delorean and pendulum.

>>> load("date: 2016-10-22T14:23:12+00:00", Map({"date": strictyaml.Datetime()})) == {"date": datetime(2016, 10, 22, 14, 23, 12)}

Comma Separated Values

Scalar strings can be parsed a second time into comma separated values.

>>> load("a: 1, 2, 3", Map({"a": strictyaml.CommaSepaeated(strictyaml.Int())})) == {"a": [1, 2, 3, ]}

Custom scalar types

COMING SOON

Kwalify Validation

COMING SOON

Changelog

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

Contributors

  • @gvx

  • @AlexandreDecan

  • @lots0logs

Metadata

Release files for strictyaml 0.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for strictyaml 0.5.2
File Size Uploaded Provenance Actions
strictyaml-0.5.2.tar.gz 11.9 kB Without provenance Details for strictyaml-0.5.2.tar.gz

Release files / strictyaml-0.5.2.tar.gz

Download URL strictyaml-0.5.2.tar.gz
Size 11.9 kB
Tags Source
SHA-256 checksum
How to use checksums
31764dfb279506a683a1b9847de8cfcd182f56a651c4b4952ab311c130f6aafb
BLAKE2b-256 checksum
How to use checksums
cba0c779b2f93d5987bc9f816b925912c8b4d9cff45e4c0ddb61bd37c0ab1d2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for strictyaml 0.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.2 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page