typing: Improve @cancellable; add flag literals

Refine @cancellable typing to better model control flow and
introduce Literal types for optional Compiler flags to
improve static checking and autocomplete.

Author: emaheuxPEREN

frida/_frida/__init__.pyi

@@ -754,8 +754,13 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> str:
         """
         Build an agent.
@@ -766,8 +771,13 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> None:
         """
         Continuously build an agent.

frida/core.py

@@ -33,10 +33,15 @@
 else:
     from typing_extensions import Literal, TypedDict
 
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
+else:
+    from typing_extensions import ParamSpec
+
 if sys.version_info >= (3, 11):
-    from typing import NotRequired
+    from typing import NotRequired, cast
 else:
-    from typing_extensions import NotRequired
+    from typing_extensions import NotRequired, cast
 
 from . import _frida
 
@@ -72,15 +77,18 @@ def _filter_missing_kwargs(d: MutableMapping[Any, Any]) -> None:
             d.pop(key)
 
 
-R = TypeVar("R")
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
 
 
-def cancellable(f: Callable[..., R]) -> Callable[..., R]:
+def cancellable(f: Callable[P, R]) -> Callable[P, R]:
+    # currently there is no way to type properly the extended callable with optional cancellable parameter
+    # ref: https://github.com/python/typing/discussions/1905#discussioncomment-11696995
     @functools.wraps(f)
-    def wrapper(*args: Any, **kwargs: Any) -> R:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         cancellable = kwargs.pop("cancellable", None)
         if cancellable is not None:
-            with cancellable:
+            with cast(Cancellable, cancellable):
                 return f(*args, **kwargs)
 
         return f(*args, **kwargs)
@@ -1554,6 +1562,12 @@ class CompilerDiagnostic(TypedDict):
 CompilerOutputCallback = Callable[[str], None]
 CompilerDiagnosticsCallback = Callable[[List[CompilerDiagnostic]], None]
 
+CompilerOutputFormat = Literal["unescaped", "hex-bytes", "c-string"]
+CompilerBundleFormat = Literal["esm", "iife"]
+CompilerTypeCheck = Literal["full", "none"]
+CompilerSourceMaps = Literal["included", "omitted"]
+CompilerCompression = Literal["none", "terser"]
+CompilerPlatform = Literal["neutral", "gum", "browser"]
 
 class Compiler:
     def __init__(self) -> None:
@@ -1567,12 +1581,12 @@ def build(
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        output_format: Optional[str] = None,
-        bundle_format: Optional[str] = None,
-        type_check: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
-        platform: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
         externals: Optional[Sequence[str]] = None,
     ) -> str:
         kwargs = {
@@ -1593,12 +1607,12 @@ def watch(
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        output_format: Optional[str] = None,
-        bundle_format: Optional[str] = None,
-        type_check: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
-        platform: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
         externals: Optional[Sequence[str]] = None,
     ) -> None:
         kwargs = {