<commit_before>StrictYAML
==========

StrictYAML is a `type-safe <https://en.wikipedia.org/wiki/Type_safety>`_ YAML parser
that parses a
`restricted subset <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-features-does-strictyaml-remove>`_
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 near-drop in replacement for pyyaml, ruamel.yaml or poyo.
* Roundtripping - reading in (commented) YAML and writing it out with comments.
* Letting you worry about more interesting things than parsing or writing config files.

Simple example:

.. code-block:: yaml

  # All about the character
  name: <NAME>
  age: 42
  possessions:
    - Towel

Default parse result:

.. code-block:: python

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

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

Using a schema:

.. code-block:: python

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


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

.. code-block:: python

   >>> person['age'] = load('43')
   >>> print(person.as_yaml())
   # All about the character
   name: <NAME>
   age: 43
   possessions:
     - Towel

As well as look up line numbers:

.. code-block:: python

   >>> person['possessions'][0].start_line
   5


See more `example driven documentation <http://strictyaml.readthedocs.org/>`_.


Install It
----------

.. code-block:: sh

  $ pip install strictyaml



FAQ
---

From learning programmers:

* `What is YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-is-yaml>`_
* `Why should I care about YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-should-i-care-about-yaml>`_
* `When should I use a validator and when should I not? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#when-should-i-use-a-validator-and-when-should-i-not>`_

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:


* `Why should I use strictyaml instead of ordinary YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-should-i-use-strictyaml-instead-of-ordinary-YAML>`_
* `What features does StrictYAML remove? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-features-does-strictyaml-remove>`_
* `Why not use JSON for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-json-for-configuration-or-dsls>`_
* `Why not use INI files for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-ini-files-for-configuration-or-dsls>`_
* `Why shouldn't I just use python for configuration? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-shouldnt-i-just-use-python-for-configuration>`_
* `Why not use XML for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-xml-for-configuration-or-dsls>`_
* `Why not use TOML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-toml>`_
* `Why not use HJSON? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-hjson>`_<commit_msg>Fixed link to non-existing paragraph (#25)<commit_after>StrictYAML
==========

StrictYAML is a `type-safe <https://en.wikipedia.org/wiki/Type_safety>`_ YAML parser
that parses a
`restricted subset <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-features-does-strictyaml-remove>`_
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 near-drop in replacement for pyyaml, ruamel.yaml or poyo.
* Roundtripping - reading in (commented) YAML and writing it out with comments.
* Letting you worry about more interesting things than parsing or writing config files.

Simple example:

.. code-block:: yaml

  # All about the character
  name: <NAME>
  age: 42
  possessions:
    - Towel

Default parse result:

.. code-block:: python

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

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

Using a schema:

.. code-block:: python

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


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

.. code-block:: python

   >>> person['age'] = load('43')
   >>> print(person.as_yaml())
   # All about the character
   name: <NAME>
   age: 43
   possessions:
     - Towel

As well as look up line numbers:

.. code-block:: python

   >>> person['possessions'][0].start_line
   5


See more `example driven documentation <http://strictyaml.readthedocs.org/>`_.


Install It
----------

.. code-block:: sh

  $ pip install strictyaml



FAQ
---

From learning programmers:

* `What is YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-is-yaml>`_
* `Why should I care about YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-should-i-care-about-yaml>`_
* `When should I use a validator and when should I not? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#when-should-i-use-a-validator-and-when-should-i-not>`_

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:


* `Why should I use strictyaml instead of ordinary YAML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-should-i-use-strictyaml-instead-of-ordinary-yaml>`_
* `What features does StrictYAML remove? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#what-features-does-strictyaml-remove>`_
* `Why not use JSON for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-json-for-configuration-or-dsls>`_
* `Why not use INI files for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-ini-files-for-configuration-or-dsls>`_
* `Why shouldn't I just use python for configuration? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-shouldnt-i-just-use-python-for-configuration>`_
* `Why not use XML for configuration or DSLs? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-xml-for-configuration-or-dsls>`_
* `Why not use TOML? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-toml>`_
* `Why not use HJSON? <https://github.com/crdoconnor/strictyaml/blob/master/FAQ.rst#why-not-use-hjson>`_
{'fraction_non_alphanumeric': 0.15267175572519084, 'fraction_numerical': 0.004553368153207446, 'mean_word_length': 4.168166089965398, 'pattern_counts': {'":': 18, '<': 41, '<?xml version=': 0, '>': 89, 'https://': 26, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '162047', 'n_tokens_mistral': 2646, 'n_tokens_neox': 2545, 'n_words': 650}