# `son` – Tools for working with SON, an ordered mapping

Tools for creating and manipulating SON, the Serialized Ocument Notation.

Regular dictionaries can be used instead of SON objects, but not when the order of keys is important. A SON object can be used just like a normal Python dictionary.

class bson.son.SON(*args, **kwargs)

  SON data.

  A subclass of dict that maintains ordering of keys and provides a few extra niceties for dealing with SON. SON provides an API similar to collections.OrderedDict.

  Parameters:

    - args (Any)

    - kwargs (Any)

  Return type:

    SON[_Key, _Value]

  clear()

    Remove all items from the dict.

    Return type:

      None

  copy()

    Return a shallow copy of the dict.

    Return type:

      SON[_Key, _Value]

  get(key, default=None)

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

    Parameters:

      - key (_Key)

      - default (_Value | _T | None)

    Return type:

      _Value | _T | None

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

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

    Parameters:

      - key (_Key)

      - args (_Value | _T)

    Return type:

      _Value | _T

  popitem()

    Remove and return a (key, value) pair as a 2-tuple.

    Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

    Return type:

      Tuple[_Key, _Value]

  setdefault(key, default)

    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.

    Parameters:

      - key (_Key)

      - default (_Value)

    Return type:

      _Value

  to_dict()

    Convert a SON document to a normal Python dictionary instance.

    This is trickier than just dict(…) because it needs to be recursive.

    Return type:

      dict[_Key, _Value]

  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]

    Parameters:

      - other (Any | None)

      - kwargs (_Value)

    Return type:

      None

  values()

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

    Return type:

      list[_Value]