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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-ulid
-Version: 3.0.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,12 +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
@@ -39,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:
 
@@ -147,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
@@ -204,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.0.0.dist-info → python_ulid-3.2.0.dist-info}/WHEEL

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

ulid/__init__.py

@@ -6,6 +6,7 @@ import time
 import uuid
 from datetime import datetime
 from datetime import timezone
+from threading import Lock
 from typing import Any
 from typing import cast
 from typing import Generic
@@ -17,12 +18,18 @@ 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
@@ -31,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]:
@@ -51,11 +58,45 @@ class validate_type(Generic[T]):  # noqa: N801
         return wrapped
 
 
-U = TypeVar("U", bound="ULID")
+class ValueProvider:
+    def __init__(self) -> None:
+        self.lock = Lock()
+        self.prev_timestamp = constants.MIN_TIMESTAMP
+        self.prev_randomness = constants.MIN_RANDOMNESS
+
+    def timestamp(self, value: float | None = None) -> int:
+        if value is None:
+            value = time.time_ns() // constants.NANOSECS_IN_MILLISECS
+        elif isinstance(value, float):
+            value = int(value * constants.MILLISECS_IN_SECS)
+        if value > constants.MAX_TIMESTAMP:
+            raise ValueError("Value exceeds maximum possible timestamp")
+        return value
+
+    def randomness(self, current_timestamp: int | None = None) -> bytes:
+        with self.lock:
+            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")
+                randomness = self.increment_bytes(self.prev_randomness)
+            else:
+                randomness = os.urandom(constants.RANDOMNESS_LEN)
+
+            self.prev_randomness = randomness
+            self.prev_timestamp = current_timestamp
+        return randomness
+
+    def increment_bytes(self, value: bytes) -> bytes:
+        length = len(value)
+        return (int.from_bytes(value, byteorder="big") + 1).to_bytes(length, byteorder="big")
 
 
 @functools.total_ordering
 class ULID:
+    provider = ValueProvider()
+
     """The :class:`ULID` object consists of a timestamp part of 48 bits and of 80 random bits.
 
     .. code-block:: text
@@ -83,13 +124,11 @@ class ULID:
     def __init__(self, value: bytes | None = None) -> None:
         if value is not None and len(value) != constants.BYTES_LEN:
             raise ValueError("ULID has to be exactly 16 bytes long.")
-        self.bytes: bytes = (
-            value or ULID.from_timestamp(time.time_ns() // constants.NANOSECS_IN_MILLISECS).bytes
-        )
+        self.bytes: bytes = value or ULID.from_timestamp(self.provider.timestamp()).bytes
 
     @classmethod
     @validate_type(datetime)
-    def from_datetime(cls: type[U], value: datetime) -> U:
+    def from_datetime(cls, value: datetime) -> Self:
         """Create a new :class:`ULID`-object from a :class:`datetime`. The timestamp part of the
         `ULID` will be set to the corresponding timestamp of the datetime.
 
@@ -103,7 +142,7 @@ class ULID:
 
     @classmethod
     @validate_type(int, float)
-    def from_timestamp(cls: type[U], value: float) -> U:
+    def from_timestamp(cls, value: float) -> Self:
         """Create a new :class:`ULID`-object from a timestamp. The timestamp can be either a
         `float` representing the time in seconds (as it would be returned by :func:`time.time()`)
         or an `int` in milliseconds.
@@ -114,15 +153,14 @@ class ULID:
             >>> ULID.from_timestamp(time.time())
             ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)
         """
-        if isinstance(value, float):
-            value = int(value * constants.MILLISECS_IN_SECS)
-        timestamp = int.to_bytes(value, constants.TIMESTAMP_LEN, "big")
-        randomness = os.urandom(constants.RANDOMNESS_LEN)
+        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
     @validate_type(uuid.UUID)
-    def from_uuid(cls: type[U], value: uuid.UUID) -> U:
+    def from_uuid(cls, value: uuid.UUID) -> Self:
         """Create a new :class:`ULID`-object from a :class:`uuid.UUID`. The timestamp part will be
         random in that case.
 
@@ -136,37 +174,38 @@ class ULID:
 
     @classmethod
     @validate_type(bytes)
-    def from_bytes(cls: type[U], bytes_: bytes) -> U:
+    def from_bytes(cls, bytes_: bytes) -> Self:
         """Create a new :class:`ULID`-object from sequence of 16 bytes."""
         return cls(bytes_)
 
     @classmethod
     @validate_type(str)
-    def from_hex(cls: type[U], value: str) -> U:
+    def from_hex(cls, value: str) -> Self:
         """Create a new :class:`ULID`-object from 32 character string of hex values."""
         return cls.from_bytes(bytes.fromhex(value))
 
     @classmethod
     @validate_type(str)
-    def from_str(cls: type[U], string: str) -> U:
+    def from_str(cls, string: str) -> Self:
         """Create a new :class:`ULID`-object from a 26 char long string representation."""
         return cls(base32.decode(string))
 
     @classmethod
     @validate_type(int)
-    def from_int(cls: type[U], value: int) -> U:
+    def from_int(cls, value: int) -> Self:
         """Create a new :class:`ULID`-object from an `int`."""
         return cls(int.to_bytes(value, constants.BYTES_LEN, "big"))
 
     @classmethod
-    def parse(cls: type[U], value: Any) -> U:
+    def parse(cls, value: Any) -> Self:
         """Create a new :class:`ULID`-object from a given value.
 
-        .. note:: This method should only be used when the caller is trying to parse a ULID from
-        a value when they're unsure what format/primitive type it will be given in.
+        .. note::
+            This method should only be used when the caller is trying to parse a ULID from
+            a value when they're unsure what format/primitive type it will be given in.
         """
         if isinstance(value, ULID):
-            return cast(U, value)
+            return cast("Self", value)
         if isinstance(value, uuid.UUID):
             return cls.from_uuid(value)
         if isinstance(value, str):
@@ -190,7 +229,7 @@ class ULID:
             return cls.from_bytes(value)
         raise TypeError(f"Cannot parse ULID from type {type(value)}")
 
-    @property
+    @functools.cached_property
     def milliseconds(self) -> int:
         """The timestamp part as epoch time in milliseconds.
 
@@ -201,7 +240,7 @@ class ULID:
         """
         return int.from_bytes(self.bytes[: constants.TIMESTAMP_LEN], byteorder="big")
 
-    @property
+    @functools.cached_property
     def timestamp(self) -> float:
         """The timestamp part as epoch time in seconds.
 
@@ -212,7 +251,7 @@ class ULID:
         """
         return self.milliseconds / constants.MILLISECS_IN_SECS
 
-    @property
+    @functools.cached_property
     def datetime(self) -> datetime:
         """Return the timestamp part as timezone-aware :class:`datetime` in UTC.
 
@@ -223,7 +262,7 @@ class ULID:
         """
         return datetime.fromtimestamp(self.timestamp, timezone.utc)
 
-    @property
+    @functools.cached_property
     def hex(self) -> str:
         """Encode the :class:`ULID`-object as a 32 char sequence of hex values."""
         return self.bytes.hex()
@@ -248,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})"
 
@@ -297,7 +414,11 @@ class ULID:
             core_schema.union_schema([
                 core_schema.is_instance_schema(ULID),
                 core_schema.no_info_plain_validator_function(ULID),
-                core_schema.str_schema(pattern=r"[A-Z0-9]{26}", min_length=26, max_length=26),
+                core_schema.str_schema(
+                    pattern=rf"[0-7][{base32.ENCODE}]{{25}}",
+                    min_length=26,
+                    max_length=26,
+                ),
                 core_schema.bytes_schema(min_length=16, max_length=16),
             ]),
             serialization=core_schema.to_string_ser_schema(
@@ -309,6 +430,7 @@ class ULID:
     def _pydantic_validate(cls, value: Any, handler: ValidatorFunctionWrapHandler) -> Any:
         from pydantic_core import PydanticCustomError
 
+        ulid: ULID
         try:
             if isinstance(value, int):
                 ulid = cls.from_int(value)

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:

ulid/constants.py

@@ -1,6 +1,12 @@
 MILLISECS_IN_SECS = 1000
 NANOSECS_IN_MILLISECS = 1000000
 
+MIN_RANDOMNESS = b"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"
+MAX_RANDOMNESS = b"\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff"
+
+MIN_TIMESTAMP = 0
+MAX_TIMESTAMP = 2**48 - 1
+
 TIMESTAMP_LEN = 6
 RANDOMNESS_LEN = 10
 BYTES_LEN = TIMESTAMP_LEN + RANDOMNESS_LEN

python_ulid-3.0.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-ulid/__init__.py,sha256=yoBtXpTz-t8xnfOHtM70-hYIeYKk75ya7t6B6uWILhg,10971
-ulid/__main__.py,sha256=TUo3dkWkJLfzRJyd55nfqGqvv1NcG7fBpsZHIi_p4rw,5421
-ulid/base32.py,sha256=iUE5BGPW5Dul-Eu3ITvcymk8acNkIFAVTlrL12YIPKI,5961
-ulid/constants.py,sha256=tJByGuryoTT_xfECvpMNPNwRvZMp2K_ZlZ7tOLeaXJs,335
-ulid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_ulid-3.0.0.dist-info/METADATA,sha256=82s8fmElXLy5Um_bjqhtZfiXd54YF0TDI2iOlKliLMs,5782
-python_ulid-3.0.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-python_ulid-3.0.0.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-3.0.0.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-3.0.0.dist-info/RECORD,,