feat: Add BearType enforcement to critical utility functions (#188)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: William Easton <strawgate@users.noreply.github.com>

Author: strawgate

key-value/key-value-shared/src/key_value/shared/type_checking/bear_spray.py

@@ -10,8 +10,8 @@
 enforce_bear_type_conf = BeartypeConf(strategy=BeartypeStrategy.O1, violation_type=TypeError)
 enforce_bear_type = beartype(conf=enforce_bear_type_conf)
 
-P = ParamSpec("P")
-R = TypeVar("R")
+P = ParamSpec(name="P")
+R = TypeVar(name="R")
 
 
 def no_bear_type_check(func: Callable[P, R]) -> Callable[P, R]:

key-value/key-value-shared/src/key_value/shared/utils/compound.py

@@ -1,5 +1,7 @@
 from collections.abc import Sequence
 
+from key_value.shared.type_checking.bear_spray import bear_enforce
+
 DEFAULT_COMPOUND_SEPARATOR = "::"
 DEFAULT_PREFIX_SEPARATOR = "__"
 
@@ -29,11 +31,13 @@ def uncompound_strings(strings: Sequence[str], separator: str | None = None) ->
     return [uncompound_string(string=string, separator=separator) for string in strings]
 
 
+@bear_enforce
 def compound_key(collection: str, key: str, separator: str | None = None) -> str:
     separator = separator or DEFAULT_COMPOUND_SEPARATOR
     return compound_string(first=collection, second=key, separator=separator)
 
 
+@bear_enforce
 def uncompound_key(key: str, separator: str | None = None) -> tuple[str, str]:
     separator = separator or DEFAULT_COMPOUND_SEPARATOR
     return uncompound_string(string=key, separator=separator)

key-value/key-value-shared/src/key_value/shared/utils/sanitize.py

@@ -1,6 +1,8 @@
 import hashlib
 from enum import Enum
 
+from key_value.shared.type_checking.bear_spray import bear_enforce
+
 MINIMUM_MAX_LENGTH = 16
 
 DEFAULT_HASH_FRAGMENT_SIZE = 8
@@ -59,6 +61,7 @@ def sanitize_characters_in_string(value: str, allowed_characters: str, replace_w
     return new_value
 
 
+@bear_enforce
 def sanitize_string(
     value: str,
     max_length: int,
@@ -133,6 +136,7 @@ def sanitize_string(
     return sanitized_value
 
 
+@bear_enforce
 def hash_excess_length(value: str, max_length: int) -> str:
     """Hash part of the value if it exceeds the maximum length. This operation
     will truncate the value to the maximum length minus 8 characters and will swap

key-value/key-value-shared/src/key_value/shared/utils/serialization.py

@@ -10,11 +10,13 @@
 from typing import Any, Literal, TypeVar
 
 from key_value.shared.errors import DeserializationError, SerializationError
+from key_value.shared.type_checking.bear_spray import bear_enforce
 from key_value.shared.utils.managed_entry import ManagedEntry, dump_to_json, load_from_json, verify_dict
 
 T = TypeVar("T")
 
 
+@bear_enforce
 def key_must_be(dictionary: dict[str, Any], /, key: str, expected_type: type[T]) -> T | None:
     if key not in dictionary:
         return None
@@ -24,6 +26,7 @@ def key_must_be(dictionary: dict[str, Any], /, key: str, expected_type: type[T])
     return dictionary[key]
 
 
+@bear_enforce
 def parse_datetime_str(value: str) -> datetime:
     try:
         return datetime.fromisoformat(value)

key-value/key-value-shared/src/key_value/shared/utils/time_to_live.py

@@ -1,9 +1,9 @@
 import time
 from datetime import datetime, timedelta, timezone
-from numbers import Real
 from typing import Any, SupportsFloat, overload
 
 from key_value.shared.errors import InvalidTTLError
+from key_value.shared.type_checking.bear_spray import bear_enforce
 
 
 def epoch_to_datetime(epoch: float) -> datetime:
@@ -59,11 +59,18 @@ def prepare_ttl(t: SupportsFloat | None) -> float | None:
     if a bool is provided, an InvalidTTLError will be raised. If the user passes TTL=True, true becomes `1` and the
     entry immediately expires which is likely not what the user intended.
     """
+    try:
+        return _validate_ttl(t=t)
+    except TypeError as e:
+        raise InvalidTTLError(ttl=t, extra_info={"type": type(t).__name__}) from e
+
+
+@bear_enforce
+def _validate_ttl(t: SupportsFloat | None) -> float | None:
     if t is None:
         return None
 
-    # This is not needed by the static type checker but is needed by the runtime type checker
-    if not isinstance(t, Real | SupportsFloat) or isinstance(t, bool):  # pyright: ignore[reportUnnecessaryIsInstance]
+    if isinstance(t, bool):
         raise InvalidTTLError(ttl=t, extra_info={"type": type(t).__name__})
 
     ttl = float(t)

key-value/key-value-shared/tests/utils/test_time_to_live.py

@@ -54,6 +54,7 @@ def test_prepare_ttl(t: Any, expected: int | float | None):
         "bool-false",
     ],
 )
+@pytest.mark.filterwarnings("ignore:Function key_value.shared.utils")  # Ignore BearType warnings here
 def test_prepare_ttl_invalid(t: Any):
     with pytest.raises(InvalidTTLError):
         prepare_ttl(t)