fix: resolve all Ty type checker errors

Fix 22 type checking errors by refactoring decorators with ParamSpec,
implementing descriptor protocol for cache decorator, updating port
interfaces, and adding TYPE_CHECKING imports. No cast() usage.

Author: HosseinNejatiJavaremi

archipy/adapters/redis/mocks.py

@@ -14,6 +14,45 @@
 from archipy.configs.config_template import RedisConfig, RedisMode
 
 
+class FakeRedisClusterWrapper(fakeredis.FakeRedis):
+    """Wrapper around FakeRedis that adds cluster-specific methods."""
+
+    def cluster_info(self) -> dict[str, Any]:
+        """Return fake cluster info."""
+        return {
+            "cluster_state": "ok",
+            "cluster_slots_assigned": 16384,
+            "cluster_slots_ok": 16384,
+            "cluster_slots_pfail": 0,
+            "cluster_slots_fail": 0,
+            "cluster_known_nodes": 6,
+            "cluster_size": 3,
+        }
+
+    def cluster_nodes(self) -> str:
+        """Return fake cluster nodes info."""
+        return "fake cluster nodes info"
+
+    def cluster_slots(self) -> list[tuple[int, int, list[str]]]:
+        """Return fake cluster slots info."""
+        slot1: tuple[int, int, list[str]] = (0, 5460, ["127.0.0.1", "7000"])
+        slot2: tuple[int, int, list[str]] = (5461, 10922, ["127.0.0.1", "7001"])
+        slot3: tuple[int, int, list[str]] = (10923, 16383, ["127.0.0.1", "7002"])
+        return [slot1, slot2, slot3]
+
+    def cluster_keyslot(self, key: str) -> int:
+        """Return fake cluster keyslot for a key."""
+        return hash(key) % 16384
+
+    def cluster_countkeysinslot(self, slot: int) -> int:
+        """Return fake count of keys in a slot."""
+        return 0
+
+    def cluster_get_keys_in_slot(self, slot: int, count: int) -> list[str]:
+        """Return fake keys in a slot."""
+        return []
+
+
 class RedisMock(RedisAdapter):
     """A Redis adapter implementation using fakeredis for testing."""
 
@@ -28,29 +67,10 @@ def __init__(self, redis_config: RedisConfig | None = None) -> None:
 
     def _setup_fake_clients(self) -> None:
         """Setup fake Redis clients that simulate different modes."""
-        fake_client: Any = fakeredis.FakeRedis(decode_responses=True)
-
-        # For testing purposes, we simulate different modes
         if self.config.MODE == RedisMode.CLUSTER:
-            # Add cluster-specific mock methods using setattr for dynamic attributes
-            fake_client.cluster_info = lambda: {
-                "cluster_state": "ok",
-                "cluster_slots_assigned": 16384,
-                "cluster_slots_ok": 16384,
-                "cluster_slots_pfail": 0,
-                "cluster_slots_fail": 0,
-                "cluster_known_nodes": 6,
-                "cluster_size": 3,
-            }
-            fake_client.cluster_nodes = lambda: "fake cluster nodes info"
-            fake_client.cluster_slots = lambda: [
-                (0, 5460, ["127.0.0.1", 7000]),
-                (5461, 10922, ["127.0.0.1", 7001]),
-                (10923, 16383, ["127.0.0.1", 7002]),
-            ]
-            fake_client.cluster_keyslot = lambda key: hash(key) % 16384
-            fake_client.cluster_countkeysinslot = lambda slot: 0
-            fake_client.cluster_get_keys_in_slot = lambda slot, count: []
+            fake_client: Redis = FakeRedisClusterWrapper(decode_responses=True)
+        else:
+            fake_client = fakeredis.FakeRedis(decode_responses=True)
 
         self.client = fake_client
         self.read_only_client = fake_client

archipy/adapters/temporal/ports.py

@@ -5,7 +5,7 @@
 the ArchiPy architecture.
 """
 
-from abc import abstractmethod
+from abc import ABC, abstractmethod
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, TypeVar
 
@@ -283,7 +283,7 @@ async def start_worker(
         self,
         task_queue: str,
         workflows: list[type] | None = None,
-        activities: list[object] | None = None,
+        activities: list[Callable[..., Any]] | None = None,
         build_id: str | None = None,
         identity: str | None = None,
         max_concurrent_workflow_tasks: int | None = None,
@@ -295,7 +295,7 @@ async def start_worker(
             task_queue (str): The task queue this worker will poll from.
             workflows (list[type], optional): List of workflow classes to register.
                 Defaults to None.
-            activities (list[object], optional): List of activity instances to register.
+            activities (list[Callable], optional): List of activity callables to register.
                 Defaults to None.
             build_id (str, optional): Build identifier for worker versioning.
                 Defaults to None.
@@ -358,7 +358,21 @@ class WorkflowDescription:
     pass
 
 
-class WorkerHandle:
-    """Type stub for worker handle."""
+class WorkerHandle(ABC):
+    """Base type for worker handle.
 
-    pass
+    This is an abstract base class that concrete implementations should extend.
+    It provides a common interface for worker handle operations.
+    """
+
+    worker_id: str
+    task_queue: str
+
+    @abstractmethod
+    async def stop(self, grace_period: int = 30) -> None:
+        """Stop the worker gracefully.
+
+        Args:
+            grace_period: Maximum time in seconds to wait for graceful shutdown.
+        """
+        ...

archipy/adapters/temporal/worker.py

@@ -7,6 +7,7 @@
 
 import asyncio
 import logging
+from collections.abc import Callable
 from typing import Any, override
 from uuid import uuid4
 
@@ -31,7 +32,7 @@ class WorkerHandle(PortWorkerHandle):
         worker_id (str): Unique identifier for this worker instance.
         task_queue (str): The task queue this worker polls from.
         workflows (list[type]): List of workflow types registered with this worker.
-        activities (list[object]): List of activity instances registered with this worker.
+        activities (list[Callable]): List of activity callables registered with this worker.
         build_id (str | None): Build identifier for worker versioning.
         identity (str | None): Worker identity for debugging and monitoring.
         max_concurrent_workflow_tasks (int): Maximum concurrent workflow tasks.
@@ -44,7 +45,7 @@ def __init__(
         worker_id: str,
         task_queue: str,
         workflows: list[type] | None = None,
-        activities: list[object] | None = None,
+        activities: list[Callable[..., Any]] | None = None,
         build_id: str | None = None,
         identity: str | None = None,
         max_concurrent_workflow_tasks: int | None = None,
@@ -57,7 +58,7 @@ def __init__(
             worker_id (str): Unique identifier for this worker instance.
             task_queue (str): The task queue this worker polls from.
             workflows (list[type], optional): List of workflow types. Defaults to None.
-            activities (list[object], optional): List of activity instances. Defaults to None.
+            activities (list[Callable], optional): List of activity callables. Defaults to None.
             build_id (str, optional): Build identifier for worker versioning. Defaults to None.
             identity (str, optional): Worker identity. Defaults to None.
             max_concurrent_workflow_tasks (int, optional): Maximum concurrent workflow tasks.
@@ -253,7 +254,7 @@ async def start_worker(
         self,
         task_queue: str,
         workflows: list[type] | None = None,
-        activities: list[object] | None = None,
+        activities: list[Callable[..., Any]] | None = None,
         build_id: str | None = None,
         identity: str | None = None,
         max_concurrent_workflow_tasks: int | None = None,
@@ -265,7 +266,7 @@ async def start_worker(
             task_queue (str): The task queue this worker will poll from.
             workflows (list[type], optional): List of workflow classes to register.
                 Defaults to None.
-            activities (list[object], optional): List of activity instances to register.
+            activities (list[Callable], optional): List of activity callables to register.
                 Defaults to None.
             build_id (str, optional): Build identifier for worker versioning.
                 Defaults to None.
@@ -288,13 +289,11 @@ async def start_worker(
 
         try:
             # Create the Temporal worker
-            # Prepare activities list - Worker accepts list of activity instances
-            activities_list: list[Any] = activities if activities is not None else []
             worker = Worker(
                 client,
                 task_queue=task_queue,
                 workflows=workflows or [],
-                activities=activities_list,
+                activities=activities or [],
                 build_id=build_id,
                 identity=worker_identity,
                 max_concurrent_workflow_tasks=max_concurrent_workflow_tasks,
@@ -345,11 +344,11 @@ async def start_worker(
             ) from error
 
     @override
-    async def stop_worker(self, worker_handle: WorkerHandle) -> None:
+    async def stop_worker(self, worker_handle: PortWorkerHandle) -> None:
         """Stop a running Temporal worker.
 
         Args:
-            worker_handle (WorkerHandle): Handle to the worker to stop.
+            worker_handle (PortWorkerHandle): Handle to the worker to stop.
 
         Raises:
             WorkerShutdownError: If the worker fails to stop gracefully.

archipy/helpers/decorators/cache.py

@@ -1,28 +1,76 @@
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, Protocol, TypeVar
-
-T = TypeVar("T")
-R = TypeVar("R")
-P_co = TypeVar("P_co", bound=Callable[..., Any], covariant=True)
-
-
-class ClearableFunction(Protocol[P_co]):
-    """Protocol for a function with a clear_cache method."""
-
-    def __call__(self, *args: object, **kwargs: object) -> object:
-        """Call the function."""
-        ...
+from typing import Any
+
+
+class CachedFunction[**P, R]:
+    """Wrapper class for a cached function with a clear_cache method."""
+
+    def __init__(self, func: Callable[P, R], cache: Any) -> None:
+        """Initialize the cached function wrapper.
+
+        Args:
+            func: The function to wrap.
+            cache: The cache instance to use.
+        """
+        self._func = func
+        self._cache = cache
+        # Preserve function metadata
+        wraps(func)(self)
+
+    def __get__(self, obj: object, objtype: type | None = None) -> CachedFunction[P, R]:
+        """Support instance methods by implementing descriptor protocol."""
+        if obj is None:
+            return self
+        # Return a bound method-like callable
+        from functools import partial
+
+        bound_call = partial(self.__call__, obj)
+        # Create a new CachedFunction instance that wraps the bound method
+        # This ensures clear_cache is available on the bound method
+        bound_cached = CachedFunction(bound_call, self._cache)
+        return bound_cached
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R:
+        """Call the cached function.
+
+        Args:
+            *args: Positional arguments to pass to the function.
+            **kwargs: Keyword arguments to pass to the function.
+
+        Returns:
+            The result of the function call (from cache or fresh).
+        """
+        # Create a key based on function name, args, and kwargs
+        func_name = getattr(self._func, "__name__", "unknown")
+        key_parts = [func_name]
+        # Skip first arg if it looks like 'self' (for instance methods)
+        # We check if args[0] has __dict__ which indicates it's likely an instance
+        if args and hasattr(args[0], "__dict__"):
+            key_parts.extend(str(arg) for arg in args[1:])
+        else:
+            key_parts.extend(str(arg) for arg in args)
+        key_parts.extend(f"{k}:{v}" for k, v in sorted(kwargs.items()))
+        key = ":".join(key_parts)
+
+        # Check if result is in cache
+        if key in self._cache:
+            return self._cache[key]
+
+        # Call the function and cache the result
+        result = self._func(*args, **kwargs)
+        self._cache[key] = result
+        return result
 
     def clear_cache(self) -> None:
         """Clear the cache."""
-        ...
+        self._cache.clear()
 
 
-def ttl_cache_decorator(
+def ttl_cache_decorator[**P, R](
     ttl_seconds: int = 300,
     maxsize: int = 100,
-) -> Callable[[Callable[..., Any]], ClearableFunction[Callable[..., Any]]]:
+) -> Callable[[Callable[P, R]], CachedFunction[P, R]]:
     """Decorator that provides a TTL cache for methods.
 
     Args:
@@ -36,31 +84,7 @@ def ttl_cache_decorator(
 
     cache: TTLCache = TTLCache(maxsize=maxsize, ttl=ttl_seconds)
 
-    def decorator(func: Callable[..., Any]) -> ClearableFunction[Callable[..., Any]]:
-        @wraps(func)
-        def wrapper(*args: object, **kwargs: object) -> object:
-            # Create a key based on function name, args, and kwargs
-            func_name = getattr(func, "__name__", "unknown")
-            key_parts = [func_name]
-            key_parts.extend(str(arg) for arg in args[1:])  # Skip self
-            key_parts.extend(f"{k}:{v}" for k, v in sorted(kwargs.items()))
-            key = ":".join(key_parts)
-
-            # Check if result is in cache
-            if key in cache:
-                return cache[key]
-
-            # Call the function and cache the result
-            result = func(*args, **kwargs)
-            cache[key] = result
-            return result
-
-        # Add a method to clear the cache
-        def clear_cache() -> None:
-            cache.clear()
-
-        # Add clear_cache method to wrapper using setattr for dynamic attribute
-        wrapper.clear_cache = clear_cache
-        return wrapper
+    def decorator(func: Callable[P, R]) -> CachedFunction[P, R]:
+        return CachedFunction(func, cache)
 
     return decorator

archipy/helpers/decorators/deprecation_exception.py

@@ -1,18 +1,22 @@
 from collections.abc import Callable
 from functools import wraps
-from typing import Any, TypeVar
+from typing import Any, ParamSpec, TypeVar
 
 from archipy.models.errors import DeprecationError
 from archipy.models.types.language_type import LanguageType
 
-# Define a type variable for the return type of the decorated function
-F = TypeVar("F", bound=Callable[..., Any])
+# Define type variables for the decorator
+P = ParamSpec("P")
+R = TypeVar("R")
 
 # Define a type variable for the return type of the decorated class
 T = TypeVar("T", bound=type[Any])
 
 
-def method_deprecation_error(operation: str | None = None, lang: LanguageType = LanguageType.EN) -> Callable[[F], F]:
+def method_deprecation_error(
+    operation: str | None = None,
+    lang: LanguageType = LanguageType.EN,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
     """Decorator that raises a DeprecationError when the decorated method is called.
 
     This decorator is used to mark methods as deprecated and immediately prevent
@@ -48,10 +52,13 @@ def old_method(self):
         ```
     """
 
-    def decorator(func: F) -> F:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        # Capture function name before wrapping - use getattr for type safety
+        func_name = getattr(func, "__name__", "unknown")
+
         @wraps(func)
-        def wrapper(*_args: Any, **_kwargs: Any) -> Any:
-            operation_name = operation if operation is not None else func.__name__
+        def wrapper(*_args: P.args, **_kwargs: P.kwargs) -> R:
+            operation_name = operation if operation is not None else func_name
             raise DeprecationError(deprecated_feature=operation_name, lang=lang)
 
         return wrapper