# salt.aggregation

## salt.utils.aggregation

This library makes it possible to introspect dataset and aggregate nodes when it is instructed.

Note

The following examples with be expressed in YAML for convenience's sake:

- !aggr-scalar will refer to Scalar python function

- !aggr-map will refer to Map python object

- !aggr-seq will refer for Sequence python object

### How to instructs merging

This yaml document has duplicate keys:

    foo: !aggr-scalar first
    foo: !aggr-scalar second
    bar: !aggr-map {first: foo}
    bar: !aggr-map {second: bar}
    baz: !aggr-scalar 42

but tagged values instruct Salt that overlapping values they can be merged together:

    foo: !aggr-seq [first, second]
    bar: !aggr-map {first: foo, second: bar}
    baz: !aggr-seq [42]

### Default merge strategy is keep untouched

For example, this yaml document still has duplicate keys, but does not instruct aggregation:

    foo: first
    foo: second
    bar: {first: foo}
    bar: {second: bar}
    baz: 42

So the late found values prevail:

    foo: second
    bar: {second: bar}
    baz: 42

### Limitations

Aggregation is permitted between tagged objects that share the same type. If not, the default merge strategy prevails.

For example, these examples:

    foo: {first: value}
    foo: !aggr-map {second: value}

    bar: !aggr-map {first: value}
    bar: 42

    baz: !aggr-seq [42]
    baz: [fail]

    qux: 42
    qux: !aggr-scalar fail

are interpreted like this:

    foo: !aggr-map{second: value}

    bar: 42

    baz: [fail]

    qux: !aggr-seq [fail]

### Introspection

TODO: write this part

class salt.utils.aggregation.Aggregate

  Aggregation base.

class salt.utils.aggregation.Map

  Map aggregation.

class salt.utils.aggregation.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.

salt.utils.aggregation.Scalar(obj)

  Shortcut for Sequence creation

      >>> Scalar('foo') == Sequence(['foo'])
      True

class salt.utils.aggregation.Sequence(iterable=(), /)

  Sequence aggregation.

salt.utils.aggregation.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.utils.aggregation.levelise(level)

  Describe which levels are allowed to do deep merging.

  level can be:

  True

    all levels are True

  False

    all levels are False

  an int

    only the first levels are True, the others are False

  a sequence

    it describes which levels are True, it can be:

    - a list of bool and int values

    - a string of 0 and 1 characters

salt.utils.aggregation.mark(obj, map_class=<class 'salt.utils.aggregation.Map'>, sequence_class=<class 'salt.utils.aggregation.Sequence'>)

  Convert obj into an Aggregate instance