cuid2 2.2.0__tar.gz → 2.2.1__tar.gz

{cuid2-2.2.0 → cuid2-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuid2
-Version: 2.2.0
+Version: 2.2.1
 Summary: Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance.
 Keywords: crypt,security,uuid,guid,cuid,cryptography
 Author: Will Gordon
@@ -45,7 +45,7 @@ by [Parallel Drive](https://github.com/paralleldrive) to Python 3.
 
 ## What is CUID2?
 
-* Secure: It's not feasible to guess the next ID (unguessability derives from the `secrets.SystemRandom` CSPRNG salt; per [RFC 9562 §8](https://www.rfc-editor.org/rfc/rfc9562.html#section-8), IDs are identifiers, not capability tokens or secrets).
+* Secure: It's not feasible to guess the next ID (unguessability derives from the `random.SystemRandom` CSPRNG salt; per [RFC 9562 §8](https://www.rfc-editor.org/rfc/rfc9562.html#section-8), IDs are identifiers, not capability tokens or secrets).
 * Collision resistant: It's extremely unlikely to generate the same ID twice.
 * Horizontally scalable: Generate IDs on multiple machines without coordination.
 * Offline-compatible: Generate IDs without a network connection.
@@ -69,7 +69,7 @@ For more information on the improvements of CUID2 over CUID, see the
   * **123.6-Bit Default Keyspace (`length=24`)**: 1 leading lowercase letter ($26$) followed by 23 base36 characters ($36^{23}$) yields $26 \times 36^{23} \approx \mathbf{1.61 \times 10^{37}}$ possible IDs ($\approx \mathbf{123.6\text{ bits}}$ of entropy)—slightly more than UUIDv4's 122 random bits in a 33% shorter string (24 vs. 36 chars). Reaching a 50% birthday-bound collision probability requires $\sqrt{2 \ln(2) \times 26 \times 36^{23}} \approx \mathbf{4.7 \times 10^{18}}$ IDs (generating **149 million IDs/sec continuously for 1,000 years**).
   * **Up to 165.0 Bits (`BIG_LENGTH = 32`)**: At `length=32`, the keyspace expands to $26 \times 36^{31} \approx \mathbf{4.54 \times 10^{49}}$ IDs ($\approx \mathbf{165.0\text{ bits}}$; 50% collision bound at $\approx 7.9 \times 10^{24}$ IDs).
   * **Histogram De-Biasing**: Because $2^{512} \approx 1.34 \times 10^{154}$ is not an exact power of 36, the most-significant base36 digit of a 512-bit SHA3-512 digest is biased toward low digits; CUID2 drops that leading hash character (`[1:]`) and prepends an independent uniform `[a-z]` letter so every character position has a uniform distribution.
-* **Thread, Pre-Fork, & Container Snapshot Resilience**: `Cuid`, `create_id`, `cuid_wrapper`, and `create_counter` are thread-safe (including on free-threaded Python, tested on `3.14t` and `3.15t`). Each generator records the process ID (`os.getpid()`) that built its state; the first ID generated in a forked child process (`multiprocessing`, Gunicorn, Celery prefork, and uWSGI workers, including uWSGI's default mode, which skips Python's `os.register_at_fork` hooks) rebuilds that state with a fresh lock, RNG state, random initial counter (`INITIAL_COUNT_MAX = 476,782,367`, giving $\approx 25,700$ concurrent hosts before a 50% chance of two hosts starting at the same counter value), and child-PID fingerprints (`os.getpid()`, `socket.gethostname()`, and environment variable keys). For cloned VM/container snapshots where no `fork()` syscall occurs, per-call `secrets.SystemRandom` (`os.urandom`) salt and `time.time_ns()` provide defense-in-depth against state collisions.
+* **Thread, Pre-Fork, & Container Snapshot Resilience**: `Cuid`, `create_id`, `cuid_wrapper`, and `create_counter` are thread-safe (including on free-threaded Python, tested on `3.14t` and `3.15t`). Each generator records the process ID (`os.getpid()`) that built its state; the first ID generated in a forked child process (`multiprocessing`, Gunicorn, Celery prefork, and uWSGI workers, including uWSGI's default mode, which skips Python's `os.register_at_fork` hooks) rebuilds that state with a fresh RNG state, lock (when `random_generator` returns something other than a `random.SystemRandom` instance or `counter` is not the default; the default `random.SystemRandom` and counter are already thread-safe), random initial counter (`INITIAL_COUNT_MAX = 476,782,367`, giving $\approx 25,700$ concurrent hosts before a 50% chance of two hosts starting at the same counter value), and child-PID fingerprints (`os.getpid()`, `socket.gethostname()`, and environment variable keys). For cloned VM/container snapshots where no `fork()` syscall occurs, per-call `random.SystemRandom` (`os.urandom`) salt and `time.time_ns()` provide defense-in-depth against state collisions.
 * **Polyglot ORM Compatibility (Prisma & Drizzle)**: Generates 24-character base36 primary keys compatible with TypeScript/Node.js services using Prisma (`@default(cuid(2))` / `@onCreate(cuid(2))`) or Drizzle (`@paralleldrive/cuid2`), and replaces the deprecated CUIDv1 (`cuid`) format.
 
 | Property | CUID2 (`cuid2`) | UUIDv7 (`uuid.uuid7`) | UUIDv4 (`uuid.uuid4`) | ULID (`python-ulid`) | NanoID (`nanoid`) |

{cuid2-2.2.0 → cuid2-2.2.1}/README.md

@@ -17,7 +17,7 @@ by [Parallel Drive](https://github.com/paralleldrive) to Python 3.
 
 ## What is CUID2?
 
-* Secure: It's not feasible to guess the next ID (unguessability derives from the `secrets.SystemRandom` CSPRNG salt; per [RFC 9562 §8](https://www.rfc-editor.org/rfc/rfc9562.html#section-8), IDs are identifiers, not capability tokens or secrets).
+* Secure: It's not feasible to guess the next ID (unguessability derives from the `random.SystemRandom` CSPRNG salt; per [RFC 9562 §8](https://www.rfc-editor.org/rfc/rfc9562.html#section-8), IDs are identifiers, not capability tokens or secrets).
 * Collision resistant: It's extremely unlikely to generate the same ID twice.
 * Horizontally scalable: Generate IDs on multiple machines without coordination.
 * Offline-compatible: Generate IDs without a network connection.
@@ -41,7 +41,7 @@ For more information on the improvements of CUID2 over CUID, see the
   * **123.6-Bit Default Keyspace (`length=24`)**: 1 leading lowercase letter ($26$) followed by 23 base36 characters ($36^{23}$) yields $26 \times 36^{23} \approx \mathbf{1.61 \times 10^{37}}$ possible IDs ($\approx \mathbf{123.6\text{ bits}}$ of entropy)—slightly more than UUIDv4's 122 random bits in a 33% shorter string (24 vs. 36 chars). Reaching a 50% birthday-bound collision probability requires $\sqrt{2 \ln(2) \times 26 \times 36^{23}} \approx \mathbf{4.7 \times 10^{18}}$ IDs (generating **149 million IDs/sec continuously for 1,000 years**).
   * **Up to 165.0 Bits (`BIG_LENGTH = 32`)**: At `length=32`, the keyspace expands to $26 \times 36^{31} \approx \mathbf{4.54 \times 10^{49}}$ IDs ($\approx \mathbf{165.0\text{ bits}}$; 50% collision bound at $\approx 7.9 \times 10^{24}$ IDs).
   * **Histogram De-Biasing**: Because $2^{512} \approx 1.34 \times 10^{154}$ is not an exact power of 36, the most-significant base36 digit of a 512-bit SHA3-512 digest is biased toward low digits; CUID2 drops that leading hash character (`[1:]`) and prepends an independent uniform `[a-z]` letter so every character position has a uniform distribution.
-* **Thread, Pre-Fork, & Container Snapshot Resilience**: `Cuid`, `create_id`, `cuid_wrapper`, and `create_counter` are thread-safe (including on free-threaded Python, tested on `3.14t` and `3.15t`). Each generator records the process ID (`os.getpid()`) that built its state; the first ID generated in a forked child process (`multiprocessing`, Gunicorn, Celery prefork, and uWSGI workers, including uWSGI's default mode, which skips Python's `os.register_at_fork` hooks) rebuilds that state with a fresh lock, RNG state, random initial counter (`INITIAL_COUNT_MAX = 476,782,367`, giving $\approx 25,700$ concurrent hosts before a 50% chance of two hosts starting at the same counter value), and child-PID fingerprints (`os.getpid()`, `socket.gethostname()`, and environment variable keys). For cloned VM/container snapshots where no `fork()` syscall occurs, per-call `secrets.SystemRandom` (`os.urandom`) salt and `time.time_ns()` provide defense-in-depth against state collisions.
+* **Thread, Pre-Fork, & Container Snapshot Resilience**: `Cuid`, `create_id`, `cuid_wrapper`, and `create_counter` are thread-safe (including on free-threaded Python, tested on `3.14t` and `3.15t`). Each generator records the process ID (`os.getpid()`) that built its state; the first ID generated in a forked child process (`multiprocessing`, Gunicorn, Celery prefork, and uWSGI workers, including uWSGI's default mode, which skips Python's `os.register_at_fork` hooks) rebuilds that state with a fresh RNG state, lock (when `random_generator` returns something other than a `random.SystemRandom` instance or `counter` is not the default; the default `random.SystemRandom` and counter are already thread-safe), random initial counter (`INITIAL_COUNT_MAX = 476,782,367`, giving $\approx 25,700$ concurrent hosts before a 50% chance of two hosts starting at the same counter value), and child-PID fingerprints (`os.getpid()`, `socket.gethostname()`, and environment variable keys). For cloned VM/container snapshots where no `fork()` syscall occurs, per-call `random.SystemRandom` (`os.urandom`) salt and `time.time_ns()` provide defense-in-depth against state collisions.
 * **Polyglot ORM Compatibility (Prisma & Drizzle)**: Generates 24-character base36 primary keys compatible with TypeScript/Node.js services using Prisma (`@default(cuid(2))` / `@onCreate(cuid(2))`) or Drizzle (`@paralleldrive/cuid2`), and replaces the deprecated CUIDv1 (`cuid`) format.
 
 | Property | CUID2 (`cuid2`) | UUIDv7 (`uuid.uuid7`) | UUIDv4 (`uuid.uuid4`) | ULID (`python-ulid`) | NanoID (`nanoid`) |

{cuid2-2.2.0 → cuid2-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "cuid2"
-version = "2.2.0"
+version = "2.2.1"
 description = "Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance."
 readme = "README.md"
 requires-python = ">=3.10"

{cuid2-2.2.0 → cuid2-2.2.1}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "cuid2"
-version = "2.2.0"
+version = "2.2.1"
 authors = [
     {name = "Will Gordon", email = "dev@gordoncode.dev"},
 ]

{cuid2-2.2.0 → cuid2-2.2.1}/src/cuid2/cli.py

@@ -15,9 +15,9 @@ from cuid2.utils import BIG_LENGTH, DEFAULT_LENGTH, MAXIMUM_LENGTH, MIN_LENGTH
 __all__ = ["main"]
 
 if TYPE_CHECKING:
-    from _random import Random
     from argparse import Namespace
     from collections.abc import Iterable, Iterator, Sequence
+    from random import Random
 
 _SLUG_LENGTH: int = 5
 

{cuid2-2.2.0 → cuid2-2.2.1}/src/cuid2/generator.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import inspect
 import os
 import re
 import threading
@@ -11,9 +10,8 @@ import warnings
 from contextlib import suppress
 from copy import copy, deepcopy
 from functools import partial
-from math import floor
-from secrets import SystemRandom
-from typing import TYPE_CHECKING, ClassVar, Final, NamedTuple, Protocol
+from random import SystemRandom  # secrets.SystemRandom re-exports random.SystemRandom (os.urandom CSPRNG)
+from typing import TYPE_CHECKING, NamedTuple
 
 from cuid2 import utils
 from cuid2.utils import BIG_LENGTH, DEFAULT_LENGTH, INITIAL_COUNT_MAX, MAXIMUM_LENGTH, MIN_LENGTH
@@ -31,8 +29,9 @@ __all__ = [
 ]
 
 if TYPE_CHECKING:
-    from _random import Random
     from collections.abc import Callable
+    from random import Random
+    from typing import ClassVar, Final, Protocol
 
     class FingerprintCallable(Protocol):
         """Protocol for fingerprint generator callables."""
@@ -82,16 +81,11 @@ def _validate_length(length: int) -> None:
         msg = "Length must never exceed 98 characters."
         raise ValueError(msg)
     if length < MIN_LENGTH or length > BIG_LENGTH:
-        stacklevel: int = 1
-        frame = inspect.currentframe()
-        while frame is not None and frame.f_code.co_filename == __file__:
-            stacklevel += 1
-            frame = frame.f_back
         warnings.warn(
             f"Length {length} outside the CUID2 specification range ({MIN_LENGTH}..{BIG_LENGTH}) "
             "is deprecated and will raise ValueError in v3.0.0.",
             DeprecationWarning,
-            stacklevel=stacklevel,
+            stacklevel=3,
         )
 
 
@@ -128,8 +122,9 @@ class _GeneratorState(NamedTuple):
     """Per-process generator state, replaced as a whole when a forked child process first generates an ID."""
 
     pid: int
-    lock: threading.RLock
+    lock: threading.RLock | None
     random: Random
+    draw: Callable[[int], tuple[str, str]]
     counter: Callable[[], int]
     fingerprint: str
 
@@ -165,8 +160,12 @@ class Cuid:
         Parameters
         ----------
         random_generator : Callable[[], "Random"], default=SystemRandom
-            Factory callable returning the random number generator instance. Defaults to `secrets.SystemRandom`.
-            Called again in a forked child process (see Notes).
+            Factory callable returning the random number generator instance. Defaults to `random.SystemRandom`
+            (`os.urandom`). Random bits are drawn with the instance's `.getrandbits(k)`. A generator without
+            `.getrandbits(k)`, or whose class defines `.random()` but not `.getrandbits(k)` (such as a `random.Random`
+            subclass overriding only `.random()`, the custom generator pattern described in the `random` module
+            documentation), is drawn from with one `.random()` call per character. Called again in a forked child
+            process (see Notes).
         counter : Callable[[int], Callable[[], int]], default=utils.create_counter
             The `counter` parameter is a callable that creates a counter returning an incremented value each time it
             is called. The `create_counter` function from the `utils` module is used by default. Called again with a
@@ -192,22 +191,25 @@ class Cuid:
 
         Notes
         -----
-        `generate()` may be called concurrently from multiple threads, including on free-threaded Python. Draws from
-        the random generator and counter are serialized per instance by a re-entrant lock, so a signal handler or
-        finalizer that generates an ID on the same thread does not deadlock.
+        `generate()` may be called concurrently from multiple threads, including on free-threaded Python. When
+        `random_generator` returns a `random.SystemRandom` instance and `counter` is the default, both of which are
+        thread-safe on their own, no instance lock is taken. Otherwise, draws from the random generator and counter
+        are serialized per instance by a re-entrant lock, so a signal handler or finalizer that generates an ID on the
+        same thread does not deadlock.
 
         Each instance records the process ID that built its state. When `generate()` first runs in a different
         process, such as any `os.fork()` child (including pre-fork servers that fork without running Python's fork
-        hooks), it builds a new lock, random generator, counter, and fingerprint once, by calling `random_generator`,
-        `counter`, and `fingerprint` again before generating. If `random_generator` returns the same object as before
-        the fork, its `seed()` method is called to reseed it from OS entropy; if it has no `seed()` method or `seed()`
-        raises `NotImplementedError` or `TypeError`, that generator keeps the parent's stream, and IDs still differ by
-        timestamp and, with the default `fingerprint`, by process ID. Fixed-seed factories (such as
-        `functools.partial(random.Random, 42)`) give every process the same stream and are intended for deterministic
-        single-process tests.
+        hooks), it builds a new random generator, counter, fingerprint, and (when one is used) lock once, by
+        calling `random_generator`, `counter`, and `fingerprint` again before generating. If `random_generator`
+        returns the same object as before the fork, its `seed()` method is called to reseed it from OS entropy; if it
+        has no `seed()` method or `seed()` raises `NotImplementedError` or `TypeError`, that generator keeps the
+        parent's stream, and IDs still differ by timestamp and, with the default `fingerprint`, by process ID.
+        Fixed-seed factories (such as `functools.partial(random.Random, 42)`) give every process the same stream and
+        are intended for deterministic single-process tests.
 
         `copy.deepcopy()` returns an independent generator: the three factories are shared by reference, other
-        attributes are deep-copied, and the lock, random generator, counter, and fingerprint are built anew.
+        attributes are deep-copied, and the random generator, counter, fingerprint, and (when one is used) lock are
+        built anew.
         """
         _validate_length(length)
 
@@ -245,11 +247,19 @@ class Cuid:
         if random_generator is previous_random:
             with suppress(AttributeError, NotImplementedError, TypeError):
                 random_generator.seed()
+        # SystemRandom draws are stateless os.urandom reads and create_counter locks internally, so the defaults
+        # need no instance lock; any other generator or counter may keep unsynchronized state.
+        needs_lock: bool = (
+            type(random_generator) is not SystemRandom or self._counter_factory is not utils.create_counter
+        )
         return _GeneratorState(
             pid=os.getpid(),
-            lock=threading.RLock(),
+            lock=threading.RLock() if needs_lock else None,
             random=random_generator,
-            counter=self._counter_factory(floor(random_generator.random() * INITIAL_COUNT_MAX)),
+            draw=utils._letter_and_entropy_source(random_generator),  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            counter=self._counter_factory(
+                utils._create_initial_count(random_generator),  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            ),
             fingerprint=self._fingerprint_factory(random_generator=random_generator),
         )
 
@@ -283,18 +293,28 @@ class Cuid:
         """
         if length is not None:
             _validate_length(length)
-        resolved_length: int = self._length if length is None else length
+        return self._generate(self._length if length is None else length)
 
+    def _generate(self: Cuid, resolved_length: int) -> str:
         state: _GeneratorState = self._current_state()
-        with state.lock:
-            first_letter: str = utils.create_letter(random_generator=state.random)
-            base36_count: str = utils.base36_encode(state.counter())
-            salt: str = utils.create_entropy(length=resolved_length, random_generator=state.random)
-
+        lock: threading.RLock | None = state.lock
+        if lock is None:
+            first_letter, salt = state.draw(resolved_length)
+            count = state.counter()
+        else:
+            with lock:
+                first_letter, salt = state.draw(resolved_length)
+                count = state.counter()
+
+        base36_count: str = utils.base36_encode(count)
         base36_time: str = utils.base36_encode(time.time_ns())
         hash_input: str = base36_time + salt + base36_count + state.fingerprint
 
-        return first_letter + utils.create_hash(hash_input)[1:resolved_length]
+        return first_letter + utils._create_hash_slice(  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            hash_input,
+            1,
+            resolved_length,
+        )
 
     is_cuid: ClassVar[IsCuidCallable] = staticmethod(is_cuid)
 
@@ -328,6 +348,8 @@ def create_id(length: int | None = None) -> str:
         If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
     """
     global _default_generator  # noqa: PLW0603
+    if length is not None:
+        _validate_length(length)
     generator = _default_generator
     if generator is None:
         with _process_lock(os.getpid()):
@@ -335,7 +357,7 @@ def create_id(length: int | None = None) -> str:
             if generator is None:
                 generator = Cuid()
                 _default_generator = generator
-    return generator.generate(length=length)
+    return generator._generate(DEFAULT_LENGTH if length is None else length)  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
 
 
 def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]:

cuid2-2.2.1/src/cuid2/utils.py

@@ -0,0 +1,294 @@
+"""Cryptographic hashing, entropy, counter, fingerprint, and base36 helpers for CUID2."""
+
+from __future__ import annotations
+
+import os
+import threading
+from functools import partial
+from hashlib import sha3_512
+from math import floor
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from random import Random
+    from typing import Final
+
+# ~25.7k hosts before 50% chance of initial counter collision
+# with a remaining counter range of 9.0e+15 in JavaScript.
+INITIAL_COUNT_MAX: Final[int] = 476782367
+MIN_LENGTH: Final[int] = 2
+DEFAULT_LENGTH: Final[int] = 24
+BIG_LENGTH: Final[int] = 32
+MAXIMUM_LENGTH: Final[int] = 98
+
+ASCII_LOWERCASE: Final[str] = "abcdefghijklmnopqrstuvwxyz"
+ASCII_LOWERCASE_LEN: Final[int] = len(ASCII_LOWERCASE)
+BASE36_ALPHABET: Final[str] = "0123456789abcdefghijklmnopqrstuvwxyz"
+BASE36_RADIX: Final[int] = len(BASE36_ALPHABET)
+
+_OVERSAMPLE_BITS: Final[int] = 64
+_COUNTER_DRAW_BITS: Final[int] = INITIAL_COUNT_MAX.bit_length() + _OVERSAMPLE_BITS
+_LETTER_DRAW_BITS: Final[int] = ASCII_LOWERCASE_LEN.bit_length() + _OVERSAMPLE_BITS
+_POWERS_OF_36: Final[tuple[int, ...]] = tuple(BASE36_RADIX**i for i in range(101))
+_HASH_MIN_99_DIGITS: Final[int] = _POWERS_OF_36[98]
+_HASH_MIN_100_DIGITS: Final[int] = _POWERS_OF_36[99]
+
+
+def _uses_random_only(random_generator: Random) -> bool:
+    # Generators without getrandbits(), and random.Random subclasses whose nearest definition is random() rather
+    # than getrandbits() (mirroring random.Random.__init_subclass__), supply their own core generator through
+    # random() alone; they are drawn from with one floor(random() * n) call per character, never through the
+    # inherited getrandbits(), so random() of any resolution keeps its full per-character entropy.
+    if getattr(random_generator, "getrandbits", None) is None:
+        return True
+    for klass in type(random_generator).__mro__:
+        namespace = vars(klass)
+        if "getrandbits" in namespace:
+            return False
+        if "random" in namespace:
+            return True
+    return False
+
+
+def _scale_randbits(bits: int, upper_bound: int, draw_bits: int) -> int:
+    return (bits * upper_bound) >> draw_bits
+
+
+def _create_initial_count(random_generator: Random) -> int:  # pyright: ignore[reportUnusedFunction]
+    if _uses_random_only(random_generator):
+        return floor(random_generator.random() * INITIAL_COUNT_MAX)
+    return _scale_randbits(
+        random_generator.getrandbits(_COUNTER_DRAW_BITS),
+        INITIAL_COUNT_MAX,
+        _COUNTER_DRAW_BITS,
+    )
+
+
+def _entropy_from_scaled(scaled: int, length: int) -> str:
+    alphabet: str = BASE36_ALPHABET
+    chars: list[str] = []
+    for _ in range(length):
+        scaled, mod = divmod(scaled, BASE36_RADIX)
+        chars.append(alphabet[mod])
+    return "".join(chars)
+
+
+def _letter_via_random(random_generator: Random) -> str:
+    return ASCII_LOWERCASE[floor(random_generator.random() * ASCII_LOWERCASE_LEN)]
+
+
+def _entropy_via_random(random_generator: Random, length: int) -> str:
+    return "".join([BASE36_ALPHABET[floor(random_generator.random() * BASE36_RADIX)] for _ in range(length)])
+
+
+def _letter_and_entropy_via_getrandbits(getrandbits: Callable[[int], int], length: int) -> tuple[str, str]:
+    entropy_modulus: int = _POWERS_OF_36[length]
+    modulus: int = ASCII_LOWERCASE_LEN * entropy_modulus
+    draw_bits: int = modulus.bit_length() + _OVERSAMPLE_BITS
+    letter_idx, entropy_scaled = divmod(_scale_randbits(getrandbits(draw_bits), modulus, draw_bits), entropy_modulus)
+    return ASCII_LOWERCASE[letter_idx], _entropy_from_scaled(entropy_scaled, length)
+
+
+def _letter_and_entropy_via_random(random_generator: Random, length: int) -> tuple[str, str]:
+    return _letter_via_random(random_generator), _entropy_via_random(random_generator, length)
+
+
+def _letter_and_entropy_source(  # pyright: ignore[reportUnusedFunction]
+    random_generator: Random,
+) -> Callable[[int], tuple[str, str]]:
+    if _uses_random_only(random_generator):
+        return partial(_letter_and_entropy_via_random, random_generator)
+    return partial(_letter_and_entropy_via_getrandbits, random_generator.getrandbits)
+
+
+def _create_hash_slice(data: str, start: int, stop: int) -> str:
+    hashed_int: int = int.from_bytes(sha3_512(data.encode()).digest(), byteorder="big")
+    raw_start: int = start + 1
+    raw_stop: int = stop + 1
+    if hashed_int >= _HASH_MIN_99_DIGITS and stop < MAXIMUM_LENGTH:
+        total_digits: int = 100 if hashed_int >= _HASH_MIN_100_DIGITS else 99
+        return base36_encode(hashed_int // _POWERS_OF_36[total_digits - raw_stop])[raw_start:raw_stop]
+    return base36_encode(hashed_int)[raw_start:raw_stop]
+
+
+def create_counter(count: int) -> Callable[[], int]:
+    """Create a thread-safe counter that returns an incremented value each time it is called.
+
+    Parameters
+    ----------
+    count : int
+        Initial count value for the counter.
+
+    Returns
+    -------
+    Callable[[], int]
+        Closure function `counter` that takes no arguments and returns an integer. The closure function keeps track
+        of a count variable that is initialized with the value passed as an argument to `create_counter`. Each time
+        the closure function is called, it atomically increments the count variable under a lock and returns its
+        new value.
+    """
+    lock = threading.RLock()
+
+    def counter() -> int:
+        nonlocal count
+        with lock:
+            count += 1
+            return count
+
+    return counter
+
+
+def create_fingerprint(random_generator: Random, fingerprint_data: str | None = "") -> str:
+    """Create a host/process fingerprint combined with random entropy and hashed.
+
+    Parameters
+    ----------
+    random_generator : random.Random
+        Random number generator used to generate fingerprint entropy. Its `.getrandbits(k)` is used; a generator
+        without `.getrandbits(k)`, or whose class defines `.random()` but not `.getrandbits(k)` (such as a
+        `random.Random` subclass overriding only `.random()`), is drawn from with one `.random()` call per character.
+    fingerprint_data : str, optional
+        An optional parameter that contains data to be included in the fingerprint.
+        If it is not provided, the function combines process ID, hostname, and environment variables
+
+    Returns
+    -------
+    str
+        The hashed value of the input `fingerprint_data` or default value concatenated with a randomly generated
+        entropy string.
+        The length of the returned string is trimmed to the constant `BIG_LENGTH` (32 characters).
+    """
+    if not fingerprint_data:
+        import socket  # noqa: PLC0415
+
+        process_id: int = os.getpid()
+        hostname: str = socket.gethostname()
+        env_variables: str = "".join(os.environ.keys())
+
+        fingerprint_data = str(process_id) + hostname + env_variables
+
+    fingerprint: str = str(fingerprint_data) + create_entropy(random_generator, BIG_LENGTH)
+    return _create_hash_slice(fingerprint, 0, BIG_LENGTH)
+
+
+def create_entropy(random_generator: Random, length: int = 4) -> str:
+    """Create a random string of specified length using base36 encoding.
+
+    Parameters
+    ----------
+    random_generator : random.Random
+        Random number generator used to generate a random string. Its `.getrandbits(k)` is used; a generator
+        without `.getrandbits(k)`, or whose class defines `.random()` but not `.getrandbits(k)` (such as a
+        `random.Random` subclass overriding only `.random()`), is drawn from with one `.random()` call per character.
+    length : int, default=4
+        The length parameter is an integer that specifies the length of the entropy string to be generated.
+        The default value is 4, but it can be set to any positive integer value.
+
+    Returns
+    -------
+    str
+        Random characters encoded as a base36 string. The length of the string is determined by
+        the `length` parameter passed to the function.
+
+    Raises
+    ------
+    ValueError
+        If the input integer is less than 1.
+    """
+    if length < 1:
+        msg = "Cannot create entropy without a length >= 1."
+        raise ValueError(msg)
+
+    if _uses_random_only(random_generator):
+        return _entropy_via_random(random_generator, length)
+
+    modulus: int = _POWERS_OF_36[length] if length < len(_POWERS_OF_36) else BASE36_RADIX**length
+    draw_bits: int = modulus.bit_length() + _OVERSAMPLE_BITS
+    scaled: int = _scale_randbits(random_generator.getrandbits(draw_bits), modulus, draw_bits)
+    return _entropy_from_scaled(scaled, length)
+
+
+def create_hash(data: str = "") -> str:
+    """Create a base36-encoded SHA3-512 hash of `data` with the leading character dropped.
+
+    Parameters
+    ----------
+    data : str, default=""
+        Data to be hashed. It is an optional parameter with a default value of an empty string.
+        If no value is provided for `data`, an empty string will be hashed.
+
+    Returns
+    -------
+    str
+        Base36 encoding of the SHA3-512 hash of the input string `data`, with the first character dropped.
+
+    """
+    hashed_value = sha3_512(data.encode())
+    hashed_int: int = int.from_bytes(hashed_value.digest(), byteorder="big")
+
+    # Drop the first character because it will bias the histogram to the left.
+    return base36_encode(hashed_int)[1:]
+
+
+def create_letter(random_generator: Random) -> str:
+    """Generate a random lowercase ASCII letter using the given random number generator.
+
+    Parameters
+    ----------
+    random_generator : random.Random
+        Random number generator used to generate a random letter. Its `.getrandbits(k)` is used; a generator
+        without `.getrandbits(k)`, or whose class defines `.random()` but not `.getrandbits(k)` (such as a
+        `random.Random` subclass overriding only `.random()`), is drawn from with one `.random()` call.
+
+    Returns
+    -------
+    str
+        a randomly generated lowercase letter from the English alphabet.
+    """
+    if _uses_random_only(random_generator):
+        return _letter_via_random(random_generator)
+    return ASCII_LOWERCASE[
+        _scale_randbits(
+            random_generator.getrandbits(_LETTER_DRAW_BITS),
+            ASCII_LOWERCASE_LEN,
+            _LETTER_DRAW_BITS,
+        )
+    ]
+
+
+def base36_encode(number: int) -> str:
+    """Encode a non-negative integer into a base36 string.
+
+    Parameters
+    ----------
+    number : int
+        Integer to be encoded as a base36 string.
+
+    Returns
+    -------
+    str
+        A string that represents the base36 encoded input integer.
+        If the input integer is negative, a ValueError is raised.
+        If the input integer is 0, the function returns the string "0".
+
+    Raises
+    ------
+    ValueError
+        If the input integer is negative.
+    """
+    if number < 0:
+        msg = "Cannot encode negative integers."
+        raise ValueError(msg)
+
+    if number == 0:
+        return "0"
+
+    alphabet: str = BASE36_ALPHABET
+    encoded_chars: list[str] = []
+    while number != 0:
+        number, mod = divmod(number, BASE36_RADIX)
+        encoded_chars.append(alphabet[mod])
+
+    encoded_chars.reverse()
+    return "".join(encoded_chars)

cuid2-2.2.0/src/cuid2/utils.py

@@ -1,188 +0,0 @@
-"""Cryptographic hashing, entropy, counter, fingerprint, and base36 helpers for CUID2."""
-
-from __future__ import annotations
-
-import os
-import socket
-import string
-import threading
-from hashlib import sha3_512
-from math import floor
-from typing import TYPE_CHECKING, Final
-
-# ~25.7k hosts before 50% chance of initial counter collision
-# with a remaining counter range of 9.0e+15 in JavaScript.
-INITIAL_COUNT_MAX: Final[int] = 476782367
-MIN_LENGTH: Final[int] = 2
-DEFAULT_LENGTH: Final[int] = 24
-BIG_LENGTH: Final[int] = 32
-MAXIMUM_LENGTH: Final[int] = 98
-
-ASCII_LOWERCASE: Final[str] = string.ascii_lowercase
-ASCII_LOWERCASE_LEN: Final[int] = len(ASCII_LOWERCASE)
-BASE36_ALPHABET: Final[str] = string.digits + string.ascii_lowercase
-BASE36_RADIX: Final[int] = len(BASE36_ALPHABET)
-
-
-if TYPE_CHECKING:
-    from _random import Random
-    from collections.abc import Callable
-
-
-def create_counter(count: int) -> Callable[[], int]:
-    """Create a thread-safe counter that returns an incremented value each time it is called.
-
-    Parameters
-    ----------
-    count : int
-        Initial count value for the counter.
-
-    Returns
-    -------
-    Callable[[], int]
-        Closure function `counter` that takes no arguments and returns an integer. The closure function keeps track
-        of a count variable that is initialized with the value passed as an argument to `create_counter`. Each time
-        the closure function is called, it atomically increments the count variable under a lock and returns its
-        new value.
-    """
-    lock = threading.RLock()
-
-    def counter() -> int:
-        nonlocal count
-        with lock:
-            count += 1
-            return count
-
-    return counter
-
-
-def create_fingerprint(random_generator: Random, fingerprint_data: str | None = "") -> str:
-    """Create a host/process fingerprint combined with random entropy and hashed.
-
-    Parameters
-    ----------
-    random_generator : "Random"
-        Used as the base generator to generate some entropy.
-    fingerprint_data : str, optional
-        An optional parameter that contains data to be included in the fingerprint.
-        If it is not provided, the function combines process ID, hostname, and environment variables
-
-    Returns
-    -------
-    str
-        The hashed value of the input `fingerprint_data` or default value concatenated with a randomly generated
-        entropy string.
-        The length of the returned string is trimmed to the constant `BIG_LENGTH` (32 characters).
-    """
-    if not fingerprint_data:
-        process_id: int = os.getpid()
-        hostname: str = socket.gethostname()
-        env_variables: str = "".join(os.environ.keys())
-
-        fingerprint_data = str(process_id) + hostname + env_variables
-
-    fingerprint: str = str(fingerprint_data) + create_entropy(random_generator, BIG_LENGTH)
-    return create_hash(fingerprint)[0:BIG_LENGTH]
-
-
-def create_entropy(random_generator: Random, length: int = 4) -> str:
-    """Create a random string of specified length using base36 encoding.
-
-    Parameters
-    ----------
-    random_generator : "Random"
-        Used as the base generator to generate a random string.
-    length : int, default=4
-        The length parameter is an integer that specifies the length of the entropy string to be generated.
-        The default value is 4, but it can be set to any positive integer value.
-
-    Returns
-    -------
-    str
-        Random characters encoded as a base36 string. The length of the string is determined by
-        the `length` parameter passed to the function.
-
-    Raises
-    ------
-    ValueError
-        If the input integer is less than 1.
-    """
-    if length < 1:
-        msg = "Cannot create entropy without a length >= 1."
-        raise ValueError(msg)
-
-    return "".join([BASE36_ALPHABET[floor(random_generator.random() * BASE36_RADIX)] for _ in range(length)])
-
-
-def create_hash(data: str = "") -> str:
-    """Create a base36-encoded SHA3-512 hash of `data` with the leading character dropped.
-
-    Parameters
-    ----------
-    data : str, default=""
-        Data to be hashed. It is an optional parameter with a default value of an empty string.
-        If no value is provided for `data`, an empty string will be hashed.
-
-    Returns
-    -------
-    str
-        Base36 encoding of the SHA3-512 hash of the input string `data`, with the first character dropped.
-
-    """
-    hashed_value = sha3_512(data.encode())
-    hashed_int: int = int.from_bytes(hashed_value.digest(), byteorder="big")
-
-    # Drop the first character because it will bias the histogram to the left.
-    return base36_encode(hashed_int)[1:]
-
-
-def create_letter(random_generator: Random) -> str:
-    """Generate a random lowercase ASCII letter using the given random number generator.
-
-    Parameters
-    ----------
-    random_generator : "Random"
-        Used as the base generator to generate a random letter.
-
-    Returns
-    -------
-    str
-        a randomly generated lowercase letter from the English alphabet.
-    """
-    return ASCII_LOWERCASE[floor(random_generator.random() * ASCII_LOWERCASE_LEN)]
-
-
-def base36_encode(number: int) -> str:
-    """Encode a non-negative integer into a base36 string.
-
-    Parameters
-    ----------
-    number : int
-        Integer to be encoded as a base36 string.
-
-    Returns
-    -------
-    str
-        A string that represents the base36 encoded input integer.
-        If the input integer is negative, a ValueError is raised.
-        If the input integer is 0, the function returns the string "0".
-
-    Raises
-    ------
-    ValueError
-        If the input integer is negative.
-    """
-    if number < 0:
-        msg = "Cannot encode negative integers."
-        raise ValueError(msg)
-
-    if number == 0:
-        return "0"
-
-    encoded_chars: list[str] = []
-    while number != 0:
-        number, mod = divmod(number, BASE36_RADIX)
-        encoded_chars.append(BASE36_ALPHABET[mod])
-
-    encoded_chars.reverse()
-    return "".join(encoded_chars)