Skip to content

PYTHON-5883 Add unique parameter to ObjectId.from_datetime - #3187

Open
techi101 wants to merge 2 commits into
mongodb:mainfrom
techi101:PYTHON-5883-unique-from-datetime
Open

techi101 wants to merge 2 commits into
mongodb:mainfrom
techi101:PYTHON-5883-unique-from-datetime

Conversation

@techi101

@techi101 techi101 commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

PYTHON-5883

Changes in this PR

ObjectId.from_datetime() fills the 8 bytes after the timestamp with zeros, so it can only make dummy ids for range queries. The ticket asks for a way to make a real, unique ObjectId from an external timestamp, like Go's NewObjectIDFromTimestamp.

This adds a keyword-only unique parameter:

ObjectId.from_datetime(dt)               # unchanged: zero-filled dummy for queries
ObjectId.from_datetime(dt, unique=True)  # timestamp + process random value + counter
  • The bytes-building code from ObjectId.__init__ (counter under _inc_lock, then 4-byte timestamp + 5-byte random + 3-byte counter) moved into a private _generate(timestamp) classmethod. ObjectId() now calls it, so its behavior is unchanged, and from_datetime(..., unique=True) reuses it.
  • unique is keyword-only and defaults to False, so existing callers are unaffected.
  • Updated the docstring (the warning now applies to unique=False) with versionchanged:: 4.20, added a changelog entry, and added myself to doc/contributors.rst.

I went with a parameter on the existing method to keep one entry point, but I'm happy to switch to a separate classmethod or another name if you prefer (I asked on the ticket too).

I used Claude to help with this, and I reviewed and tested the change myself.

Test Plan

Two new tests in test/test_objectid.py:

  • test_from_datetime_unique: two calls with the same datetime keep that timestamp but are different, are not zero-filled, carry the process random value in bytes 4-8 (same as ObjectId()), the counter goes up by one, and aware datetimes are converted to UTC like before.
  • test_from_datetime_unique_is_keyword_only: passing unique positionally raises TypeError.

The new test fails on main and passes with the change. pytest test/test_objectid.py test/test_json_util.py: 45 passed. ruff format --check and mypy bson/objectid.py pass.

Checklist

Checklist for Author

  • Did you update the changelog (if necessary)?
  • Is there test coverage?
  • Is any followup work tracked in a JIRA ticket? If so, add link(s).

Checklist for Reviewer

  • Does the title of the PR reference a JIRA Ticket?
  • Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
  • Is all relevant documentation (README or docstring) updated?

ObjectId.from_datetime() fills the 8 bytes after the timestamp with
zeros, so it can only make dummy ids for range queries. With
unique=True it fills them like ObjectId() does (process random value
plus counter), giving a unique id with an external timestamp, like
NewObjectIDFromTimestamp in the Go driver.

Assisted-by: Claude
@techi101
techi101 requested a review from a team as a code owner November 7, 2026 10:46
@techi101
techi101 requested a review from sleepyStick November 7, 2026 10:46

@sleepyStick sleepyStick left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for your work! I've got some changes - kinda minor i think? but shouldn't take too long to actually fix!

Comment thread bson/objectid.py Outdated
return cls(cls._generate(timestamp))
return cls(_PACK_INT(timestamp) + b"\x00\x00\x00\x00\x00\x00\x00\x00")

@classmethod

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
@classmethod
@staticmethod

Comment thread bson/objectid.py Outdated
return cls(_PACK_INT(timestamp) + b"\x00\x00\x00\x00\x00\x00\x00\x00")

@classmethod
def _generate(cls, timestamp: int) -> bytes:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
def _generate(cls, timestamp: int) -> bytes:
def _generate_bytes(cls, timestamp: int) -> bytes:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe? idk _generate itself feels too vague though. Open to other ideas but I do want the name to be more specific

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants