cuid2 2.0.2__tar.gz → 2.0.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cuid2
-Version: 2.0.2
+Version: 2.0.3
 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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "cuid2"
-version = "2.0.2"
+version = "2.0.3"
 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.3}/pyproject.toml.orig

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

cuid2-2.0.3/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.3}/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.3}/src/cuid2/utils.py

@@ -15,7 +15,13 @@ except ImportError:
     from hashlib import sha512  # type: ignore[assignment] # pylint: disable=ungrouped-imports
 
 
-BIG_LENGTH: Final = 32
+# ~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
 
 
 if TYPE_CHECKING:

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"]