# 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

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