fix: resolve ruff and mypy issues across configs, models, and decorators

- Update to Python 3.13 generic syntax (UP046, UP047)
- Fix type annotations and imports (assignment, no-untyped-def)
- Add missing error classes (DeadlineExceededError, DeprecationError)
- Configure pyproject.toml with proper lint ignores and mypy overrides
- Ensure all behave tests pass (17 features, 176 scenarios, 856 steps)

Author: HosseinNejatiJavaremi

archipy/helpers/decorators/deprecation_exception.py

@@ -52,7 +52,7 @@ def decorator(func: F) -> F:
         @wraps(func)
         def wrapper(*_args: Any, **_kwargs: Any) -> Any:
             operation_name = operation if operation is not None else func.__name__
-            raise DeprecationError(operation=operation_name, lang=lang)
+            raise DeprecationError(deprecated_feature=operation_name, lang=lang)
 
         return cast(F, wrapper)
 
@@ -93,7 +93,7 @@ def __init__(self):
     def decorator(cls: T) -> T:
         def new_init(_self: Any, *_args: Any, **_kwargs: Any) -> None:
             operation_name = operation if operation is not None else cls.__name__
-            raise DeprecationError(operation=operation_name, lang=lang)
+            raise DeprecationError(deprecated_feature=operation_name, lang=lang)
 
         cls.__init__ = new_init
         return cls

archipy/helpers/decorators/sqlalchemy_atomic.py

@@ -7,7 +7,7 @@
 import logging
 from collections.abc import Callable
 from functools import partial, wraps
-from typing import Any, TypeVar
+from typing import Any, TypeVar, cast
 
 from sqlalchemy.exc import (
     IntegrityError,
@@ -179,7 +179,7 @@ def get_registry() -> type[SessionManagerRegistry]:
 
             module_path, class_name = ATOMIC_BLOCK_CONFIGS[db_type]["registry"].rsplit(".", 1)
             module = importlib.import_module(module_path)
-            return getattr(module, class_name)
+            return cast(type[SessionManagerRegistry], getattr(module, class_name))
         except (ImportError, AttributeError) as e:
             raise DatabaseConfigurationError(
                 database=db_type,
@@ -231,8 +231,9 @@ async def async_wrapper(*args: Any, **kwargs: Any) -> R:
                         if not is_nested:
                             await session.commit()
                         return result
-                    async with session.begin():
-                        return await func(*args, **kwargs)
+                    else:
+                        async with session.begin():
+                            return await func(*args, **kwargs)
                 except Exception as exception:
                     await session.rollback()
                     _handle_db_exception(exception, db_type, func.__name__)
@@ -278,8 +279,9 @@ def sync_wrapper(*args: Any, **kwargs: Any) -> R:
                         if not is_nested:
                             session.commit()
                         return result
-                    with session.begin():
-                        return func(*args, **kwargs)
+                    else:
+                        with session.begin():
+                            return func(*args, **kwargs)
                 except Exception as exception:
                     session.rollback()
                     _handle_db_exception(exception, db_type, func.__name__)

archipy/helpers/decorators/timing.py

@@ -1,13 +1,10 @@
 import logging
 import time
 from collections.abc import Callable
-from typing import Any, TypeVar, cast
+from typing import Any, cast
 
-# Define a type variable for the return type of the decorated function
-F = TypeVar("F", bound=Callable[..., Any])
 
-
-def timing_decorator(func: F) -> F:
+def timing_decorator[F: Callable[..., Any]](func: F) -> F:
     """A decorator that measures the execution time of a function and logs it if the logging level is DEBUG.
 
     Args:

archipy/models/errors/__init__.py

@@ -77,7 +77,9 @@
 from archipy.models.errors.system_errors import (
     AbortedError,
     ConfigurationError,
+    DeadlineExceededError,
     DeadlockDetectedError,
+    DeprecationError,
     InternalError,
     UnavailableError,
     UnknownError,
@@ -124,7 +126,9 @@
     "DatabaseSerializationError",
     "DatabaseTimeoutError",
     "DatabaseTransactionError",
+    "DeadlineExceededError",
     "DeadlockDetectedError",
+    "DeprecationError",
     "FailedPreconditionError",
     "FileTooLargeError",
     "GatewayTimeoutError",

archipy/models/errors/system_errors.py

@@ -1,30 +1,24 @@
+from typing import Any, ClassVar
+
 from archipy.models.dtos.error_dto import ErrorDetailDTO
 from archipy.models.errors.base_error import BaseError
 from archipy.models.types.error_message_types import ErrorMessageType
 from archipy.models.types.language_type import LanguageType
 
 
 class InternalError(BaseError):
-    """Exception raised for unexpected internal errors."""
-
-    def __init__(
-        self,
-        lang: LanguageType | None = None,
-        error: ErrorDetailDTO = ErrorMessageType.INTERNAL_ERROR.value,
-        additional_data: dict | None = None,
-    ) -> None:
-        super().__init__(error, lang, additional_data)
+    """Represents an internal server error.
 
-
-class UnknownError(BaseError):
-    """Exception raised for unknown or unexpected error conditions."""
+    This error is typically used when an unexpected condition is encountered
+    that prevents the server from fulfilling the request.
+    """
 
     def __init__(
         self,
         error_code: str | None = None,
         lang: LanguageType | None = None,
-        error: ErrorDetailDTO = ErrorMessageType.UNKNOWN_ERROR.value,
-        additional_data: dict | None = None,
+        error: ErrorDetailDTO = ErrorMessageType.INTERNAL_ERROR.value,
+        additional_data: dict[str, Any] | None = None,
     ) -> None:
         data = {}
         if error_code:
@@ -34,16 +28,20 @@ def __init__(
         super().__init__(error, lang, data if data else None)
 
 
-class AbortedError(BaseError):
-    """Exception raised when an operation is aborted."""
+class ConfigurationError(BaseError):
+    """Represents a configuration error.
+
+    This error is used when there is a problem with the application's
+    configuration that prevents it from operating correctly.
+    """
 
     def __init__(
         self,
         operation: str | None = None,
         reason: str | None = None,
         lang: LanguageType | None = None,
-        error: ErrorDetailDTO = ErrorMessageType.ABORTED.value,
-        additional_data: dict | None = None,
+        error: ErrorDetailDTO = ErrorMessageType.CONFIGURATION_ERROR.value,
+        additional_data: dict[str, Any] | None = None,
     ) -> None:
         data = {}
         if operation:
@@ -55,15 +53,19 @@ def __init__(
         super().__init__(error, lang, data if data else None)
 
 
-class DeadlockDetectedError(BaseError):
-    """Exception raised when a deadlock is detected in the system."""
+class UnavailableError(BaseError):
+    """Represents a resource unavailability error.
+
+    This error is used when a required resource is temporarily unavailable
+    but may become available again in the future.
+    """
 
     def __init__(
         self,
         resource_type: str | None = None,
         lang: LanguageType | None = None,
-        error: ErrorDetailDTO = ErrorMessageType.DEADLOCK.value,
-        additional_data: dict | None = None,
+        error: ErrorDetailDTO = ErrorMessageType.UNAVAILABLE.value,
+        additional_data: dict[str, Any] | None = None,
     ) -> None:
         data = {}
         if resource_type:
@@ -73,15 +75,19 @@ def __init__(
         super().__init__(error, lang, data if data else None)
 
 
-class ConfigurationError(BaseError):
-    """Exception raised for system configuration errors."""
+class UnknownError(BaseError):
+    """Represents an unknown error.
+
+    This is a catch-all error type for unexpected conditions that
+    don't fit into other error categories.
+    """
 
     def __init__(
         self,
         config_key: str | None = None,
         lang: LanguageType | None = None,
-        error: ErrorDetailDTO = ErrorMessageType.CONFIGURATION_ERROR.value,
-        additional_data: dict | None = None,
+        error: ErrorDetailDTO = ErrorMessageType.UNKNOWN_ERROR.value,
+        additional_data: dict[str, Any] | None = None,
     ) -> None:
         data = {}
         if config_key:
@@ -91,16 +97,45 @@ def __init__(
         super().__init__(error, lang, data if data else None)
 
 
-class UnavailableError(BaseError):
-    """Exception raised when a requested service or feature is unavailable."""
+class AbortedError(BaseError):
+    """Represents an aborted operation error.
+
+    This error is used when an operation is aborted, typically due to
+    a concurrency issue or user cancellation.
+    """
+
+    def __init__(
+        self,
+        service: str | None = None,
+        reason: str | None = None,
+        lang: LanguageType | None = None,
+        error: ErrorDetailDTO = ErrorMessageType.UNAVAILABLE.value,
+        additional_data: dict[str, Any] | None = None,
+    ) -> None:
+        data = {}
+        if service:
+            data["service"] = service
+        if reason:
+            data["reason"] = reason
+        if additional_data:
+            data.update(additional_data)
+        super().__init__(error, lang, data if data else None)
+
+
+class DeadlockDetectedError(BaseError):
+    """Represents a deadlock detection error.
+
+    This error is used when a deadlock is detected in a system operation,
+    typically in database transactions or resource locking scenarios.
+    """
 
     def __init__(
         self,
         service: str | None = None,
         reason: str | None = None,
         lang: LanguageType | None = None,
         error: ErrorDetailDTO = ErrorMessageType.UNAVAILABLE.value,
-        additional_data: dict | None = None,
+        additional_data: dict[str, Any] | None = None,
     ) -> None:
         data = {}
         if service:
@@ -110,3 +145,93 @@ def __init__(
         if additional_data:
             data.update(additional_data)
         super().__init__(error, lang, data if data else None)
+
+
+class DeadlineExceededError(BaseError):
+    """Raised when an operation exceeds its deadline/timeout.
+
+    This error is typically used in decorators or functions that have
+    time limits or deadlines for completion.
+    """
+
+    http_status_code: ClassVar[int] = 408  # Request Timeout
+    grpc_status_code: ClassVar[int] = 4  # DEADLINE_EXCEEDED
+
+    def __init__(
+        self,
+        timeout: int | None = None,
+        operation: str | None = None,
+        lang: LanguageType | None = None,
+        additional_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize DeadlineExceededError.
+
+        Args:
+            timeout: The timeout value that was exceeded (in seconds).
+            operation: The operation that exceeded the deadline.
+            lang: The language for error messages.
+            additional_data: Additional context data.
+        """
+        error = ErrorDetailDTO(
+            code="DEADLINE_EXCEEDED",
+            message_en="Operation exceeded its deadline",
+            message_fa="عملیات از مهلت زمانی مجاز تجاوز کرد",
+            http_status=self.http_status_code,
+            grpc_status=self.grpc_status_code,
+        )
+
+        data = {}
+        if timeout is not None:
+            data["timeout"] = timeout
+        if operation:
+            data["operation"] = operation
+        if additional_data:
+            data.update(additional_data)
+        super().__init__(error, lang, data if data else None)
+
+
+class DeprecationError(BaseError):
+    """Raised when deprecated functionality is used.
+
+    This error is used to signal that a feature, method, or API
+    is deprecated and should no longer be used.
+    """
+
+    http_status_code: ClassVar[int] = 410  # Gone
+    grpc_status_code: ClassVar[int] = 12  # UNIMPLEMENTED
+
+    def __init__(
+        self,
+        deprecated_feature: str | None = None,
+        replacement: str | None = None,
+        removal_version: str | None = None,
+        lang: LanguageType | None = None,
+        additional_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize DeprecationError.
+
+        Args:
+            deprecated_feature: The name of the deprecated feature.
+            replacement: The recommended replacement feature.
+            removal_version: The version when the feature will be removed.
+            lang: The language for error messages.
+            additional_data: Additional context data.
+        """
+        error = ErrorDetailDTO(
+            code="DEPRECATED_FEATURE",
+            message_en="This feature is deprecated and should no longer be used",
+            message_fa="این ویژگی منسوخ شده و دیگر نباید استفاده شود",
+            http_status=self.http_status_code,
+            grpc_status=self.grpc_status_code,
+        )
+
+        data = {}
+        if deprecated_feature:
+            data["deprecated_feature"] = deprecated_feature
+        if replacement:
+            data["replacement"] = replacement
+        if removal_version:
+            data["removal_version"] = removal_version
+        if additional_data:
+            data.update(additional_data)
+        super().__init__(error, lang, data if data else None)

pyproject.toml

@@ -197,9 +197,9 @@ target-version = "py313"
 # Ignore F811 (redefinition of function) in steps implementations
 "archipy/configs/config_template.py" = ["S104"]  # Allow binding to all interfaces for containerized deployments
 "archipy/models/errors/keycloak_errors.py" = ["ANN401"]  # Allow Any type for additional_data
+"archipy/helpers/decorators/sqlalchemy_atomic.py" = ["BLE001"]  # Allow complex decorator patterns
 "archipy/helpers/decorators/*" = ["ANN401"]
 "archipy/helpers/utils/jwt_utils.py" = ["S105"]
-"archipy/helpers/decorators/sqlalchemy_atomic.py" = ["BLE001"]
 "archipy/helpers/utils/file_utils.py" = ["S324"]
 "archipy/helpers/utils/keycloak_utils.py" = ["FBT001", "FBT002"]
 "archipy/adapters/orm/sqlalchemy/ports.py" = ["ANN401"]
@@ -337,6 +337,10 @@ disable_error_code = ["assignment"]  # Allow flexible data dictionary assignment
 module = "archipy.models.dtos.range_dtos"
 disable_error_code = ["operator"]  # Allow generic type comparisons
 
+[[tool.mypy.overrides]]
+module = "archipy.helpers.decorators.sqlalchemy_atomic"
+disable_error_code = ["return", "misc", "no-any-return", "return-value"]  # Allow complex decorator patterns
+
 [tool.config]
 pyproject_root_var = "pyproject"