# salt.serializers.yamlex

YAMLEX is a format that allows for things like sls files to be more intuitive.

It's an extension of YAML that implements all the salt magic: - it implies omap for any dict like. - it implies that string like data are str, not unicode - ...

For example, the file states.sls has this contents:

    foo:
      bar: 42
      baz: [1, 2, 3]

The file can be parsed into Python like this

    from salt.serializers import yamlex

    with open('state.sls', 'r') as stream:
        obj = yamlex.deserialize(stream)

Check that `obj` is an OrderedDict

    from collections import OrderedDict

    assert isinstance(obj, dict)
    assert isinstance(obj, OrderedDict)

yamlex __repr__ and __str__ objects' methods render YAML understandable string. It means that they are template friendly.

    print '{0}'.format(obj)

returns:

    {foo: {bar: 42, baz: [1, 2, 3]}}

and they are still valid YAML:

    from salt.serializers import yaml
    yml_obj = yaml.deserialize(str(obj))
    assert yml_obj == obj

yamlex implements also custom tags:

!aggregate

> > this tag allows structures aggregation.

> For example:

>     placeholder: !aggregate foo
>     placeholder: !aggregate bar
>     placeholder: !aggregate baz

> is rendered as

>     placeholder: [foo, bar, baz]

!reset

> > this tag flushes the computing value.

>     placeholder: {!aggregate foo: {foo: 42}}
>     placeholder: {!aggregate foo: {bar: null}}
>     !reset placeholder: {!aggregate foo: {baz: inga}}

> is roughly equivalent to

>     placeholder: {!aggregate foo: {baz: inga}}

Document is defacto an aggregate mapping.

class salt.serializers.yamlex.AggregatedMap

class salt.serializers.yamlex.AggregatedSequence(iterable=(), /)

salt.serializers.yamlex.BaseDumper

  alias of `SafeDumper`

salt.serializers.yamlex.BaseLoader

  alias of `SafeLoader`

exception salt.serializers.yamlex.ConstructorError(context=None, context_mark=None, problem=None, problem_mark=None, note=None)

exception salt.serializers.yamlex.DeserializationError(message, line_num=None, buf='', marker=' <======================', trace=None)

  Raised when stream of string failed to be deserialized

class salt.serializers.yamlex.Dumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True)

  sls dumper.

  represent_odict(data)
  yaml_multi_representers = {<class 'NoneType'>: <function SafeRepresenter.represent_none>, <class 'bool'>: <function SafeRepresenter.represent_bool>, <class 'bytes'>: <function SafeRepresenter.represent_binary>, <class 'datetime.date'>: <function SafeRepresenter.represent_date>, <class 'datetime.datetime'>: <function SafeRepresenter.represent_datetime>, <class 'dict'>: <function Dumper.represent_odict>, <class 'float'>: <function SafeRepresenter.represent_float>, <class 'int'>: <function SafeRepresenter.represent_int>, <class 'list'>: <function SafeRepresenter.represent_list>, <class 'set'>: <function SafeRepresenter.represent_set>, <class 'str'>: <function SafeRepresenter.represent_str>, <class 'tuple'>: <function SafeRepresenter.represent_list>, None: <function SafeRepresenter.represent_undefined>}

class salt.serializers.yamlex.Loader(stream)

  Create a custom YAML loader that uses the custom constructor. This allows for the YAML loading defaults to be manipulated based on needs within salt to make things like sls file more intuitive.

  DEFAULT_MAPPING_TAG = 'tag:yaml.org,2002:omap'
  DEFAULT_SCALAR_TAG = 'tag:yaml.org,2002:str'
  DEFAULT_SEQUENCE_TAG = 'tag:yaml.org,2002:seq'
  compose_document()
  construct_sls_aggregate(node)
  construct_sls_int(node)

    Verify integers and pass them in correctly is they are declared as octal

  construct_sls_reset(node)
  construct_sls_str(node)

    Build the SLSString.

  construct_yaml_omap(node)

    Build the SLSMap

  resolve_sls_tag(node)
  yaml_constructors = {'!aggregate': <function Loader.construct_sls_aggregate>, '!reset': <function Loader.construct_sls_reset>, 'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function Loader.construct_sls_int>, 'tag:yaml.org,2002:map': <function SafeConstructor.construct_yaml_map>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function Loader.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function SafeConstructor.construct_yaml_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function Loader.construct_sls_str>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}
  yaml_multi_constructors = {'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:map': <function SafeConstructor.construct_yaml_map>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function SafeConstructor.construct_yaml_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>}

class salt.serializers.yamlex.Map

  Map aggregation.

class salt.serializers.yamlex.MappingNode(tag, value, start_mark=None, end_mark=None, flow_style=None)
  id = 'mapping'

class salt.serializers.yamlex.OrderedDict

  Dictionary that remembers insertion order

  clear() → None. Remove all items from od.
  copy() → a shallow copy of od
  classmethod fromkeys(iterable, value=None)

    Create a new ordered dictionary with keys from iterable and values set to value.

  items()

    Return a set-like object providing a view on the dict's items.

  keys()

    Return a set-like object providing a view on the dict's keys.

  move_to_end(key, last=True)

    Move an existing element to the end (or beginning if last is false).

    Raise KeyError if the element does not exist.

  pop(key[, default]) → v, remove specified key and return the corresponding value.

    If the key is not found, return the default if given; otherwise, raise a KeyError.

  popitem(last=True)

    Remove and return a (key, value) pair from the dictionary.

    Pairs are returned in LIFO order if last is true or FIFO order if false.

  setdefault(key, default=None)

    Insert key with a value of default if key is not in the dictionary.

    Return the value for key if key is in the dictionary, else default.

  update([E, ]**F) → None. Update D from mapping/iterable E and F.

    If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

  values()

    Return an object providing a view on the dict's values.

class salt.serializers.yamlex.SLSMap

  Ensures that dict str() and repr() are YAML friendly.

      >>> mapping = OrderedDict([('a', 'b'), ('c', None)])
      >>> print mapping
      OrderedDict([('a', 'b'), ('c', None)])

      >>> sls_map = SLSMap(mapping)
      >>> print sls_map.__str__()
      {a: b, c: null}

class salt.serializers.yamlex.SLSString

  Ensures that str str() and repr() are YAML friendly.

      >>> scalar = str('foo')
      >>> print 'foo'
      foo

      >>> sls_scalar = SLSString(scalar)
      >>> print sls_scalar
      "foo"

exception salt.serializers.yamlex.ScannerError(context=None, context_mark=None, problem=None, problem_mark=None, note=None)

class salt.serializers.yamlex.Sequence(iterable=(), /)

  Sequence aggregation.

exception salt.serializers.yamlex.SerializationError(message='')

  Raised when stream of string failed to be serialized

salt.serializers.yamlex.aggregate(obj_a, obj_b, level=False, map_class=<class 'salt.utils.aggregation.Map'>, sequence_class=<class 'salt.utils.aggregation.Sequence'>)

  Merge obj_b into obj_a.

      >>> aggregate('first', 'second', True) == ['first', 'second']
      True

salt.serializers.yamlex.deserialize(stream_or_string, **options)

  Deserialize any string of stream like object into a Python data structure.

  Parameters:

    - stream_or_string -- stream or string to deserialize.

    - options -- options given to lower yaml module.

salt.serializers.yamlex.merge_recursive(obj_a, obj_b, level=False)

  Merge obj_b into obj_a.

salt.serializers.yamlex.serialize(obj, **options)

  Serialize Python data to YAML.

  Parameters:

    - obj -- the data structure to serialize

    - options -- options given to lower yaml module.