python-ulid 3.2.1__py3-none-any.whl → 4.0.1__py3-none-any.whl

{python_ulid-3.2.1.dist-info → python_ulid-4.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ulid
-Version: 3.2.1
+Version: 4.0.1
 Summary: Universally unique lexicographically sortable identifier
 Project-URL: Homepage, https://github.com/mdomke/python-ulid
 Project-URL: Documentation, https://python-ulid.readthedocs.io
@@ -164,6 +164,64 @@ timestamp, then :math:`r_2 = r_1 + 1`.
 
 .. monotonic-end
 
+.. generators-begin
+
+Generators and policies
+-----------------------
+
+Every ``ULID`` is produced by a ``ULIDGenerator``, which samples a clock for the timestamp,
+sources entropy for the randomness, and enforces a *monotonicity policy*. The bare ``ULID()``
+constructor and the ``ULID.from_*`` factory methods delegate to a shared module-level
+``default_generator``.
+
+For most use cases the default is all you need. To customize generation — a different clock, a
+custom entropy source, or another monotonicity policy — create your own ``ULIDGenerator`` and
+call ``generate()``
+
+.. code-block:: pycon
+
+   >>> from ulid import ULIDGenerator
+   >>> generator = ULIDGenerator()
+   >>> generator.generate()
+   ULID(01HB0N8Q4RCE7YB1M2VZK9WX3T)
+
+Choosing a monotonicity policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A policy decides how the randomness is resolved when multiple ULIDs are generated within the same
+millisecond. Three policies are available:
+
+* ``StrictMonotonicPolicy`` *(default)* — increments the randomness by 1 on a same-millisecond
+  collision and raises ``ValueError`` if the randomness is exhausted. This is the behaviour
+  described under `Monotonic Support`_.
+* ``LaxMonotonicPolicy`` — increments like the strict policy, but regenerates fresh randomness
+  instead of raising when the randomness is exhausted.
+* ``PureRandomPolicy`` — ignores previous state and always draws fresh randomness, maximizing
+  entropy at the cost of same-millisecond sort order.
+
+.. code-block:: pycon
+
+   >>> from ulid import ULIDGenerator, PureRandomPolicy
+   >>> generator = ULIDGenerator(policy=PureRandomPolicy())
+   >>> generator.generate()
+   ULID(01HB0N9F3TA5KDQ6ZE0WYV7MRC)
+
+Overriding the default generator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make ``ULID()`` and the ``ULID.from_*`` constructors use a custom generator globally, reassign
+``ulid.default_generator``
+
+.. code-block:: pycon
+
+   >>> import ulid
+   >>> from ulid import ULID, ULIDGenerator, LaxMonotonicPolicy
+   >>> ulid.default_generator = ULIDGenerator(policy=LaxMonotonicPolicy())
+   >>> ULID()  # now generated with the lax policy
+   ULID(01HB0NB7X2M4C8VKQ0ZF5WD9RA)
+
+.. generators-end
+
 .. cli-begin
 
 Command line interface

python_ulid-4.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+ulid/__init__.py,sha256=RUAerfe39tcNib2oAREKB7U9DfF-rdXueNg3kF76zV8,21227
+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-4.0.1.dist-info/METADATA,sha256=LuILMUf_zi1x8OonhM9KEuPdygFqPs9R4ubHAMxn6fQ,8758
+python_ulid-4.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+python_ulid-4.0.1.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
+python_ulid-4.0.1.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
+python_ulid-4.0.1.dist-info/RECORD,,

ulid/__init__.py

@@ -1,17 +1,24 @@
 from __future__ import annotations
 
+import abc
 import functools
 import os
 import time
 import uuid
+from collections.abc import Callable
 from datetime import datetime
 from datetime import timezone
 from threading import Lock
 from typing import Any
 from typing import cast
-from typing import Generic
+from typing import Protocol
 from typing import TYPE_CHECKING
-from typing import TypeVar
+
+
+try:
+    from typing import override
+except ImportError:
+    from typing_extensions import override  # type: ignore
 
 from ulid import base32
 from ulid import constants
@@ -19,7 +26,6 @@ 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
@@ -38,65 +44,202 @@ except ImportError:  # pragma: no cover
 
 __version__ = version("python-ulid")
 
-T = TypeVar("T")
-R = TypeVar("R")
+
+RandomnessSource = Callable[[int], bytes]
 
 
-class validate_type(Generic[T]):  # noqa: N801
-    def __init__(self, *types: type[T]) -> None:
-        self.types = types
+class MonotonicityPolicy(Protocol):
+    """Protocol defining the interface for monotonicity and randomness resolution policies."""
+
+    def resolve_randomness(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        """Resolve randomness for a given timestamp.
+
+        Args:
+            timestamp (int): The current timestamp in milliseconds.
+            randomness_source (RandomnessSource): A callable to get fresh random bytes.
 
-    def __call__(self, func: Callable[..., R]) -> Callable[..., R]:
-        @functools.wraps(func)
-        def wrapped(cls: Any, value: T) -> R:
-            if not isinstance(value, self.types):
-                message = "Value has to be of type "
-                message += " or ".join([t.__name__ for t in self.types])
-                raise TypeError(message)
-            return func(cls, value)
+        Returns:
+            bytes: The resolved randomness bytes (80 bits).
+        """
+        ...
 
-        return wrapped
 
+class BaseMonotonicPolicy(abc.ABC):
+    """Base class for stateful monotonic policies."""
 
-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:
+    def resolve_randomness(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        if timestamp == self.prev_timestamp:
+            if self.prev_randomness == constants.MAX_RANDOMNESS:
+                randomness = self._on_overflow(timestamp, randomness_source)
+            else:
+                randomness = self._increment(self.prev_randomness)
+        else:
+            randomness = randomness_source(timestamp)
+
+        self.prev_randomness = randomness
+        self.prev_timestamp = timestamp
+        return randomness
+
+    @staticmethod
+    def _increment(value: bytes) -> bytes:
+        return (int.from_bytes(value, byteorder="big") + 1).to_bytes(len(value), byteorder="big")
+
+    @abc.abstractmethod
+    def _on_overflow(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        """Handle same-millisecond randomness exhaustion.
+
+        Args:
+            timestamp (int): The current timestamp in milliseconds.
+            randomness_source (RandomnessSource): A callable to get fresh random bytes.
+
+        Returns:
+            bytes: The resolved randomness bytes.
+        """
+        raise NotImplementedError
+
+
+class StrictMonotonicPolicy(BaseMonotonicPolicy):
+    """Strict monotonicity policy.
+
+    Always increments the randomness by 1 if generated within the same millisecond.
+    Raises ValueError on millisecond randomness exhaustion.
+    """
+
+    @override
+    def _on_overflow(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        raise ValueError("Randomness within same millisecond exhausted")
+
+
+class PureRandomPolicy:
+    """Pure random policy.
+
+    Always generates fresh randomness without enforcing any monotonicity constraints.
+    """
+
+    def resolve_randomness(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        return randomness_source(timestamp)
+
+
+class LaxMonotonicPolicy(BaseMonotonicPolicy):
+    """Lax monotonicity policy.
+
+    Increments the randomness by 1 if generated within the same millisecond.
+    If the randomness overflows, it regenerates fresh randomness instead of raising
+    an error or sleeping.
+    """
+
+    @override
+    def _on_overflow(
+        self,
+        timestamp: int,
+        randomness_source: RandomnessSource,
+    ) -> bytes:
+        return randomness_source(timestamp)
+
+
+class ULIDGenerator:
+    """Generator for creating universally unique lexicographically sortable identifiers (ULIDs).
+
+    Samples a clock for the timestamp, sources entropy for the randomness, and enforces a
+    :class:`MonotonicityPolicy` so that identifiers generated within the same millisecond are
+    monotonically increasing. Generation is guarded by a lock and is safe to share across
+    threads.
+
+    Args:
+        clock: A callable returning the current time in milliseconds. Defaults to the system
+            clock.
+        randomness: A callable that, given a timestamp, returns fresh random bytes for the
+            randomness component. Defaults to :func:`os.urandom`.
+        policy: The :class:`MonotonicityPolicy` used to resolve randomness on same-millisecond
+            collisions. Defaults to :class:`StrictMonotonicPolicy`.
+    """
+
+    def __init__(
+        self,
+        clock: Callable[[], int] | None = None,
+        randomness: RandomnessSource | None = None,
+        policy: MonotonicityPolicy | None = None,
+    ) -> None:
+        self.lock = Lock()
+        self.clock = clock or self._default_clock
+        self.randomness_source = randomness or self._default_randomness
+        self.policy = policy or StrictMonotonicPolicy()
+
+    @staticmethod
+    def _default_clock() -> int:
+        return time.time_ns() // constants.NANOSECS_IN_MILLISECS
+
+    @staticmethod
+    def _default_randomness(_timestamp: int) -> bytes:
+        return os.urandom(constants.RANDOMNESS_LEN)
+
+    def _normalize_timestamp(self, value: float | datetime | None = None) -> int:
         if value is None:
-            value = time.time_ns() // constants.NANOSECS_IN_MILLISECS
+            value = self.clock()
+        elif isinstance(value, datetime):
+            value = int(value.timestamp() * constants.MILLISECS_IN_SECS)
         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:
+    def generate(self, timestamp: float | datetime | None = None) -> ULID:
+        """Generate a new :class:`ULID` monotonically.
+
+        Args:
+            timestamp (int, float, datetime, None): Optional timestamp to set on the ULID.
+
+        Returns:
+            ULID: A generated ULID.
+        """
+        ts = self._normalize_timestamp(timestamp)
+
         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)
+            randomness = self.policy.resolve_randomness(
+                ts,
+                self.randomness_source,
+            )
+
+        ts_bytes = int.to_bytes(ts, constants.TIMESTAMP_LEN, "big")
+        return ULID.from_bytes(ts_bytes + randomness)
 
-            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")
+#: The module-level generator used by ``ULID()`` and the ``ULID.from_*`` constructors.
+#: Reassign it to route the default constructors through a custom
+#: :class:`ULIDGenerator` (e.g. a different clock, randomness source, or
+#: :class:`MonotonicityPolicy`)::
+#:
+#:     ulid.default_generator = ULIDGenerator(policy=LaxMonotonicPolicy())
+default_generator = ULIDGenerator()
 
 
 @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
@@ -121,13 +264,18 @@ class ULID:
         ValueError: If the provided value is not a valid encoded ULID.
     """
 
-    def __init__(self, value: bytes | None = None) -> None:
+    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(self.provider.timestamp()).bytes
+        if value is None:
+            self.bytes: bytes = default_generator.generate().bytes
+        else:
+            self.bytes = value
 
     @classmethod
-    @validate_type(datetime)
     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.
@@ -138,10 +286,11 @@ class ULID:
             >>> ULID.from_datetime(datetime.now())
             ULID(01E75QRYCAMM1MKQ9NYMYT6SAV)
         """
-        return cls.from_timestamp(value.timestamp())
+        if not isinstance(value, datetime):
+            raise TypeError("Value has to be of type datetime")
+        return cls.from_bytes(default_generator.generate(value).bytes)
 
     @classmethod
-    @validate_type(int, float)
     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()`)
@@ -153,13 +302,11 @@ class ULID:
             >>> ULID.from_timestamp(time.time())
             ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)
         """
-        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)
+        if not isinstance(value, (int, float)):
+            raise TypeError("Value has to be of type int or float")
+        return cls.from_bytes(default_generator.generate(value).bytes)
 
     @classmethod
-    @validate_type(uuid.UUID)
     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.
@@ -170,30 +317,36 @@ class ULID:
             >>> ULID.from_uuid(uuid4())
             ULID(27Q506DP7E9YNRXA0XVD8Z5YSG)
         """
+        if not isinstance(value, uuid.UUID):
+            raise TypeError("Value has to be of type UUID")
         return cls(value.bytes)
 
     @classmethod
-    @validate_type(bytes)
     def from_bytes(cls, bytes_: bytes) -> Self:
         """Create a new :class:`ULID`-object from sequence of 16 bytes."""
+        if not isinstance(bytes_, bytes):
+            raise TypeError("Value has to be of type bytes")
         return cls(bytes_)
 
     @classmethod
-    @validate_type(str)
     def from_hex(cls, value: str) -> Self:
         """Create a new :class:`ULID`-object from 32 character string of hex values."""
+        if not isinstance(value, str):
+            raise TypeError("Value has to be of type str")
         return cls.from_bytes(bytes.fromhex(value))
 
     @classmethod
-    @validate_type(str)
     def from_str(cls, string: str) -> Self:
         """Create a new :class:`ULID`-object from a 26 char long string representation."""
+        if not isinstance(string, str):
+            raise TypeError("Value has to be of type str")
         return cls(base32.decode(string))
 
     @classmethod
-    @validate_type(int)
     def from_int(cls, value: int) -> Self:
         """Create a new :class:`ULID`-object from an `int`."""
+        if not isinstance(value, int):
+            raise TypeError("Value has to be of type int")
         return cls(int.to_bytes(value, constants.BYTES_LEN, "big"))
 
     @classmethod
@@ -303,9 +456,9 @@ class ULID:
         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 = ulid.to_uuid7()  # Perfect round-trip
+            >>> assert ULID.from_uuid7(uuid7) == ulid
+            >>> uuid7_compliant = ulid.to_uuid7(compliant=True)  # RFC 4122 compliant
             >>> uuid7_compliant.version
             7
         """
@@ -334,21 +487,22 @@ class ULID:
         return uuid.UUID(bytes=uuid_bytes)
 
     @classmethod
-    @validate_type(uuid.UUID)
-    def from_uuidv7(cls, value: uuid.UUID) -> Self:
+    def from_uuid7(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`.
+        preserved, providing perfect round-trip conversion with :meth:`to_uuid7`.
 
         Examples:
 
             >>> uuid7 = uuid.UUID("01936c5e-f4c0-7000-8000-000000000000")
-            >>> ulid = ULID.from_uuidv7(uuid7)
+            >>> ulid = ULID.from_uuid7(uuid7)
             >>> ulid.datetime
             datetime.datetime(2025, 11, 10, ...)
         """
+        if not isinstance(value, uuid.UUID):
+            raise TypeError("Value has to be of type UUID")
         uuid_int = int.from_bytes(value.bytes, byteorder="big")
 
         # Extract timestamp from UUIDv7 layout (always in first 48 bits)

python_ulid-3.2.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-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.1.dist-info/METADATA,sha256=_Ug09XKRumD9YAhF2abhShiUXJLRjfkh8HebBZPQBb8,6591
-python_ulid-3.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-python_ulid-3.2.1.dist-info/entry_points.txt,sha256=9214ghzfSgS8a-TjjlWDF7bI7KSaeewOCBKn5uz7bdU,50
-python_ulid-3.2.1.dist-info/licenses/LICENSE,sha256=DiDPNhW5yUHIqaKowvX0c1c9xWiI0xW4ji8R9N2NJbw,1056
-python_ulid-3.2.1.dist-info/RECORD,,