diff --git a/bson/objectid.py b/bson/objectid.py index c5591aaac4..a506929f08 100644 --- a/bson/objectid.py +++ b/bson/objectid.py @@ -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): @@ -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. @@ -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: diff --git a/doc/changelog.rst b/doc/changelog.rst index dc0e697fdf..1238fe7822 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -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 ......... @@ -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 diff --git a/doc/contributors.rst b/doc/contributors.rst index 4caa90eebe..e99ffcaa42 100644 --- a/doc/contributors.rst +++ b/doc/contributors.rst @@ -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) diff --git a/test/test_objectid.py b/test/test_objectid.py index b000b9bf54..d6bc695810 100644 --- a/test/test_objectid.py +++ b/test/test_objectid.py @@ -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]: