python-ulid 3.2.1__tar.gz → 4.0.1__tar.gz

{python_ulid-3.2.1 → python_ulid-4.0.1}/AGENTS.md

@@ -46,6 +46,18 @@ We require full, strict type annotations across the entire codebase.
 
 ---
 
+## 📝 Changelog
+
+We maintain a human-readable changelog in [CHANGELOG.rst](file:///Users/martin.domke/Source/private/ulid/CHANGELOG.rst) following the **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)** conventions.
+
+- **Section headings**: Group entries under the standard headings, in this order: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Omit any section that has no entries.
+- **Removals belong under `Removed`**: Do *not* fold removed or renamed public APIs into `Changed`.
+- **Versioning**: Follow [Semantic Versioning](https://semver.org). A breaking change (e.g. a removed public API) requires a **major** version bump and a `.. warning::` admonition describing the migration path.
+- **Entry format**: Each release has a ``` `X.Y.Z`_ - YYYY-MM-DD ``` heading plus a matching compare link at the bottom of the file (``.. _X.Y.Z: https://github.com/mdomke/python-ulid/compare/PREV...X.Y.Z``).
+- **reStructuredText**: Keep lines within **100 characters** (enforced by `doc8`) and reference public symbols with Sphinx roles such as `:class:` and `:meth:` — the changelog is included into the rendered documentation.
+
+---
+
 ## 🛠️ Verification Workflow
 
 Before completing any task, you **MUST** run the verification commands to ensure no regressions or style issues are introduced.

{python_ulid-3.2.1 → python_ulid-4.0.1}/CHANGELOG.rst

@@ -5,6 +5,51 @@ Changelog
 
 Versions follow `Semantic Versioning <http://www.semver.org>`_
 
+`4.0.1`_ - 2026-07-20
+---------------------
+Changed
+~~~~~~~
+* Renamed ``ULID.from_uuidv7`` to :meth:`.ULID.from_uuid7` for naming symmetry with
+  :meth:`.ULID.to_uuid7`, correcting an inconsistency introduced in 3.2.0.
+
+`4.0.0`_ - 2026-07-20
+---------------------
+
+.. warning::
+
+   **Breaking change:** the ``ValueProvider`` class and the ``ULID.provider`` class attribute
+   have been removed. ULID generation is now handled by the new :class:`.ULIDGenerator` together
+   with pluggable monotonicity policies. To customize generation, construct a
+   :class:`.ULIDGenerator` (optionally with a custom clock, randomness source, or policy) and
+   either call its ``generate()`` method or assign it to ``ulid.default_generator``.
+
+Added
+~~~~~
+* Added a public :class:`.ULIDGenerator` class that encapsulates ULID generation and can be
+  configured with a custom clock, randomness source, and monotonicity policy.
+* Added pluggable monotonicity policies: :class:`.StrictMonotonicPolicy` (the default),
+  :class:`.LaxMonotonicPolicy` and :class:`.PureRandomPolicy`, together with the
+  :class:`.MonotonicityPolicy` protocol and the :class:`.BaseMonotonicPolicy` base class for
+  implementing custom policies.
+* Added a module-level ``ulid.default_generator`` that can be reassigned to route ``ULID()`` and
+  the ``ULID.from_*`` constructors through a custom :class:`.ULIDGenerator`.
+
+Removed
+~~~~~~~
+* Removed the ``ValueProvider`` class and the ``ULID.provider`` attribute in favour of
+  :class:`.ULIDGenerator` and the monotonicity policies. Code that replaced ``ULID.provider`` or
+  subclassed ``ValueProvider`` must migrate to a custom :class:`.ULIDGenerator` assigned to
+  ``ulid.default_generator``.
+* Removed the internal ``validate_type`` decorator. The ``ULID.from_*`` constructors still raise
+  ``TypeError`` for arguments of the wrong type, so runtime behaviour is unchanged.
+
+`3.2.1`_ - 2026-07-17
+---------------------
+Fixed
+~~~~~
+* Corrected the build and publish pipeline and the generated source distribution. This release
+  contains no changes to the library code.
+
 `3.2.0`_ - 2026-07-17
 ---------------------
 Added
@@ -220,6 +265,9 @@ Changed
 * The package now has no external dependencies.
 * The test-coverage has been raised to 100%.
 
+.. _4.0.1: https://github.com/mdomke/python-ulid/compare/4.0.0...4.0.1
+.. _4.0.0: https://github.com/mdomke/python-ulid/compare/3.2.1...4.0.0
+.. _3.2.1: https://github.com/mdomke/python-ulid/compare/3.2.0...3.2.1
 .. _3.2.0: https://github.com/mdomke/python-ulid/compare/3.1.0...3.2.0
 .. _3.1.0: https://github.com/mdomke/python-ulid/compare/3.0.0...3.1.0
 .. _3.0.0: https://github.com/mdomke/python-ulid/compare/2.7.0...3.0.0

python_ulid-4.0.1/CONTEXT.md

@@ -0,0 +1,34 @@
+# Domain Glossary & Context: python-ulid
+
+Welcome to the architectural domain reference for the `python-ulid` project. This document outlines the ubiquitous language, core domain entities, and structural concepts of this implementation.
+
+---
+
+## Core Concepts & Vocabulary
+
+### ULID
+*   **Definition**: A Universally Unique Lexicographically Sortable Identifier.
+*   **Format**: A 128-bit value consisting of:
+    *   **Timestamp**: 48 bits, representing epoch time in milliseconds.
+    *   **Randomness**: 80 bits, representing high-entropy random generation.
+*   **Representation**: Encoded as a 26-character Base32 string.
+*   **Nature**: Act as an immutable, hashable **Value Object**.
+
+### ULIDGenerator
+*   **Definition**: A deep, stateful generator responsible for orchestrating the creation of new `ULID` identifiers.
+*   **Responsibilities**:
+    *   Sampling system or injected clocks for the **Timestamp**.
+    *   Sourcing entropy for the **Randomness**.
+    *   Tracking state and enforcing **Monotonicity** rules.
+    *   Guaranteeing thread-safe generation across execution contexts.
+
+### Monotonicity & Policies
+*   **Definition**: The deterministic ordering property where multiple ULID instances generated within the exact same millisecond resolve their randomness component to prevent sorting collisions.
+*   **MonotonicityPolicy**: An extensible interface (seam) for configuring generator behavior:
+    *   **StrictMonotonicPolicy**: Always increments the randomness by 1 under same-millisecond collisions, raising an overflow error if randomness is exhausted.
+    *   **PureRandomPolicy**: Ignores previous states and always generates fresh random bytes, maximizing security and entropy.
+    *   **LaxMonotonicPolicy**: Increments monotonically, but on same-millisecond randomness exhaustion, regenerates fresh randomness instead of raising an error or sleeping.
+
+### Base32 Engine
+*   **Definition**: Crockford's Base32 translation layer.
+*   **Nature**: Encodes/decodes binary representation using a restricted alphabet of 32 characters (`0123456789ABCDEFGHJKMNPQRSTVWXYZ`), omitting ambiguous characters like `I`, `L`, `O`, and `U` to guarantee maximum readability.

{python_ulid-3.2.1 → python_ulid-4.0.1}/PKG-INFO

@@ -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-3.2.1 → python_ulid-4.0.1}/README.rst

@@ -165,6 +165,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/docs/source/api.rst

@@ -0,0 +1,52 @@
+.. _api:
+
+Developer Interface
+===================
+
+.. module:: ulid
+
+
+ULID
+----
+
+.. autoclass:: ULID
+   :members:
+
+
+Generators
+----------
+
+Every :class:`ULID` is produced by a :class:`ULIDGenerator`. The bare :class:`ULID` constructor
+and the ``ULID.from_*`` factory methods delegate to a shared module-level
+:data:`default_generator`. Create your own :class:`ULIDGenerator` to customize the clock, the
+randomness source, or the :class:`MonotonicityPolicy`.
+
+.. autoclass:: ULIDGenerator
+   :members:
+
+.. autodata:: default_generator
+   :no-value:
+
+
+Monotonicity policies
+---------------------
+
+A monotonicity policy decides how the randomness component is resolved when several ULIDs are
+generated within the same millisecond. Pass an instance to :class:`ULIDGenerator`. Any object
+satisfying the :class:`MonotonicityPolicy` protocol can be used; stateful policies can subclass
+:class:`BaseMonotonicPolicy` and only implement the overflow behaviour.
+
+.. autoclass:: MonotonicityPolicy
+   :members:
+
+.. autoclass:: BaseMonotonicPolicy
+   :members:
+
+.. autoclass:: StrictMonotonicPolicy
+   :members:
+
+.. autoclass:: LaxMonotonicPolicy
+   :members:
+
+.. autoclass:: PureRandomPolicy
+   :members:

{python_ulid-3.2.1 → python_ulid-4.0.1}/docs/source/index.rst

@@ -24,6 +24,10 @@ Release v\ |release| (:ref:`What's new <changelog>`)
    :start-after: monotonic-begin
    :end-before: monotonic-end
 
+.. include:: ../../README.rst
+   :start-after: generators-begin
+   :end-before: generators-end
+
 .. include:: ../../README.rst
    :start-after: cli-begin
    :end-before: cli-end

{python_ulid-3.2.1 → python_ulid-4.0.1}/tests/test_ulid.py

@@ -12,9 +12,14 @@ from freezegun import freeze_time
 from pydantic import BaseModel
 from pydantic import ValidationError
 
+import ulid as ulid_pkg
 from ulid import base32
 from ulid import constants
+from ulid import LaxMonotonicPolicy
+from ulid import PureRandomPolicy
+from ulid import StrictMonotonicPolicy
 from ulid import ULID
+from ulid import ULIDGenerator
 
 
 def utcnow() -> datetime:
@@ -80,10 +85,44 @@ def test_z_real_time_monotonic_sorting() -> None:
 
 @freeze_time()
 def test_same_millisecond_overflow() -> None:
-    ULID.provider.prev_timestamp = ULID.provider.timestamp()
-    ULID.provider.prev_randomness = constants.MAX_RANDOMNESS
+    generator = ULIDGenerator(randomness=lambda _: constants.MAX_RANDOMNESS)
+    generator.generate()
     with pytest.raises(ValueError, match="Randomness within same millisecond exhausted"):
-        ULID()
+        generator.generate()
+
+
+def test_generator_custom_clock_and_randomness() -> None:
+    custom_ts = 123456789
+    custom_rand = b"1234567890"
+    generator = ULIDGenerator(
+        clock=lambda: custom_ts,
+        randomness=lambda _: custom_rand,
+    )
+    ulid = generator.generate()
+    assert ulid.milliseconds == custom_ts
+    assert ulid.bytes[constants.TIMESTAMP_LEN :] == custom_rand
+
+
+def test_generator_state_isolation() -> None:
+    # Ensure two generators do not share state
+    g1 = ULIDGenerator()
+    g2 = ULIDGenerator()
+
+    assert isinstance(g1.policy, StrictMonotonicPolicy)
+    assert isinstance(g2.policy, StrictMonotonicPolicy)
+
+    # Initially, both states should be untouched
+    assert g1.policy.prev_timestamp == constants.MIN_TIMESTAMP
+    assert g2.policy.prev_timestamp == constants.MIN_TIMESTAMP
+
+    # Generating with g1 should update g1's state, but g2 should remain untouched
+    g1.generate()
+    assert g1.policy.prev_timestamp != constants.MIN_TIMESTAMP
+    assert g2.policy.prev_timestamp == constants.MIN_TIMESTAMP
+
+    # Generating with g2 should update g2's state independently
+    g2.generate()
+    assert g2.policy.prev_timestamp != constants.MIN_TIMESTAMP
 
 
 def assert_sorted(seq: list[Any]) -> None:
@@ -122,7 +161,7 @@ def test_idempotency() -> None:
     assert ULID.from_bytes(ulid.bytes) == ulid
     assert ULID.from_str(str(ulid)) == ulid
     assert ULID.from_uuid(ulid.to_uuid()) == ulid
-    assert ULID.from_uuidv7(ulid.to_uuid7(compliant=False)) == ulid
+    assert ULID.from_uuid7(ulid.to_uuid7(compliant=False)) == ulid
     assert ULID.from_int(int(ulid)) == ulid
     assert ULID.from_hex(ulid.hex) == ulid
     assert ULID.parse(ulid) == ulid
@@ -170,7 +209,7 @@ def test_uuid7_perfect_roundtrip() -> None:
     """Test perfect round-trip conversion with compliant=False."""
     ulid = ULID()
     uuid7 = ulid.to_uuid7(compliant=False)
-    ulid_restored = ULID.from_uuidv7(uuid7)
+    ulid_restored = ULID.from_uuid7(uuid7)
     # Perfect round-trip: all 128 bits should be identical
     assert ulid_restored == ulid
     assert ulid_restored.bytes == ulid.bytes
@@ -181,7 +220,7 @@ def test_uuid7_compliant_roundtrip() -> None:
     """Test round-trip with compliant=True preserves timestamp but loses some randomness."""
     ulid = ULID()
     uuid7 = ulid.to_uuid7(compliant=True)
-    ulid_restored = ULID.from_uuidv7(uuid7)
+    ulid_restored = ULID.from_uuid7(uuid7)
     # Timestamp should be perfectly preserved
     assert ulid_restored.milliseconds == ulid.milliseconds
     # Full ULID won't match due to lost randomness in version/variant bits (6 bits lost)
@@ -197,7 +236,7 @@ def test_uuid7_timestamp_preservation() -> None:
     # Test both compliant and non-compliant modes
     for compliant in [False, True]:
         uuid7 = ulid.to_uuid7(compliant=compliant)
-        ulid_from_uuid7 = ULID.from_uuidv7(uuid7)
+        ulid_from_uuid7 = ULID.from_uuid7(uuid7)
 
         # Check timestamp is perfectly preserved (exact millisecond match)
         assert ulid_from_uuid7.milliseconds == ulid.milliseconds
@@ -232,7 +271,7 @@ def test_uuid7_same_millisecond() -> None:
 
     # Perfect round-trip for all
     for ulid, uuid7 in zip(ulids, uuids, strict=True):
-        assert ULID.from_uuidv7(uuid7) == ulid
+        assert ULID.from_uuid7(uuid7) == ulid
 
 
 def test_from_uuid7_with_external_uuid() -> None:
@@ -250,7 +289,7 @@ def test_from_uuid7_with_external_uuid() -> None:
     uuid_int = (timestamp_ms << 80) | (0x7 << 76) | (rand_a << 64) | (0x2 << 62) | rand_b
     uuid7 = uuid.UUID(bytes=uuid_int.to_bytes(16, byteorder="big"))
 
-    ulid = ULID.from_uuidv7(uuid7)
+    ulid = ULID.from_uuid7(uuid7)
 
     # Check timestamp is correctly extracted (should be exact since it's in milliseconds)
     assert ulid.milliseconds == timestamp_ms
@@ -400,3 +439,72 @@ def test_pydantic_protocol() -> None:
     assert {
         "type": "null",
     } in model_json_schema["properties"]["ulid"]["anyOf"]
+
+
+def test_pure_random_policy() -> None:
+    # Ensure PureRandomPolicy generates non-monotonic fresh randomness
+    custom_ts = 123456789
+    rand1 = b"1" * constants.RANDOMNESS_LEN
+    rand2 = b"2" * constants.RANDOMNESS_LEN
+    rands = [rand1, rand2]
+
+    # Iterator to return our mocks
+    iterator = iter(rands)
+    generator = ULIDGenerator(
+        clock=lambda: custom_ts,
+        randomness=lambda _: next(iterator),
+        policy=PureRandomPolicy(),
+    )
+
+    ulid1 = generator.generate()
+    ulid2 = generator.generate()
+
+    assert ulid1.bytes[constants.TIMESTAMP_LEN :] == rand1
+    assert ulid2.bytes[constants.TIMESTAMP_LEN :] == rand2
+
+
+def test_lax_monotonic_policy() -> None:
+    # Under LaxMonotonicPolicy, normal operations increase monotonically
+    custom_ts = 123456789
+    generator = ULIDGenerator(
+        clock=lambda: custom_ts,
+        policy=LaxMonotonicPolicy(),
+    )
+    ulid1 = generator.generate()
+    ulid2 = generator.generate()
+    assert ulid1 < ulid2
+
+    # Mocking same-millisecond overflow
+    # Set the state of the lax policy to MAX_RANDOMNESS
+    assert isinstance(generator.policy, LaxMonotonicPolicy)
+    generator.policy.prev_randomness = constants.MAX_RANDOMNESS
+
+    # Generating again should regenerate fresh randomness instead of raising ValueError or sleeping
+    ulid3 = generator.generate()
+    assert isinstance(ulid3, ULID)
+
+
+def test_default_generator_is_strict() -> None:
+    # The default generator is public and enforces strict monotonicity out of the box
+    assert isinstance(ulid_pkg.default_generator, ULIDGenerator)
+    assert isinstance(ulid_pkg.default_generator.policy, StrictMonotonicPolicy)
+
+
+def test_default_generator_swappable(monkeypatch: pytest.MonkeyPatch) -> None:
+    # Reassigning default_generator routes ULID() and the from_* constructors through it.
+    # monkeypatch restores the original default at teardown, keeping tests isolated.
+    custom_ts = 123456789
+    custom_rand = b"1234567890"
+    custom = ULIDGenerator(clock=lambda: custom_ts, randomness=lambda _: custom_rand)
+    monkeypatch.setattr(ulid_pkg, "default_generator", custom)
+
+    # ULID() draws both timestamp (via the clock) and randomness from the swapped generator
+    now_ulid = ULID()
+    assert now_ulid.milliseconds == custom_ts
+    assert now_ulid.bytes[constants.TIMESTAMP_LEN :] == custom_rand
+
+    # Explicit-timestamp constructors keep their own timestamp but still draw randomness
+    # from the swapped generator (each distinct timestamp yields fresh randomness).
+    assert ULID.from_timestamp(1000).bytes[constants.TIMESTAMP_LEN :] == custom_rand
+    assert ULID.from_datetime(utcnow()).bytes[constants.TIMESTAMP_LEN :] == custom_rand
+    assert ULID.parse(2000).bytes[constants.TIMESTAMP_LEN :] == custom_rand

{python_ulid-3.2.1 → python_ulid-4.0.1}/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/docs/source/api.rst

@@ -1,13 +0,0 @@
-.. _api:
-
-Developer Interface
-===================
-
-.. module:: ulid
-
-
-ULID
-----
-
-.. autoclass:: ULID
-   :members: