feat: Add typing for function_decorator

src/decopatch/main.pyi

@@ -0,0 +1,72 @@
+from typing import Any, Callable, Optional, Protocol, TypeVar, overload
+
+from decopatch.utils_disambiguation import FirstArgDisambiguation
+from decopatch.utils_modes import SignatureInfo
+
+try:
+ from typing import ParamSpec
+except ImportError:
+ from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+F = TypeVar("F", bound=Callable[..., Any])
+
+class _Decorator(Protocol[P]):
+ """
+ This is callable Protocol, to distinguish between cases where
+ created decorator is called as `@decorator` or `@decorator()`
+ """
+
+ # decorator is called without parenthesis: @decorator
+ @overload
+ def __call__(self, func: F) -> F: ...
+ # decorator is called with options or parenthesis: @decorator(some_option=...)
+ @overload
+ def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Callable[[F], F]: ...
+
+# @function_decorator is called without options or parenthesis
+@overload
+def function_decorator(
+ enable_stack_introspection: Callable[P, Any],
+ custom_disambiguator: Callable[[Any], FirstArgDisambiguation] = ...,
+ flat_mode_decorated_name: Optional[str] = ...,
+) -> _Decorator[P]: ...
+
+# @function_decorator() is called with options or parenthesis.
+@overload
+def function_decorator(
+ enable_stack_introspection: bool = ...,
+ custom_disambiguator: Callable[[Any], FirstArgDisambiguation] = ...,
+ flat_mode_decorated_name: Optional[str] = ...,
+) -> Callable[[Callable[P, Any]], _Decorator[P]]: ...
+def class_decorator(
+ enable_stack_introspection: bool = ...,
+ custom_disambiguator: Callable[[Any], FirstArgDisambiguation] = ...,
+ flat_mode_decorated_name: Optional[str] = ...,
+): ...
+def decorator(
+ is_function_decorator: bool = ...,
+ is_class_decorator: bool = ...,
+ enable_stack_introspection: bool = ...,
+ custom_disambiguator: Callable[[Any], FirstArgDisambiguation] = ...,
+ use_signature_trick: bool = ...,
+ flat_mode_decorated_name: str = ...,
+): ...
+def create_decorator(
+ impl_function,
+ is_function_decorator: bool = ...,
+ is_class_decorator: bool = ...,
+ enable_stack_introspection: bool = ...,
+ custom_disambiguator: Callable[[Any], FirstArgDisambiguation] = ...,
+ use_signature_trick: bool = ...,
+ flat_mode_decorated_name: Optional[str] = ...,
+): ...
+def create_no_args_decorator(
+ decorator_function, function_for_metadata: Any | None = ...
+): ...
+def create_kwonly_decorator(
+ sig_info: SignatureInfo, decorator_function, disambiguator, function_for_metadata
+): ...
+def create_general_case_decorator(
+ sig_info: SignatureInfo, impl_function, disambiguator, function_for_metadata
+): ...

tests/test_typing.py

@@ -0,0 +1,57 @@
+# This is test file for typing,
+# No automatic testing is used at the moment. Just use your type checker and see if it works.
+# Pytest here is used to make sure that runtime behavir matches with type checker expecter errors.
+from typing import Any, Callable
+
+import pytest
+
+from decopatch import DECORATED, function_decorator
+
+
+def test_invalid_parameter():
+ with pytest.raises(TypeError):
+ # Error, invalid argument
+ @function_decorator(invalid_param=True)
+ def decorator_wint_invalid_param(fn=DECORATED):
+ return fn
+
+
+def test_normal_decorator():
+ @function_decorator
+ def decorator(scope="test", fn=DECORATED): # type: (str, Any) -> Callable[..., Any]
+ assert isinstance(scope, str)
+ return fn
+
+ # Ok
+ @decorator
+ def decorated_flat():
+ pass
+
+ assert decorated_flat
+
+ with pytest.raises(AssertionError):
+ # Error, Literal[2] is incompatible with str
+ @decorator(scope=2)
+ def decorated_with_invalid_options():
+ pass
+
+ # Ok, should reveal correct type for `scope`
+ @decorator(scope="success")
+ def decorated_with_valid_options():
+ pass
+
+ assert decorated_with_valid_options
+
+
+def test_function_decorator_with_params():
+ # Ok, should reveal correct type for `enable_stack_introspection`
+ @function_decorator(enable_stack_introspection=True)
+ def decorator_with_params(scope = "test", fn=DECORATED): # type: (str, Any) -> Callable[..., Any]
+ return fn
+
+ # Ok, should reveal correct type for `scope`
+ @decorator_with_params(scope="success")
+ def decorated_with_valid_options():
+ pass
+
+ assert decorated_with_valid_options