feat: Enforce BearType on Store/Wrapper methods (#126)

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

Author: strawgate

README.md

@@ -101,11 +101,12 @@ needs while keeping your framework code clean and backend-agnostic.
 - **No Live Objects**: Even when using the in-memory store, "live" objects are
   never returned from the store. You get a dictionary or a Pydantic model,
   hopefully a copy of what you stored, but never the same instance in memory.
-- **Dislike of Bear Bros**: Beartype is used for runtime type checking, it will
-  report warnings if you get too cheeky with what you're passing around. If you
-  are not a fan of beartype, you can disable it by setting the
-  `PY_KEY_VALUE_DISABLE_BEARTYPE` environment variable to `true` or you can
-  disable the warnings via the warn module.
+- **Dislike of Bear Bros**: Beartype is used for runtime type checking. Core
+  protocol methods in store and wrapper implementations (put/get/delete/ttl
+  and their batch variants) enforce types and will raise TypeError for
+  violations. Other code produces warnings. You can disable all beartype
+  checks by setting `PY_KEY_VALUE_DISABLE_BEARTYPE=true` or suppress warnings
+  via the warnings module.
 
 ## Installation
 

key-value/key-value-aio/src/key_value/aio/stores/base.py

@@ -11,6 +11,7 @@
 
 from key_value.shared.constants import DEFAULT_COLLECTION_NAME
 from key_value.shared.errors import StoreSetupError
+from key_value.shared.type_checking.bear_spray import bear_enforce
 from key_value.shared.utils.managed_entry import ManagedEntry
 from key_value.shared.utils.time_to_live import now, prepare_ttl
 from typing_extensions import Self, override
@@ -134,6 +135,7 @@ async def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) ->
 
         return [await self._get_managed_entry(collection=collection, key=key) for key in keys]
 
+    @bear_enforce
     @override
     async def get(
         self,
@@ -163,6 +165,7 @@ async def get(
 
         return dict(managed_entry.value)
 
+    @bear_enforce
     @override
     async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         collection = collection or self.default_collection
@@ -171,6 +174,7 @@ async def get_many(self, keys: Sequence[str], *, collection: str | None = None)
         entries = await self._get_managed_entries(keys=keys, collection=collection)
         return [dict(entry.value) if entry and not entry.is_expired else None for entry in entries]
 
+    @bear_enforce
     @override
     async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
         collection = collection or self.default_collection
@@ -183,6 +187,7 @@ async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[st
 
         return (dict(managed_entry.value), managed_entry.ttl)
 
+    @bear_enforce
     @override
     async def ttl_many(
         self,
@@ -216,6 +221,7 @@ async def _put_managed_entries(self, *, collection: str, keys: Sequence[str], ma
                 managed_entry=managed_entry,
             )
 
+    @bear_enforce
     @override
     async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         """Store a key-value pair in the specified collection with optional TTL."""
@@ -245,6 +251,7 @@ def _prepare_put_many(
 
         return (keys, values, ttl_for_entries)
 
+    @bear_enforce
     @override
     async def put_many(
         self,
@@ -281,13 +288,15 @@ async def _delete_managed_entries(self, *, keys: Sequence[str], collection: str)
 
         return deleted_count
 
+    @bear_enforce
     @override
     async def delete(self, key: str, *, collection: str | None = None) -> bool:
         collection = collection or self.default_collection
         await self.setup_collection(collection=collection)
 
         return await self._delete_managed_entry(key=key, collection=collection)
 
+    @bear_enforce
     @override
     async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple managed entries by key from the specified collection."""

key-value/key-value-aio/src/key_value/aio/wrappers/base.py

@@ -1,6 +1,7 @@
 from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
+from key_value.shared.type_checking.bear_spray import bear_enforce
 from typing_extensions import override
 
 from key_value.aio.protocols.key_value import AsyncKeyValue
@@ -11,26 +12,32 @@ class BaseWrapper(AsyncKeyValue):
 
     key_value: AsyncKeyValue
 
+    @bear_enforce
     @override
     async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
         return await self.key_value.get(collection=collection, key=key)
 
+    @bear_enforce
     @override
     async def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         return await self.key_value.get_many(collection=collection, keys=keys)
 
+    @bear_enforce
     @override
     async def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
         return await self.key_value.ttl(collection=collection, key=key)
 
+    @bear_enforce
     @override
     async def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         return await self.key_value.ttl_many(collection=collection, keys=keys)
 
+    @bear_enforce
     @override
     async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         return await self.key_value.put(collection=collection, key=key, value=value, ttl=ttl)
 
+    @bear_enforce
     @override
     async def put_many(
         self,
@@ -42,10 +49,12 @@ async def put_many(
     ) -> None:
         return await self.key_value.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
 
+    @bear_enforce
     @override
     async def delete(self, key: str, *, collection: str | None = None) -> bool:
         return await self.key_value.delete(collection=collection, key=key)
 
+    @bear_enforce
     @override
     async def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         return await self.key_value.delete_many(keys=keys, collection=collection)

key-value/key-value-shared-test/src/key_value/shared_test/cases.py

@@ -106,15 +106,8 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
         data={"str_key": {"str_key_2": None, "str_key_3": None}},
         json='{"str_key": {"str_key_2": null, "str_key_3": null}}',
     ),
-    Case(
-        name="nested-dict-keys",
-        data={"str_key": {"str_key_2": {None: "str_value"}}},
-        json='{"str_key": {"str_key_2": {"null": "str_value"}}}',
-        round_trip={"str_key": {"str_key_2": {"null": "str_value"}}},
-    ),
     Case(name="no-implicit-serialization-in-keys", data={"null": "str_value"}, json='{"null": "str_value"}'),
     Case(name="no-implicit-serialization-in-values", data={"str_key": "null"}, json='{"str_key": "null"}'),
-    Case(name="implicit-serialization-of-null-key", data={None: True}, json='{"null": true}', round_trip={"null": True}),  # type: ignore
     case_type="null",
 )
 
@@ -129,16 +122,8 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
         data={"str_key": {"str_key_2": True, "str_key_3": False}},
         json='{"str_key": {"str_key_2": true, "str_key_3": false}}',
     ),
-    Case(
-        name="nested-dict-keys",
-        data={"str_key": {"str_key_2": {True: "str_value"}}},
-        json='{"str_key": {"str_key_2": {"true": "str_value"}}}',
-        round_trip={"str_key": {"str_key_2": {"true": "str_value"}}},
-    ),
     Case(name="no-implicit-serialization-in-keys", data={"true": "str_value"}, json='{"true": "str_value"}'),
     Case(name="no-implicit-serialization-in-values", data={"str_key": "true"}, json='{"str_key": "true"}'),
-    Case(name="implicit-serialization-of-true-key", data={True: True}, json='{"true": true}', round_trip={"true": True}),  # type: ignore
-    Case(name="implicit-serialization-of-false-key", data={False: True}, json='{"false": true}', round_trip={"false": True}),  # type: ignore
     case_type="boolean",
 )
 
@@ -150,7 +135,6 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
     Case(name="int", data={"int_key": 1}, json='{"int_key": 1}'),
     Case(name="value-negative", data={"negative_int_key": -42}, json='{"negative_int_key": -42}'),
     Case(name="large-value", data={"large_int_key": 1 * 10**18}, json=f'{{"large_int_key": {1 * 10**18}}}'),
-    Case(name="key", data={1: True}, json='{"1": true}', round_trip={"1": True}),  # type: ignore
     Case(name="no-implicit-serialization-in-keys", data={"1": "str_value"}, json='{"1": "str_value"}'),
     Case(name="no-implicit-serialization-in-values", data={"str_key": "1"}, json='{"str_key": "1"}'),
     case_type="integer",
@@ -165,7 +149,6 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
     Case(name="large-value", data={"large_float_key": 1.0 * 10**63}, json=f'{{"large_float_key": {1.0 * 10**63}}}'),
     Case(name="no-implicit-serialization-in-keys", data={"1.0": "str_value"}, json='{"1.0": "str_value"}'),
     Case(name="no-implicit-serialization-in-values", data={"str_key": "1.0"}, json='{"str_key": "1.0"}'),
-    Case(name="implicit-serialization-of-float-key", data={1.0: True}, json='{"1.0": true}', round_trip={"1.0": True}),  # type: ignore
     case_type="float",
 )
 
@@ -189,11 +172,8 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
 DATETIME_CASES: PositiveCases = PositiveCases(case_type="datetime")
 
 NEGATIVE_DATETIME_CASES: NegativeCases = NegativeCases(
-    NegativeCase(name="datetime-key", data={FIXED_DATETIME: True}),  # type: ignore
     NegativeCase(name="datetime-value", data={"str_key": FIXED_DATETIME}),
-    NegativeCase(name="date-key", data={FIXED_DATETIME.date(): True}),  # type: ignore
     NegativeCase(name="date-value", data={"str_key": FIXED_DATETIME.date()}),
-    NegativeCase(name="time-key", data={FIXED_TIME: True}),  # type: ignore
     NegativeCase(name="time-value", data={"str_key": FIXED_TIME}),
     case_type="datetime",
 )
@@ -213,7 +193,6 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
 )
 
 NEGATIVE_UUID_CASES: NegativeCases = NegativeCases(
-    NegativeCase(name="key", data={FIXED_UUID: True}),  # type: ignore
     NegativeCase(name="value", data={"str_key": FIXED_UUID}),
     case_type="uuid",
 )
@@ -228,7 +207,6 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
 )
 
 NEGATIVE_BYTES_CASES: NegativeCases = NegativeCases(
-    NegativeCase(name="bytes-key", data={B_HELLO_WORLD: True}),  # type: ignore
     NegativeCase(name="bytes-value", data={"str_key": B_HELLO_WORLD}),
     case_type="bytes",
 )
@@ -246,7 +224,6 @@ def parametrize(cls, cases: list[Self]) -> MarkDecorator:
 )
 
 NEGATIVE_TUPLE_CASES: NegativeCases = NegativeCases(
-    NegativeCase(name="key", data={SAMPLE_TUPLE: True}),  # type: ignore
     NegativeCase(name="value", data={"str_key": SAMPLE_TUPLE}),
     case_type="tuple",
 )

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

@@ -7,6 +7,9 @@
 
 no_bear_type = beartype(conf=no_bear_type_check_conf)
 
+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")
 
@@ -15,4 +18,9 @@ def no_bear_type_check(func: Callable[P, R]) -> Callable[P, R]:
     return no_bear_type(func)
 
 
+def bear_enforce(func: Callable[P, R]) -> Callable[P, R]:
+    """Enforce beartype with exceptions instead of warnings."""
+    return enforce_bear_type(func)
+
+
 bear_spray = no_bear_type_check

key-value/key-value-sync/src/key_value/sync/code_gen/stores/base.py

@@ -14,6 +14,7 @@
 
 from key_value.shared.constants import DEFAULT_COLLECTION_NAME
 from key_value.shared.errors import StoreSetupError
+from key_value.shared.type_checking.bear_spray import bear_enforce
 from key_value.shared.utils.managed_entry import ManagedEntry
 from key_value.shared.utils.time_to_live import now, prepare_ttl
 from typing_extensions import Self, override
@@ -140,6 +141,7 @@ def _get_managed_entries(self, *, collection: str, keys: Sequence[str]) -> list[
 
         return [self._get_managed_entry(collection=collection, key=key) for key in keys]
 
+    @bear_enforce
     @override
     def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
         """Retrieve a value by key from the specified collection.
@@ -164,6 +166,7 @@ def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | No
 
         return dict(managed_entry.value)
 
+    @bear_enforce
     @override
     def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         collection = collection or self.default_collection
@@ -172,6 +175,7 @@ def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> lis
         entries = self._get_managed_entries(keys=keys, collection=collection)
         return [dict(entry.value) if entry and (not entry.is_expired) else None for entry in entries]
 
+    @bear_enforce
     @override
     def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
         collection = collection or self.default_collection
@@ -184,6 +188,7 @@ def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any
 
         return (dict(managed_entry.value), managed_entry.ttl)
 
+    @bear_enforce
     @override
     def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         """Retrieve multiple values and TTLs by key from the specified collection.
@@ -208,6 +213,7 @@ def _put_managed_entries(self, *, collection: str, keys: Sequence[str], managed_
         for key, managed_entry in zip(keys, managed_entries, strict=True):
             self._put_managed_entry(collection=collection, key=key, managed_entry=managed_entry)
 
+    @bear_enforce
     @override
     def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         """Store a key-value pair in the specified collection with optional TTL."""
@@ -233,6 +239,7 @@ def _prepare_put_many(
 
         return (keys, values, ttl_for_entries)
 
+    @bear_enforce
     @override
     def put_many(
         self, keys: Sequence[str], values: Sequence[Mapping[str, Any]], *, collection: str | None = None, ttl: SupportsFloat | None = None
@@ -264,13 +271,15 @@ def _delete_managed_entries(self, *, keys: Sequence[str], collection: str) -> in
 
         return deleted_count
 
+    @bear_enforce
     @override
     def delete(self, key: str, *, collection: str | None = None) -> bool:
         collection = collection or self.default_collection
         self.setup_collection(collection=collection)
 
         return self._delete_managed_entry(key=key, collection=collection)
 
+    @bear_enforce
     @override
     def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         """Delete multiple managed entries by key from the specified collection."""

key-value/key-value-sync/src/key_value/sync/code_gen/wrappers/base.py

@@ -4,6 +4,7 @@
 from collections.abc import Mapping, Sequence
 from typing import Any, SupportsFloat
 
+from key_value.shared.type_checking.bear_spray import bear_enforce
 from typing_extensions import override
 
 from key_value.sync.code_gen.protocols.key_value import KeyValue
@@ -14,36 +15,44 @@ class BaseWrapper(KeyValue):
 
     key_value: KeyValue
 
+    @bear_enforce
     @override
     def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
         return self.key_value.get(collection=collection, key=key)
 
+    @bear_enforce
     @override
     def get_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[dict[str, Any] | None]:
         return self.key_value.get_many(collection=collection, keys=keys)
 
+    @bear_enforce
     @override
     def ttl(self, key: str, *, collection: str | None = None) -> tuple[dict[str, Any] | None, float | None]:
         return self.key_value.ttl(collection=collection, key=key)
 
+    @bear_enforce
     @override
     def ttl_many(self, keys: Sequence[str], *, collection: str | None = None) -> list[tuple[dict[str, Any] | None, float | None]]:
         return self.key_value.ttl_many(collection=collection, keys=keys)
 
+    @bear_enforce
     @override
     def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
         return self.key_value.put(collection=collection, key=key, value=value, ttl=ttl)
 
+    @bear_enforce
     @override
     def put_many(
         self, keys: Sequence[str], values: Sequence[Mapping[str, Any]], *, collection: str | None = None, ttl: SupportsFloat | None = None
     ) -> None:
         return self.key_value.put_many(keys=keys, values=values, collection=collection, ttl=ttl)
 
+    @bear_enforce
     @override
     def delete(self, key: str, *, collection: str | None = None) -> bool:
         return self.key_value.delete(collection=collection, key=key)
 
+    @bear_enforce
     @override
     def delete_many(self, keys: Sequence[str], *, collection: str | None = None) -> int:
         return self.key_value.delete_many(keys=keys, collection=collection)

sonar-project.properties

@@ -0,0 +1,7 @@
+# SonarQube project configuration
+sonar.projectKey=strawgate_py-key-value
+sonar.organization=strawgate
+
+# Exclude code-generated sync library from duplication detection
+# The sync library is automatically generated from the async library
+sonar.cpd.exclusions=**/key-value-sync/**/*.py