Identify Beartype Enforce candidates

[strawgate]

Right now we just print warnings with Beartype but we should consider enforcing Beartype on certain methods/classes. For example, on the put/get in basestore.

We should do a review of what would gain the most from enforced beartype

[claude]

Claude finished @strawgate's task —— View job

---

Analysis Complete

Recommendation

Enforce beartype on the core protocol methods (put, get, delete, ttl and their _many variants) in BaseStore and BaseWrapper classes. These are the primary data flow boundaries where type safety is most critical. Keep warnings (O1 strategy) elsewhere to avoid over-constraining implementation flexibility.

The issue mentions enforcing beartype on "put/get in basestore" - this is exactly the right instinct. These methods represent the contract between users and the storage layer, making them ideal enforcement candidates.

---

Findings

Current Beartype Configuration

Global Configuration (all 3 packages):

• Strategy: O1 (constant-time checks with warnings)
• Violation Type: UserWarning (prints warnings, doesn't raise)
• Can be disabled: Via PY_KEY_VALUE_DISABLE_BEARTYPE=true

Selective Opt-Out (bear_spray decorator):

• Used in 2 locations to disable beartype:
  • RedisStore.__init__ - Complex overloaded constructor with Redis client type issues
  • PydanticAdapter.__init__ - Generic type T with Sequence[BaseModel] bound not checkable at runtime

Current State Analysis:

1. ✅ Package-wide beartype is enabled via beartype_this_package() in all 3 package __init__.py files
2. ✅ Using O1 strategy provides lightweight constant-time checks
3. ✅ Warnings-only approach (violation_type=UserWarning) prevents breaking user code
4. ⚠️ No enforcement anywhere - all violations just print warnings
5. ⚠️ Previous issues (e.g., Dynamo Types Issues #84, Fix DynamoDB client type annotations to suppress beartype warnings #85) show beartype warnings in DynamoDB client type mismatches were resolved with TYPE_CHECKING pattern, not enforcement

Critical Enforcement Candidates

Tier 1: High-Priority Core Protocol Methods (BaseStore: base.py:111-276)

The following methods in BaseStore handle the core data contract and should enforce types:

Method	Line	Rationale
get()	111-137	Primary read operation - ensures returned dict[str, Any] | None contract
put()	193-204	Primary write operation - validates value: Mapping[str, Any] and ttl: SupportsFloat | None
delete()	264-268	Primary delete operation - ensures boolean return
ttl()	148-157	Combined read+TTL operation - validates complex return type tuple[dict[str, Any] | None, float | None]
get_many()	140-145	Bulk read - validates list return types
put_many()	226-245	Bulk write - validates keys, values, ttl sequence alignment
delete_many()	271-276	Bulk delete - ensures integer count return
ttl_many()	160-175	Bulk TTL read - validates complex list of tuples

Why these methods?

• They are the public API boundary between user code and storage implementation
• They define the AsyncKeyValueProtocol contract that all stores must honor
• Type violations here cause downstream data corruption or runtime errors
• They process user-provided data (highest risk of type mismatches)

Tier 2: Wrapper Pass-Through Methods (BaseWrapper: wrappers/base.py:14-51)

The BaseWrapper class implements all protocol methods as pass-throughs. Enforcing here provides:

• Defense in depth - catches violations even if store implementation is bypassed
• Wrapper chain validation - ensures type safety across multiple wrapper layers
• Minimal performance impact - wrappers are already adding indirection

Tier 3: Adapter Serialization Boundaries (PydanticAdapter)

Currently using @bear_spray to disable checks. Do NOT enforce here because:

• Generic types like type[T] with Sequence[BaseModel] bound are not runtime-checkable
• Pydantic already provides robust runtime validation
• False positives would add noise without value

Lower-Priority Candidates

Store Implementation Details (likely skip enforcement):

• _get_managed_entry(), _put_managed_entry(), _delete_managed_entry() - Abstract methods that vary by store
• Store-specific clients (Redis, DynamoDB, etc.) - Already using TYPE_CHECKING and @bear_spray for type stub mismatches
• Context manager methods (__aenter__, __aexit__, _close) - Less critical, known types

Why skip?

• Implementation flexibility needed across 15+ store backends
• Already have specific solutions for known issues (e.g., DynamoDB client types via TYPE_CHECKING)
• Lower risk - internal implementation details, not user-facing API

Related Files

File	Relevance	Key Lines
key_value/aio/init.py	Global beartype configuration for async package	9-13
key_value/shared/init.py	Global beartype configuration for shared package	9-13
key_value/shared/type_checking/bear_spray.py	Decorator to disable beartype on specific functions	1-18
key_value/aio/stores/base.py	BaseStore class with all core protocol methods	28-403
key_value/aio/wrappers/base.py	BaseWrapper pass-through implementation	9-52
key_value/aio/protocols/key_value.py	Protocol definition showing expected types	6-181
key_value/aio/stores/redis/store.py	Example of @bear_spray usage on __init__	37-48
key_value/aio/adapters/pydantic/adapter.py	Example of @bear_spray for generic type issues	20-44

---

Detailed Action Plan

For a junior developer to implement enforcement on the recommended methods:

Step 1: Create an "enforce" decorator

Create a new decorator in key_value/shared/type_checking/bear_spray.py for enforcing beartype (raises exceptions instead of warnings):

# Add to bear_spray.py after the existing code

enforce_bear_type_conf = BeartypeConf(strategy=BeartypeStrategy.O1, violation_type=TypeError)
enforce_bear_type = beartype(conf=enforce_bear_type_conf)

def bear_enforce(func: Callable[P, R]) -> Callable[P, R]:
    """Enforce beartype with exceptions instead of warnings."""
    return enforce_bear_type(func)

Why this approach:

• Creates a clear semantic difference between @bear_spray (disable) and @bear_enforce (enforce)
• Uses O1 strategy (constant-time checks) to avoid performance regression
• Raises TypeError instead of UserWarning to actually enforce contracts
• Reusable across all packages

Step 2: Apply enforcement to BaseStore

In key_value/aio/stores/base.py, import and apply the decorator:

# Add to imports at top
from key_value.shared.type_checking.bear_spray import bear_enforce

# Apply decorator to each Tier 1 method
@bear_enforce
@override
async def get(self, key: str, *, collection: str | None = None) -> dict[str, Any] | None:
    # ... existing implementation

@bear_enforce
@override
async def put(self, key: str, value: Mapping[str, Any], *, collection: str | None = None, ttl: SupportsFloat | None = None) -> None:
    # ... existing implementation

@bear_enforce
@override
async def delete(self, key: str, *, collection: str | None = None) -> bool:
    # ... existing implementation

# Continue for: ttl, get_many, put_many, delete_many, ttl_many

Methods to decorate (8 total):

• Line 111: get()
• Line 140: get_many()
• Line 148: ttl()
• Line 160: ttl_many()
• Line 193: put()
• Line 226: put_many()
• Line 264: delete()
• Line 271: delete_many()

Step 3: Apply enforcement to BaseWrapper

In key_value/aio/wrappers/base.py, apply the same decorator:

# Add to imports at top
from key_value.shared.type_checking.bear_spray import bear_enforce

# Apply to all 8 protocol methods
@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)

# Continue for: get_many, ttl, ttl_many, put, put_many, delete, delete_many

Step 4: Regenerate sync library

After modifying the async code:

make codegen

This will automatically:

• Convert async code to sync
• Apply the same decorators to sync versions
• Lint the generated code

Step 5: Test the enforcement

Run the test suite to identify any existing violations:

make test

Expected outcomes:

1. Tests should still pass (existing code should be type-correct)
2. If tests fail with TypeError, that indicates a real type violation that needs fixing
3. Check test output for new errors vs warnings

If violations are found:

• Fix the actual type mismatches in the calling code
• Do NOT add @bear_spray to silence them - that defeats the purpose
• Only use @bear_spray for legitimate cases (like generic types in PydanticAdapter)

Step 6: Update documentation

Update the README.md section about beartype (lines 104-108):

- **Dislike of Bear Bros**: Beartype is used for runtime type checking. Core 
  protocol methods (put/get/delete/ttl) 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.

---

Related Items

Related Issues and Pull Requests

Repository	Issue/PR	Relevance
strawgate/py-key-value	#37: Become a Bear Bro	Original issue to integrate beartype into the project (CLOSED)
strawgate/py-key-value	#35: Add beartype when developing	Initial PR that added beartype with O1/warning strategy to pytest and fixed violations (MERGED)
strawgate/py-key-value	#84: Dynamo Types Issues	Beartype warnings with DynamoDB client type mismatches (CLOSED)
strawgate/py-key-value	#85: Fix DynamoDB client type annotations	Attempted fix using cast() but failed because beartype checks runtime types (CLOSED)
strawgate/py-key-value	#91: Fix dynamodb beartype	Successful fix using TYPE_CHECKING pattern to separate static vs runtime types (MERGED)
strawgate/py-key-value	#94: Switch interface to mapping from dict	Changed protocol parameters from dict to Mapping for better Liskov substitution (CLOSED)
strawgate/py-key-value	#103: refactor: switch input parameters from dict to Mapping	Implementation of #94 (MERGED)

Related Webpages

Name	URL	Relevance
Beartype Documentation: Configuration	https://beartype.readthedocs.io/en/latest/api_roar/#beartype-configuration	Official documentation for BeartypeConf options including strategies and violation types
Beartype Documentation: Strategies	https://beartype.readthedocs.io/en/latest/api_roar/#beartype-strategies	Explains O0 (disabled) vs O1 (constant-time) vs On (linear-time) checking strategies
Beartype Documentation: beartype.claw	https://beartype.readthedocs.io/en/latest/api_claw/	Package-wide beartype via beartype_this_package() as used in this project
Python TYPE_CHECKING Pattern	https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING	Pattern used in DynamoDB store to separate static type hints from runtime types

---

[strawgate]

@claude make a pull request please

[claude]

Claude finished @strawgate's task —— View job • claude/issue-120-20251026-0607 • Create PR ➔

---

Implementation Complete ✅

Successfully implemented beartype enforcement on core protocol methods as recommended in the analysis.

Summary of Changes

1. Created bear_enforce decorator (key-value/key-value-shared/src/key_value/shared/type_checking/bear_spray.py:21-23)

• Uses O1 strategy (constant-time checks) for performance
• Raises TypeError instead of UserWarning for actual enforcement
• Complements existing bear_spray decorator (which disables checks)

2. Applied enforcement to BaseStore (key-value/key-value-aio/src/key_value/aio/stores/base.py)

• get() - Line 111
• get_many() - Line 141
• ttl() - Line 150
• ttl_many() - Line 163
• put() - Line 197
• put_many() - Line 227
• delete() - Line 264
• delete_many() - Line 272

3. Applied enforcement to BaseWrapper (key-value/key-value-aio/src/key_value/aio/wrappers/base.py:15-59)

• All 8 protocol methods now enforce types at the wrapper boundary

4. Regenerated sync library

• Ran codegen with Python 3.10 to maintain consistency
• Both async and sync versions now have enforcement

5. Updated documentation (README.md:104-108)

• Clarified that core methods enforce types (raise TypeError)
• Other code still produces warnings
• Instructions for disabling beartype remain unchanged

Impact

This change strengthens type safety at the critical API boundary between user code and storage implementations. The 8 core protocol methods (get, get_many, ttl, ttl_many, put, put_many, delete, delete_many) now raise TypeError for type violations instead of just printing warnings.

Benefits:

• Catches type errors early at the protocol boundary
• Prevents downstream data corruption from type mismatches
• Maintains backward compatibility (beartype can still be disabled globally)
• Minimal performance impact (O1 constant-time strategy)

Non-breaking change: Existing correct code continues to work. Only code passing incorrect types will now raise errors instead of warnings.

---