objectid – Tools for working with MongoDB ObjectIds

Tools for working with MongoDB ObjectIds.

class bson.objectid.ObjectId([oid=None])

Initialize a new ObjectId.

If oid is None, create a new (unique) ObjectId. If oid is an instance of (basestring (str or bytes in python 3), ObjectId) validate it and use that. Otherwise, a TypeError is raised. If oid is invalid, InvalidId is raised.

Parameters :

• oid (optional): a valid ObjectId (12 byte binary or 24 character hex string)

New in version 1.2.1: The oid parameter can be a unicode instance (that contains only hexadecimal digits).

See general MongoDB documentation

objectids

str(o)

Get a hex encoded version of ObjectId o.

The following property always holds:

>>> o = ObjectId()
>>> o == ObjectId(str(o))
True

This representation is useful for urls or other places where o.binary is inappropriate.

binary

12-byte binary representation of this ObjectId.

classmethod from_datetime(generation_time)

Create a dummy ObjectId instance with a specific generation time.

This method is useful for doing range queries on a field containing ObjectId instances.

Warning

It is not safe to insert a document containing an ObjectId generated using this method. This method deliberately eliminates the uniqueness guarantee that ObjectIds generally provide. ObjectIds generated with this method should be used exclusively in queries.

generation_time will be converted to UTC. Naive datetime instances will be treated as though they already contain UTC.

An example using this helper to get documents where "_id" was generated before January 1, 2010 would be:

>>> gen_time = datetime.datetime(2010, 1, 1)
>>> dummy_id = ObjectId.from_datetime(gen_time)
>>> result = collection.find({"_id": {"$lt": dummy_id}})

Parameters :

• generation_time: datetime to be used as the generation time for the resulting ObjectId.

Changed in version 1.8: Properly handle timezone aware values for generation_time.

New in version 1.6.

generation_time

A datetime.datetime instance representing the time of generation for this ObjectId.

The datetime.datetime is timezone aware, and represents the generation time in UTC. It is precise to the second.

Changed in version 1.8: Now return an aware datetime instead of a naive one.

New in version 1.2.