Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 36 additions & 19 deletions bson/objectid.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,12 +98,7 @@ def __init__(self, oid: Optional[Union[str, ObjectId, bytes]] = None) -> None:
"""
if oid is None:
# Generate a new value for this ObjectId.
with ObjectId._inc_lock:
inc = ObjectId._inc
ObjectId._inc = (inc + 1) % (_MAX_COUNTER_VALUE + 1)

# 4 bytes current time, 5 bytes random, 3 bytes inc.
self.__id = _PACK_INT_RANDOM(int(time.time()), ObjectId._random()) + _PACK_INT(inc)[1:4]
self.__id = ObjectId._generate_bytes(int(time.time()))
elif isinstance(oid, bytes) and len(oid) == 12:
self.__id = oid
elif isinstance(oid, str):
Expand All @@ -124,19 +119,27 @@ def __init__(self, oid: Optional[Union[str, ObjectId, bytes]] = None) -> None:
raise TypeError(f"id must be an instance of (bytes, str, ObjectId), not {type(oid)}")

@classmethod
def from_datetime(cls: type[ObjectId], generation_time: datetime.datetime) -> ObjectId:
"""Create a dummy ObjectId instance with a specific generation time.
def from_datetime(
cls: type[ObjectId], generation_time: datetime.datetime, *, unique: bool = False
) -> ObjectId:
"""Create an ObjectId instance with a specific generation time.

This method is useful for doing range queries on a field
containing :class:`ObjectId` instances.
By default this creates a dummy ObjectId whose 8 bytes after the
timestamp are all zero. This is useful for doing range queries on
a field containing :class:`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
With the default ``unique=False`` it is not safe to insert a
document containing an ObjectId generated using this method.
Such an ObjectId deliberately has no uniqueness guarantee and
should be used exclusively in queries.

With ``unique=True`` the bytes after the timestamp are filled in
the same way as for ``ObjectId()``: the 5-byte random value of
this process followed by the 3-byte counter. The result is a
unique ObjectId that can be inserted, which is useful when the
timestamp comes from an external source.

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

Expand All @@ -149,12 +152,26 @@ def from_datetime(cls: type[ObjectId], generation_time: datetime.datetime) -> Ob

:param generation_time: :class:`~datetime.datetime` to be used
as the generation time for the resulting ObjectId.
:param unique: If ``True``, create a unique ObjectId that is safe
to insert, instead of a dummy ObjectId for queries.

.. versionchanged:: 4.20
Added the ``unique`` parameter.
"""
oid = (
_PACK_INT(_datetime_to_millis(generation_time) // 1000)
+ b"\x00\x00\x00\x00\x00\x00\x00\x00"
)
return cls(oid)
timestamp = _datetime_to_millis(generation_time) // 1000
if unique:
return cls(cls._generate_bytes(timestamp))
return cls(_PACK_INT(timestamp) + b"\x00\x00\x00\x00\x00\x00\x00\x00")

@staticmethod
def _generate_bytes(timestamp: int) -> bytes:
"""Return the 12 bytes of a new ObjectId with the given timestamp."""
with ObjectId._inc_lock:
inc = ObjectId._inc
ObjectId._inc = (inc + 1) % (_MAX_COUNTER_VALUE + 1)

# 4 bytes timestamp, 5 bytes random, 3 bytes inc.
return _PACK_INT_RANDOM(timestamp, ObjectId._random()) + _PACK_INT(inc)[1:4]

@classmethod
def is_valid(cls: type[ObjectId], oid: Any) -> bool:
Expand Down
5 changes: 5 additions & 0 deletions doc/changelog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ Changes in Version 4.20.0 (2026/XX/XX)

- The client handshake metadata now reports a detected coding agent in
``client.env.agent`` (`PYTHON-5929`_).
- Added the ``unique`` parameter to
:meth:`~bson.objectid.ObjectId.from_datetime`. With ``unique=True`` it
creates a unique ObjectId with the given generation time that is safe to
insert, like ``NewObjectIDFromTimestamp`` in the Go driver (`PYTHON-5883`_).

Bug fixes
.........
Expand Down Expand Up @@ -36,6 +40,7 @@ Bug fixes
Users of Python 3.12 and 3.13 should upgrade to at least those versions (`PYTHON-6182`_).

.. _PYTHON-5929: https://jira.mongodb.org/browse/PYTHON-5929
.. _PYTHON-5883: https://jira.mongodb.org/browse/PYTHON-5883
.. _PYTHON-6172: https://jira.mongodb.org/browse/PYTHON-6172
.. _PYTHON-6149: https://jira.mongodb.org/browse/PYTHON-6149
.. _PYTHON-5873: https://jira.mongodb.org/browse/PYTHON-5873
Expand Down
1 change: 1 addition & 0 deletions doc/contributors.rst
Original file line number Diff line number Diff line change
Expand Up @@ -111,3 +111,4 @@ The following is a list of people who have contributed to
- Sophia Yang (sophiayangDB)
- Madan Kumar (winklemad)
- Junyao Dong (carsontung666)
- Nitesh Kumar Yadav (techi101)
29 changes: 29 additions & 0 deletions test/test_objectid.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,35 @@ def test_from_datetime(self):
oid = ObjectId.from_datetime(aware)
self.assertEqual(as_utc, oid.generation_time)

def test_from_datetime_unique(self):
d = datetime.datetime(2020, 5, 17, 10, 30, 15)
oid1 = ObjectId.from_datetime(d, unique=True)
oid2 = ObjectId.from_datetime(d, unique=True)

# Same timestamp, but unique and not the zero-filled dummy.
self.assertEqual(d, oid1.generation_time.replace(tzinfo=None))
self.assertEqual(d, oid2.generation_time.replace(tzinfo=None))
self.assertNotEqual(oid1, oid2)
self.assertNotEqual("0" * 16, str(oid1)[8:])

# Same layout as ObjectId(): 5-byte process random, then the counter.
self.assertEqual(oid1.binary[4:9], ObjectId._random())
self.assertEqual(oid1.binary[4:9], ObjectId().binary[4:9])
inc1 = struct.unpack(">I", b"\x00" + oid1.binary[9:12])[0]
inc2 = struct.unpack(">I", b"\x00" + oid2.binary[9:12])[0]
self.assertEqual((inc1 + 1) % (_MAX_COUNTER_VALUE + 1), inc2)

# Aware datetimes are converted to UTC, as with unique=False.
aware = datetime.datetime(1993, 4, 4, 2, tzinfo=FixedOffset(555, "SomeZone"))
self.assertEqual(
ObjectId.from_datetime(aware).generation_time,
ObjectId.from_datetime(aware, unique=True).generation_time,
)

def test_from_datetime_unique_is_keyword_only(self):
with self.assertRaises(TypeError):
ObjectId.from_datetime(datetime.datetime(2020, 1, 1), True) # type: ignore[misc]

def test_pickling(self):
orig = ObjectId()
for protocol in [0, 1, 2, -1]:
Expand Down