cuid2 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuid2
-Version: 2.2.0
+Version: 2.3.0
 Summary: Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance.
 Keywords: crypt,security,uuid,guid,cuid,cryptography
 Author: Will Gordon
@@ -11,7 +11,6 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -20,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Security :: Cryptography
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Project-URL: repository, https://github.com/gordon-code/cuid2/
 Project-URL: Changelog, https://github.com/gordon-code/cuid2/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/gordon-code/cuid2/issues
@@ -28,7 +27,7 @@ Description-Content-Type: text/markdown
 
 # cuid2
 
-[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/cuid2/)
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/cuid2/)
 [![PyPi](https://img.shields.io/pypi/v/cuid2.svg)](https://pypi.org/project/cuid2/)
 [![PyPi](https://img.shields.io/pypi/dm/cuid2.svg)](https://pypi.org/project/cuid2/)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gordon-code/cuid2/badge)](https://scorecard.dev/viewer/?uri=github.com/gordon-code/cuid2)
@@ -45,7 +44,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 +68,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`) |
@@ -105,6 +104,8 @@ short_cuid: str = create_id(length=10)
 print(is_cuid(my_cuid))  # True
 ```
 
+The CUID2 specification allows lengths 2..32; lengths `1` and `33`–`98` are still accepted in 2.x but emit a `FutureWarning` (shown as `cuid2: warning: ...` by the CLI), and 3.0.0 will reject them with `ValueError`.
+
 > **Tip for Django & ORM defaults:** Pass `default=create_id` directly on model fields (e.g., `models.CharField(max_length=24, default=create_id)`). Because `create_id` is a top-level function backed by a lazy singleton generator, Django `makemigrations` can serialize it directly and `Cuid()` initialization is deferred until the first ID is generated in each worker process.
 
 You can also generate and validate CUIDs directly in the terminal:

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

@@ -1,6 +1,6 @@
 # cuid2
 
-[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/cuid2/)
+[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/cuid2/)
 [![PyPi](https://img.shields.io/pypi/v/cuid2.svg)](https://pypi.org/project/cuid2/)
 [![PyPi](https://img.shields.io/pypi/dm/cuid2.svg)](https://pypi.org/project/cuid2/)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gordon-code/cuid2/badge)](https://scorecard.dev/viewer/?uri=github.com/gordon-code/cuid2)
@@ -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`) |
@@ -77,6 +77,8 @@ short_cuid: str = create_id(length=10)
 print(is_cuid(my_cuid))  # True
 ```
 
+The CUID2 specification allows lengths 2..32; lengths `1` and `33`–`98` are still accepted in 2.x but emit a `FutureWarning` (shown as `cuid2: warning: ...` by the CLI), and 3.0.0 will reject them with `ValueError`.
+
 > **Tip for Django & ORM defaults:** Pass `default=create_id` directly on model fields (e.g., `models.CharField(max_length=24, default=create_id)`). Because `create_id` is a top-level function backed by a lazy singleton generator, Django `makemigrations` can serialize it directly and `Cuid()` initialization is deferred until the first ID is generated in each worker process.
 
 You can also generate and validate CUIDs directly in the terminal:

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

@@ -4,10 +4,10 @@ build-backend = "uv_build"
 
 [project]
 name = "cuid2"
-version = "2.2.0"
+version = "2.3.0"
 description = "Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "MIT"
 license-files = ["LICENSE"]
 classifiers = [
@@ -15,7 +15,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -44,7 +43,7 @@ Changelog = "https://github.com/gordon-code/cuid2/blob/main/CHANGELOG.md"
 Issues = "https://github.com/gordon-code/cuid2/issues"
 
 [project.scripts]
-cuid2 = "cuid2.cli:main"
+cuid2 = "cuid2.cli:_console_main"
 
 [tool.uv]
 default-groups = [
@@ -70,7 +69,7 @@ exclude = ["hack"]
 [tool.ruff]
 line-length = 120
 src = ["src"]
-target-version = "py310"
+target-version = "py311"
 cache-dir = "local/.ruff_cache"
 extend-exclude = ["hack"]
 force-exclude = true
@@ -158,6 +157,7 @@ exclude = [
     "^dist/",
     "^hack/",
 ]
+python_version = "3.11"
 strict = true
 
 [[tool.mypy.overrides]]
@@ -173,6 +173,7 @@ exclude = [
     "dist",
     "hack",
 ]
+pythonVersion = "3.11"
 strict = ["src"]
 
 [dependency-groups]
@@ -182,12 +183,11 @@ lint = [
     "prek==0.5.7",
     "ruff==0.17.0",
     "rumdl==0.3.0",
-    "zizmor==1.31.1; python_version >= '3.11'",
+    "zizmor==1.31.1",
 ]
 test = [
     "coverage[toml]==7.16.2",
-    "hypothesis==6.168.5; python_version < '3.11'",
-    "hypothesis==6.170.5; python_version >= '3.11'",
+    "hypothesis==6.170.5",
     "keepachangelog==2.0.0",
     "pytest==9.1.1",
     "pytest-cov==7.1.0",

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

@@ -4,13 +4,13 @@ build-backend = "uv_build"
 
 [project]
 name = "cuid2"
-version = "2.2.0"
+version = "2.3.0"
 authors = [
     {name = "Will Gordon", email = "dev@gordoncode.dev"},
 ]
 description = "Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance."
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = "MIT"
 license-files = ["LICENSE"]
 classifiers = [
@@ -18,7 +18,6 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -36,7 +35,7 @@ Changelog = "https://github.com/gordon-code/cuid2/blob/main/CHANGELOG.md"
 Issues = "https://github.com/gordon-code/cuid2/issues"
 
 [project.scripts]
-cuid2 = "cuid2.cli:main"
+cuid2 = "cuid2.cli:_console_main"
 
 [tool.uv]
 default-groups = ["build", "lint", "test", "typing"]
@@ -50,12 +49,11 @@ lint = [
     "prek==0.5.7",
     "ruff==0.17.0",
     "rumdl==0.3.0",
-    "zizmor==1.31.1; python_version >= '3.11'",
+    "zizmor==1.31.1",
 ]
 test = [
     "coverage[toml]==7.16.2",
-    "hypothesis==6.168.5; python_version < '3.11'",
-    "hypothesis==6.170.5; python_version >= '3.11'",
+    "hypothesis==6.170.5",
     "keepachangelog==2.0.0",
     "pytest==9.1.1",
     "pytest-cov==7.1.0",
@@ -82,7 +80,7 @@ exclude = ["hack"]
 [tool.ruff]
 line-length = 120
 src = ["src"]
-target-version = "py310"
+target-version = "py311"
 cache-dir = "local/.ruff_cache"
 extend-exclude = ["hack"]
 force-exclude = true
@@ -152,6 +150,7 @@ exclude_also = [
 cache_dir = "local/.mypy_cache"
 files = ["."]
 exclude = ["^build/", "^dist/", "^hack/"]
+python_version = "3.11"
 strict = true
 
 [[tool.mypy.overrides]]
@@ -160,4 +159,5 @@ ignore_missing_imports = true
 
 [tool.pyright]
 exclude = ["build", "dist", "hack"]
+pythonVersion = "3.11"
 strict = ["src"]

{cuid2-2.2.0 → cuid2-2.3.0}/src/cuid2/__main__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-from cuid2.cli import main
+from cuid2.cli import _console_main  # pyright: ignore[reportPrivateUsage]
 
-main()
+_console_main()

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import sys
+import warnings
 from argparse import SUPPRESS, Action, ArgumentParser, ArgumentTypeError, RawDescriptionHelpFormatter
 from contextlib import suppress
 from functools import partial
@@ -15,9 +16,10 @@ 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
+    from typing import TextIO
 
 _SLUG_LENGTH: int = 5
 
@@ -93,6 +95,23 @@ def _fixed_fingerprint(random_generator: Random, *, fingerprint: str) -> str:
     return fingerprint
 
 
+def _show_cli_warning(  # noqa: PLR0913, PLR0917
+    message: Warning | str,
+    category: type[Warning],
+    filename: str,
+    lineno: int,
+    file: TextIO | None = None,
+    line: str | None = None,
+) -> None:
+    # Prints warnings as one clean `cuid2: warning: <message>` stderr line, without the source path or code line.
+    del category, filename, lineno, line
+    stream = file if file is not None else sys.stderr
+    if stream is None:  # No stderr (pythonw or fd 2 closed at startup): drop the warning like the stdlib does.
+        return
+    with suppress(OSError):
+        stream.write(f"cuid2: warning: {message}\n")
+
+
 def _build_parser() -> ArgumentParser:
     parser = ArgumentParser(
         prog="cuid2",
@@ -246,7 +265,16 @@ def main(args: Sequence[str] | None = None) -> None:
     ------
     SystemExit
         Raised with exit code ``0`` or ``1`` in ``--check``/``--validate`` or
-        ``--version``/``--help`` modes, or exit code ``2`` on invalid arguments.
+        ``--version``/``--help`` modes, or exit code ``2`` on invalid arguments,
+        including a length warning that a warnings filter turned into an error.
+
+    Warns
+    -----
+    FutureWarning
+        When generating IDs (not in ``--check``/``--validate`` mode) with a length
+        outside the CUID2 specification range (``MIN_LENGTH``..``BIG_LENGTH``,
+        i.e., 2..32). The ``cuid2`` console script and ``python -m cuid2`` print it
+        as a ``cuid2: warning: ...`` line.
     """
     parser = _build_parser()
     cli_args = parser.parse_args(args)
@@ -259,12 +287,24 @@ def main(args: Sequence[str] | None = None) -> None:
 
     resolved_length = target_length if target_length is not None else DEFAULT_LENGTH
     count = cli_args.count if cli_args.count is not None else 1
-    cuid_generator = (
-        Cuid(length=resolved_length)
-        if cli_args.fingerprint is None
-        else Cuid(
-            length=resolved_length,
-            fingerprint=partial(_fixed_fingerprint, fingerprint=cli_args.fingerprint),
+    try:
+        cuid_generator = (
+            Cuid(length=resolved_length)
+            if cli_args.fingerprint is None
+            else Cuid(
+                length=resolved_length,
+                fingerprint=partial(_fixed_fingerprint, fingerprint=cli_args.fingerprint),
+            )
         )
-    )
+    except FutureWarning as warning:
+        # A warnings filter such as -W error or PYTHONWARNINGS=error turned the length warning into an error.
+        parser.error(str(warning))
     _write_lines(f"{cuid_generator.generate()}\n" for _ in range(count))
+
+
+def _console_main(args: Sequence[str] | None = None) -> None:  # pyright: ignore[reportUnusedFunction]
+    # Entry point for the `cuid2` console script and `python -m cuid2`: prints warnings as `cuid2: warning:` lines.
+    # main() leaves warning delivery to its caller, so programmatic use never touches the global showwarning hook.
+    with warnings.catch_warnings():
+        warnings.showwarning = _show_cli_warning
+        main(args)

{cuid2-2.2.0 → cuid2-2.3.0}/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."""
@@ -72,7 +71,7 @@ def _validate_length(length: int) -> None:
 
     Warns
     -----
-    DeprecationWarning
+    FutureWarning
         If `length` is outside the CUID2 specification range (`MIN_LENGTH`..`BIG_LENGTH`, i.e., 2..32).
     """
     if isinstance(length, bool) or length < 1:
@@ -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,
+            FutureWarning,
+            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
@@ -175,7 +174,7 @@ class Cuid:
             The length parameter is an integer that determines the maximum length of the generated string.
             It has a default value of DEFAULT_LENGTH (24).
             A length value less than 1 or greater than `MAXIMUM_LENGTH` (98 characters) will raise a ValueError.
-            Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a DeprecationWarning.
+            Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a FutureWarning (a ValueError in 3.0.0).
         fingerprint : "FingerprintCallable", default=utils.create_fingerprint
             The "fingerprint" parameter is a callable function that generates a unique identifier. Called again in a
             forked child process; the default includes the child's `os.getpid()`.
@@ -187,27 +186,30 @@ class Cuid:
 
         Warns
         -----
-        DeprecationWarning
+        FutureWarning
             If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
 
         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),
         )
 
@@ -262,7 +272,7 @@ class Cuid:
             The length parameter is an optional integer value that specifies the length of the generated string.
             If it is not provided, the default length value provided during class initialization is used.
             A length value less than 1 or greater than `MAXIMUM_LENGTH` (98 characters) will raise a ValueError.
-            Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a DeprecationWarning.
+            Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a FutureWarning (a ValueError in 3.0.0).
 
         Returns
         -------
@@ -278,23 +288,33 @@ class Cuid:
 
         Warns
         -----
-        DeprecationWarning
+        FutureWarning
             If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
         """
         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)
 
@@ -310,7 +330,7 @@ def create_id(length: int | None = None) -> str:
     length : int, optional
         The optional length of the generated CUID2 string. Defaults to `DEFAULT_LENGTH` (24) when omitted.
         A length value less than 1 or greater than `MAXIMUM_LENGTH` (98 characters) will raise a ValueError.
-        Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a DeprecationWarning.
+        Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a FutureWarning (a ValueError in 3.0.0).
 
     Returns
     -------
@@ -324,10 +344,12 @@ def create_id(length: int | None = None) -> str:
 
     Warns
     -----
-    DeprecationWarning
+    FutureWarning
         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]:
@@ -347,7 +369,7 @@ def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]:
         The length parameter is an integer that determines the maximum length of the generated string.
         It has a default value of DEFAULT_LENGTH (24).
         A length value less than 1 or greater than `MAXIMUM_LENGTH` (98 characters) will raise a ValueError.
-        Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a DeprecationWarning.
+        Lengths outside `MIN_LENGTH`..`BIG_LENGTH` (2..32) emit a FutureWarning (a ValueError in 3.0.0).
 
     Returns
     -------
@@ -361,7 +383,7 @@ def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]:
 
     Warns
     -----
-    DeprecationWarning
+    FutureWarning
         If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
     """
     _validate_length(length)

cuid2-2.3.0/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)