objectid – Tools for working with MongoDB ObjectIds — PyMongo 2.7.2 documentation

# `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 also

  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.

  classmethod `is_valid`(oid)

    Checks if a oid string is valid or not.

    Parameters: | oid: the object id to validate

    New in version 2.3.