Add transparent bidirectional UUIDv7 conversion methods #48
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Implements to_uuidv7() and from_uuidv7() methods for converting between ULID and UUIDv7 formats. The implementation supports two modes: - compliant=False (default): Preserves all 80 bits of randomness by directly mapping the 48-bit ULID timestamp into the UUIDv7 structure without lossy fractional conversion. This enables perfect bit-for-bit round-trip conversion (ULID -> UUIDv7 -> ULID). - compliant=True: Sets RFC 4122 version (0x7) and variant (0b10) bits properly, losing 6 bits of randomness but producing spec-compliant UUIDv7s. Uses fractional millisecond encoding in subsec_a field. The from_uuidv7() method automatically detects whether a UUIDv7 is compliant by checking the version bits, and decodes accordingly to preserve maximum accuracy. Key features: - Transparent timestamp preservation in both modes - Perfect round-trip with compliant=False (default) - Monotonic ordering preserved when converting ULID sequences - Compatible with external UUIDv7s (e.g., from PostgreSQL, other libraries) - Comprehensive test coverage including edge cases This allows python-ulid to serve as a bridge between ULID and UUIDv7 ecosystems while maintaining the sortability and timestamp properties that make both formats useful.
The previous implementation incorrectly used different timestamp encodings for compliant vs non-compliant modes. This has been corrected so that: - The timestamp is ALWAYS encoded in the first 48 bits as milliseconds (identical to ULID's timestamp format) - This provides transparent, lossless timestamp preservation in both modes - Only the version/variant bits and randomness placement differ between modes Changes: - Simplified to_uuidv7(): Always uses (timestamp_ms << 80) | randomness - Simplified from_uuidv7(): Always extracts timestamp from first 48 bits - Updated tests to verify perfect timestamp preservation in both modes - Removed complex fractional/subsecond conversion logic This matches the UUIDv7 spec where the first 48 bits contain unix_ts_ms (Unix timestamp in milliseconds), making ULID and UUIDv7 timestamp formats directly compatible.
pirate
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds conversion to/from UUIDv7, which is now natively supported in python >= 3.14 and postgres >= 18.
This allows you to show a ULID to your users / use it in your URLs but store it efficiently as a uuidv7 in your DB without losing any timestamp or randomness information. This lets you use ULID in deployment environments that don't allow custom db extensions to be installed to allow for native db-level ulid support.
Because strictly proper uuids lose 6 bits of randomness compared to ULID, there is a compliant=True optional flag that can be enabled to drop that randomness when converting a ULID -> uuidv7 and replace it with the correct uuid version and variant bits. By default it clobbers those bits and uses them to keep 100% of the randomness and allow for safe round-trip conversion. In practice postgresql, sqlite, and most other tools will accept invalid uuidv7s version/variant bits, so it's usually safe to clobber them.