son – Tools for working with SON, an ordered mapping — PyMongo 2.7.2 documentation

# `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`(data=None, **kwargs)

  SON data.

  A subclass of dict that maintains ordering of keys and provides a few extra niceties for dealing with SON. SON objects can be converted to and from BSON.

  The mapping from Python types to BSON types is as follows:

  Python Type | BSON Type | Supported Direction
  --- | --- | ---
  None | null | both
  bool | boolean | both
  int [1] | int32 / int64 | py -> bson
  long | int64 | both
  float | number (real) | both
  string | string | py -> bson
  unicode | string | both
  list | array | both
  dict / SON | object | both
  datetime.datetime [2] [3] | date | both
  bson.regex.Regex / compiled re [4] | regex | both
  bson.binary.Binary | binary | both
  bson.objectid.ObjectId | oid | both
  bson.dbref.DBRef | dbref | both
  None | undefined | bson -> py
  unicode | code | bson -> py
  bson.code.Code | code | py -> bson
  unicode | symbol | bson -> py
  bytes (Python 3) [5] | binary | both

  Note that to save binary data it must be wrapped as an instance of bson.binary.Binary. Otherwise it will be saved as a BSON string and retrieved as unicode.

  [1] | A Python int will be saved as a BSON int32 or BSON int64 depending on its size. A BSON int32 will always decode to a Python int. In Python 2.x a BSON int64 will always decode to a Python long. In Python 3.x a BSON int64 will decode to a Python int since there is no longer a long type.

  [2] | datetime.datetime instances will be rounded to the nearest millisecond when saved

  [3] | all datetime.datetime instances are treated as naive. clients should always use UTC.

  [4] | `Regex` instances and regular expression objects from `re.compile()` are both saved as BSON regular expressions. BSON regular expressions are decoded as Python regular expressions by default, or as `Regex` instances if the `compile_re` option is set to `False`.

  [5] | The bytes type from Python 3.x is encoded as BSON binary with subtype 0. In Python 3.x it will be decoded back to bytes. In Python 2.x it will be decoded to an instance of `Binary` with subtype 0.

  `to_dict`()

    Convert a SON document to a normal Python dictionary instance.

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