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
compiled re	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

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. A BSON int64 will always decode to a Python long.

[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.

to_dict()

Convert a SON document to a normal Python dictionary instance.

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