cuid2 2.0.2__tar.gz → 2.0.4__tar.gz

{cuid2-2.0.2 → cuid2-2.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuid2
-Version: 2.0.2
+Version: 2.0.4
 Summary: Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance.
 Keywords: crypt,security,uuid,guid,cuid,cryptography
 Author: Will Gordon

{cuid2-2.0.2 → cuid2-2.0.4}/pyproject.toml

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

{cuid2-2.0.2 → cuid2-2.0.4}/pyproject.toml.orig

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

cuid2-2.0.4/src/cuid2/__init__.py

@@ -0,0 +1,21 @@
+"""Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance."""
+
+from .generator import (
+    BIG_LENGTH,
+    DEFAULT_LENGTH,
+    INITIAL_COUNT_MAX,
+    MAXIMUM_LENGTH,
+    MIN_LENGTH,
+    Cuid,
+    cuid_wrapper,
+)
+
+__all__ = [
+    "BIG_LENGTH",
+    "DEFAULT_LENGTH",
+    "INITIAL_COUNT_MAX",
+    "MAXIMUM_LENGTH",
+    "MIN_LENGTH",
+    "Cuid",
+    "cuid_wrapper",
+]

{cuid2-2.0.2 → cuid2-2.0.4}/src/cuid2/generator.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import inspect
 import re
 import time
+import warnings
 from math import floor
 from secrets import SystemRandom
 from typing import TYPE_CHECKING, Callable, Final, Optional, Protocol
 
 from cuid2 import utils
+from cuid2.utils import BIG_LENGTH, DEFAULT_LENGTH, INITIAL_COUNT_MAX, MAXIMUM_LENGTH, MIN_LENGTH
 
 if TYPE_CHECKING:
     from _random import Random
@@ -15,14 +18,47 @@ if TYPE_CHECKING:
         def __call__(self: FingerprintCallable, random_generator: Random) -> str: ...
 
 
-# ~22k 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
-DEFAULT_LENGTH: Final = 24
-MAXIMUM_LENGTH: Final = 98
 _CUID_REGEX: Final[re.Pattern[str]] = re.compile(r"^[a-z][0-9a-z]+\Z")
 
 
+def _validate_length(length: int) -> None:
+    """Validate that the requested CUID length is within supported bounds.
+
+    Parameters
+    ----------
+    length : int
+        The requested CUID length to validate.
+
+    Raises
+    ------
+    ValueError
+        If `length` is a boolean, less than 1, or greater than `MAXIMUM_LENGTH` (98).
+
+    Warns
+    -----
+    DeprecationWarning
+        If `length` is outside the CUID2 specification range (`MIN_LENGTH`..`BIG_LENGTH`, i.e., 2..32).
+    """
+    if isinstance(length, bool) or length < 1:
+        msg = "Length must be at least 1 character."
+        raise ValueError(msg)
+    if length > MAXIMUM_LENGTH:
+        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,
+        )
+
+
 class Cuid:  # pylint: disable=too-few-public-methods
     def __init__(
         self: Cuid,
@@ -46,20 +82,21 @@ class Cuid:  # pylint: disable=too-few-public-methods
             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.
         fingerprint : "FingerprintCallable", default=utils.create_fingerprint
             The "fingerprint" parameter is a callable function that generates a unique identifier.
 
         Raises
         ------
         ValueError
-            If the length parameter is less than 1 or greater than `MAXIMUM_LENGTH` (98 characters).
+            If the length parameter is a boolean, less than 1, or greater than `MAXIMUM_LENGTH` (98 characters).
+
+        Warns
+        -----
+        DeprecationWarning
+            If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
         """
-        if isinstance(length, bool) or length < 1:
-            msg = "Length must be at least 1 character."
-            raise ValueError(msg)
-        if length > MAXIMUM_LENGTH:
-            msg = "Length must never exceed 98 characters."
-            raise ValueError(msg)
+        _validate_length(length)
 
         self._random: Random = random_generator()
         self._counter: Callable[[], int] = counter(floor(self._random.random() * INITIAL_COUNT_MAX))
@@ -75,6 +112,7 @@ class Cuid:  # pylint: disable=too-few-public-methods
             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.
 
         Returns
         -------
@@ -86,15 +124,16 @@ class Cuid:  # pylint: disable=too-few-public-methods
         Raises
         ------
         ValueError
-            If the length parameter is less than 1 or greater than `MAXIMUM_LENGTH` (98 characters).
+            If the length parameter is a boolean, less than 1, or greater than `MAXIMUM_LENGTH` (98 characters).
+
+        Warns
+        -----
+        DeprecationWarning
+            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
-        if isinstance(resolved_length, bool) or resolved_length < 1:
-            msg = "Length must be at least 1 character."
-            raise ValueError(msg)
-        if resolved_length > MAXIMUM_LENGTH:
-            msg = "Length must never exceed 98 characters."
-            raise ValueError(msg)
 
         first_letter: str = utils.create_letter(random_generator=self._random)
 
@@ -145,6 +184,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.
 
     Returns
     -------
@@ -154,7 +194,12 @@ def cuid_wrapper(length: int = DEFAULT_LENGTH) -> Callable[[], str]:
     Raises
     ------
     ValueError
-        If the length parameter is less than 1 or greater than `MAXIMUM_LENGTH` (98 characters).
+        If the length parameter is a boolean, less than 1, or greater than `MAXIMUM_LENGTH` (98 characters).
+
+    Warns
+    -----
+    DeprecationWarning
+        If the length parameter is outside `MIN_LENGTH`..`BIG_LENGTH` (2..32 characters).
     """
     cuid_generator: Cuid = Cuid(length=length)
 

{cuid2-2.0.2 → cuid2-2.0.4}/src/cuid2/utils.py

@@ -3,19 +3,22 @@ from __future__ import annotations
 import os
 import socket
 import string
+from hashlib import sha3_512
 from math import floor
 from typing import TYPE_CHECKING, Callable, Final, Optional
 
-try:
-    from hashlib import sha3_512 as sha512
-except ImportError:
-    import warnings
+# ~22k 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
 
-    warnings.warn("sha3_512 is not available, falling back to sha512, this is less secure!", UserWarning, stacklevel=2)
-    from hashlib import sha512  # type: ignore[assignment] # pylint: disable=ungrouped-imports
-
-
-BIG_LENGTH: Final = 32
+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:
@@ -103,16 +106,11 @@ def create_entropy(random_generator: Random, length: int = 4) -> str:
         msg = "Cannot create entropy without a length >= 1."
         raise ValueError(msg)
 
-    entropy: str = ""
-
-    while len(entropy) < length:
-        entropy += base36_encode(floor(random_generator.random() * 36))
-
-    return entropy
+    return "".join([BASE36_ALPHABET[floor(random_generator.random() * BASE36_RADIX)] for _ in range(length)])
 
 
 def create_hash(data: str = "") -> str:
-    """Creates a hash value for a given string using the SHA-512 algorithm (prefers SHA3) and returns
+    """Creates a hash value for a given string using the SHA3-512 algorithm and returns
     it in base36 encoding format after dropping the first character.
 
     Parameters
@@ -124,10 +122,10 @@ def create_hash(data: str = "") -> str:
     Returns
     -------
     str
-        Base36 encoding of the SHA-512 hash of the input string `data`, with the first character dropped.
+        Base36 encoding of the SHA3-512 hash of the input string `data`, with the first character dropped.
 
     """
-    hashed_value: _Hash = sha512(data.encode())
+    hashed_value: _Hash = 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.
@@ -147,8 +145,7 @@ def create_letter(random_generator: Random) -> str:
     str
         a randomly generated lowercase letter from the English alphabet.
     """
-    alphabet: str = string.ascii_lowercase
-    return alphabet[floor(random_generator.random() * len(alphabet))]
+    return ASCII_LOWERCASE[floor(random_generator.random() * ASCII_LOWERCASE_LEN)]
 
 
 def base36_encode(number: int) -> str:
@@ -175,12 +172,13 @@ def base36_encode(number: int) -> str:
         msg = "Cannot encode negative integers."
         raise ValueError(msg)
 
-    encoded_string: str = ""
-    alphabet: str = string.digits + string.ascii_lowercase
-    alphabet_length: int = len(alphabet)
+    if number == 0:
+        return "0"
 
+    encoded_chars: list[str] = []
     while number != 0:
-        number, mod = divmod(number, alphabet_length)
-        encoded_string = alphabet[mod] + encoded_string
+        number, mod = divmod(number, BASE36_RADIX)
+        encoded_chars.append(BASE36_ALPHABET[mod])
 
-    return encoded_string or "0"
+    encoded_chars.reverse()
+    return "".join(encoded_chars)

cuid2-2.0.2/src/cuid2/__init__.py

@@ -1,5 +0,0 @@
-"""Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance."""
-
-from .generator import DEFAULT_LENGTH, INITIAL_COUNT_MAX, Cuid, cuid_wrapper
-
-__all__ = ["DEFAULT_LENGTH", "INITIAL_COUNT_MAX", "Cuid", "cuid_wrapper"]