python-ulid 3.1.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

{python_ulid-3.1.0.dist-info → python_ulid-3.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ulid
-Version: 3.1.0
+Version: 3.2.0
 Summary: Universally unique lexicographically sortable identifier
 Project-URL: Homepage, https://github.com/mdomke/python-ulid
 Project-URL: Documentation, https://python-ulid.readthedocs.io
@@ -18,13 +18,14 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.9
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions; python_version < '3.11'
 Provides-Extra: pydantic
 Requires-Dist: pydantic>=2.0; extra == 'pydantic'
 Description-Content-Type: text/x-rst
@@ -40,6 +41,7 @@ A ``ULID`` is a *universally unique lexicographically sortable identifier*. It i
 * Uses Crockford's base32 for better efficiency and readability (5 bits per character)
 * Case insensitive
 * No special characters (URL safe)
+* Monotonic sort order (correctly detects and handles the same millisecond)
 
 In general the structure of a ULID is as follows:
 
@@ -148,6 +150,20 @@ The ``ULID`` class can be directly used for the popular data validation library
 
 .. pydantic-end
 
+.. monotonic-begin
+
+Monotonic Support
+-----------------
+
+This library by default supports the implementation for monotonic sort order suggested by the
+official ULID specification.
+
+This means that ULID values generated in the same millisecond will have linear increasing randomness
+values. If :math:`r_1` and :math:`r_2` are the randomness values of two ULIDs with the same
+timestamp, then :math:`r_2 = r_1 + 1`.
+
+.. monotonic-end
+
 .. cli-begin
 
 Command line interface
@@ -205,3 +221,9 @@ Other implementations
 * `ulid/javascript <https://github.com/ulid/javascript>`_
 * `RobThree/NUlid <https://github.com/RobThree/NUlid>`_
 * `imdario/go-ulid <https://github.com/imdario/go-ulid>`_
+
+Contributions
+-------------
+
+Contributions are welcome! Feel free to create pull-requests for issues or feature requests.
+It might be worth creating an issue upfront to discuss the matter.

python_ulid-3.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ulid/__init__.py,sha256=MokfVXGP3iguVkHuzaJvLeFytWAqe_jAqrQqzWYDbRs,16352
+ulid/__main__.py,sha256=ZP8ZbhQ_o-O4Ckbba87bZ4NkwzrSFhAkrRLmUnzkW0Y,5586
+ulid/base32.py,sha256=iUE5BGPW5Dul-Eu3ITvcymk8acNkIFAVTlrL12YIPKI,5961
+ulid/constants.py,sha256=lbCLRNQXq8qnOdz_w-nJf_j5dC2X7Gjv-8GJUbs5jX8,503
+ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_ulid-3.2.0.dist-info/METADATA,sha256=4wbtd2VPXZ2fiKQx7lZexKFypftpTlj3qfoWbtN5bUw,6591
+python_ulid-3.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+python_ulid-3.2.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
+python_ulid-3.2.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
+python_ulid-3.2.0.dist-info/RECORD,,

{python_ulid-3.1.0.dist-info → python_ulid-3.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

ulid/__init__.py

@@ -13,19 +13,23 @@ from typing import Generic
 from typing import TYPE_CHECKING
 from typing import TypeVar
 
-from typing_extensions import Self
-
 from ulid import base32
 from ulid import constants
 
 
 if TYPE_CHECKING:  # pragma: no cover
+    import sys
     from collections.abc import Callable
 
     from pydantic import GetCoreSchemaHandler
     from pydantic import ValidatorFunctionWrapHandler
     from pydantic_core import CoreSchema
 
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
+
 try:
     from importlib.metadata import version
 except ImportError:  # pragma: no cover
@@ -34,12 +38,12 @@ except ImportError:  # pragma: no cover
 
 __version__ = version("python-ulid")
 
-T = TypeVar("T", bound=type)
+T = TypeVar("T")
 R = TypeVar("R")
 
 
 class validate_type(Generic[T]):  # noqa: N801
-    def __init__(self, *types: T) -> None:
+    def __init__(self, *types: type[T]) -> None:
         self.types = types
 
     def __call__(self, func: Callable[..., R]) -> Callable[..., R]:
@@ -69,9 +73,10 @@ class ValueProvider:
             raise ValueError("Value exceeds maximum possible timestamp")
         return value
 
-    def randomness(self) -> bytes:
+    def randomness(self, current_timestamp: int | None = None) -> bytes:
         with self.lock:
-            current_timestamp = self.timestamp()
+            if current_timestamp is None:
+                current_timestamp = self.timestamp()
             if current_timestamp == self.prev_timestamp:
                 if self.prev_randomness == constants.MAX_RANDOMNESS:
                     raise ValueError("Randomness within same millisecond exhausted")
@@ -148,8 +153,9 @@ class ULID:
             >>> ULID.from_timestamp(time.time())
             ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)
         """
-        timestamp = int.to_bytes(cls.provider.timestamp(value), constants.TIMESTAMP_LEN, "big")
-        randomness = cls.provider.randomness()
+        timestamp_value = cls.provider.timestamp(value)
+        timestamp = int.to_bytes(timestamp_value, constants.TIMESTAMP_LEN, "big")
+        randomness = cls.provider.randomness(timestamp_value)
         return cls.from_bytes(timestamp + randomness)
 
     @classmethod
@@ -199,7 +205,7 @@ class ULID:
             a value when they're unsure what format/primitive type it will be given in.
         """
         if isinstance(value, ULID):
-            return cast(Self, value)
+            return cast("Self", value)
         if isinstance(value, uuid.UUID):
             return cls.from_uuid(value)
         if isinstance(value, str):
@@ -281,6 +287,84 @@ class ULID:
         """
         return uuid.UUID(bytes=self.bytes, version=4)
 
+    def to_uuid7(self, *, compliant: bool = False) -> uuid.UUID:
+        """Convert the :class:`ULID` to a UUIDv7 (:class:`uuid.UUID` version 7).
+
+        UUIDv7 encodes a Unix timestamp in milliseconds in the first 48 bits (just like ULID).
+        The timestamp is always transparently preserved regardless of compliant mode.
+
+        Args:
+            compliant: If True, sets RFC 4122 version (0x7) and variant (0b10) bits,
+                      losing 6 bits of randomness. If False (default), preserves all 80 bits
+                      of randomness by clobbering version/variant bits, enabling perfect
+                      round-trip conversion. Most tools (PostgreSQL, standard libraries)
+                      accept non-compliant UUIDv7s.
+
+        Examples:
+
+            >>> ulid = ULID()
+            >>> uuid7 = ulid.to_uuidv7()  # Perfect round-trip
+            >>> assert ULID.from_uuidv7(uuid7) == ulid
+            >>> uuid7_compliant = ulid.to_uuidv7(compliant=True)  # RFC 4122 compliant
+            >>> uuid7_compliant.version
+            7
+        """
+        # ULID:   [48 bits timestamp_ms][80 bits randomness]
+        # UUIDv7: [48 bits timestamp_ms][4 bits ver][12 bits rand_a][2 bits var][62 bits rand_b]
+
+        timestamp_ms = self.milliseconds
+
+        # Get the 80 bits of randomness from ULID
+        randomness_bits = int.from_bytes(self.bytes[6:], byteorder="big")
+
+        if compliant:
+            # RFC 4122 compliant: set version and variant bits, losing 6 bits of randomness
+            # Extract 74 bits of randomness (losing 6 bits for version/variant)
+            rand_a = (randomness_bits >> 68) & 0xFFF  # Top 12 bits
+            rand_b = randomness_bits & ((1 << 62) - 1)  # Bottom 62 bits
+
+            # Build UUIDv7: [48-bit timestamp_ms][4-bit version][12-bit rand_a][2-bit variant][62-bit rand_b]
+            uuid_int = (timestamp_ms << 80) | (0x7 << 76) | (rand_a << 64) | (0x2 << 62) | rand_b
+        else:
+            # Non-compliant: preserve all 80 bits of randomness for perfect round-trip
+            # Build UUIDv7: [48-bit timestamp_ms][80-bit randomness] (clobbers version/variant)
+            uuid_int = (timestamp_ms << 80) | randomness_bits
+
+        uuid_bytes = uuid_int.to_bytes(16, byteorder="big")
+        return uuid.UUID(bytes=uuid_bytes)
+
+    @classmethod
+    @validate_type(uuid.UUID)
+    def from_uuidv7(cls, value: uuid.UUID) -> Self:
+        """Create a new :class:`ULID` from a UUIDv7 (:class:`uuid.UUID` version 7).
+
+        Extracts the timestamp from the UUIDv7's first 48 bits (milliseconds since epoch)
+        and the remaining 80 bits as randomness. The timestamp is always transparently
+        preserved, providing perfect round-trip conversion with :meth:`to_uuidv7`.
+
+        Examples:
+
+            >>> uuid7 = uuid.UUID("01936c5e-f4c0-7000-8000-000000000000")
+            >>> ulid = ULID.from_uuidv7(uuid7)
+            >>> ulid.datetime
+            datetime.datetime(2025, 11, 10, ...)
+        """
+        uuid_int = int.from_bytes(value.bytes, byteorder="big")
+
+        # Extract timestamp from UUIDv7 layout (always in first 48 bits)
+        # Bits 0-47: timestamp_ms (48 bits)
+        timestamp_ms = uuid_int >> 80
+
+        # Extract all 80 bits after the timestamp (bits 48-127) as randomness
+        # This includes version/variant bits if present, enabling perfect round-trip
+        randomness_bits = uuid_int & ((1 << 80) - 1)
+
+        # Build ULID bytes: [48-bit timestamp][80-bit randomness]
+        timestamp_bytes = timestamp_ms.to_bytes(6, byteorder="big")
+        randomness_bytes = randomness_bits.to_bytes(10, byteorder="big")
+
+        return cls.from_bytes(timestamp_bytes + randomness_bytes)
+
     def __repr__(self) -> str:
         return f"ULID({self!s})"
 

ulid/__main__.py

@@ -89,6 +89,7 @@ def make_parser(prog: str | None = None) -> argparse.ArgumentParser:
     s.add_argument("ulid", help="the ULID to inspect. The special value - reads from stdin")
     s.add_argument("--uuid", action="store_true", help="convert to fully random UUID")
     s.add_argument("--uuid4", action="store_true", help="convert to RFC 4122 compliant UUIDv4")
+    s.add_argument("--uuid7", action="store_true", help="convert to RFC 4122 compliant UUIDv7")
     s.add_argument("--hex", action="store_true", help="convert to hex")
     s.add_argument("--int", action="store_true", help="convert to int")
     s.add_argument("--timestamp", "--ts", action="store_true", help="show timestamp")
@@ -141,6 +142,8 @@ def show(args: argparse.Namespace) -> str:
         return str(ulid.to_uuid())
     if args.uuid4:
         return str(ulid.to_uuid4())
+    if args.uuid7:
+        return str(ulid.to_uuid7(compliant=True))
     if args.hex:
         return ulid.hex
     if args.int:

python_ulid-3.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ulid/__init__.py,sha256=g9Fb4nyq2mt3wGtLdmv3h9HutFJXLsrv_3HiVM-Qph8,12419
-ulid/__main__.py,sha256=TUo3dkWkJLfzRJyd55nfqGqvv1NcG7fBpsZHIi_p4rw,5421
-ulid/base32.py,sha256=iUE5BGPW5Dul-Eu3ITvcymk8acNkIFAVTlrL12YIPKI,5961
-ulid/constants.py,sha256=lbCLRNQXq8qnOdz_w-nJf_j5dC2X7Gjv-8GJUbs5jX8,503
-ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_ulid-3.1.0.dist-info/METADATA,sha256=TM_dpKEq830WTj6mahb6qF_5wiVnL6-Rau-6REqSoSQ,5833
-python_ulid-3.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-python_ulid-3.1.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-3.1.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-3.1.0.dist-info/RECORD,,