refactor: convenient names for oft-mentioned function arguments

Author: nedbat

coverage/collector.py

@@ -24,7 +24,15 @@
 from coverage.misc import human_sorted_items, isolate_module
 from coverage.plugin import CoveragePlugin
 from coverage.types import (
-    TArc, TFileDisposition, TTraceData, TTraceFn, Tracer, TWarnFn,
+    TArc,
+    TCheckIncludeFn,
+    TFileDisposition,
+    TShouldStartContextFn,
+    TShouldTraceFn,
+    TTraceData,
+    TTraceFn,
+    Tracer,
+    TWarnFn,
 )
 
 os = isolate_module(os)
@@ -60,9 +68,9 @@ class Collector:
     def __init__(
         self,
         core: Core,
-        should_trace: Callable[[str, FrameType], TFileDisposition],
-        check_include: Callable[[str, FrameType], bool],
-        should_start_context: Callable[[FrameType], str | None] | None,
+        should_trace: TShouldTraceFn,
+        check_include: TCheckIncludeFn,
+        should_start_context: TShouldStartContextFn | None,
         file_mapper: Callable[[str], str],
         branch: bool,
         warn: TWarnFn,

coverage/context.py

@@ -6,12 +6,14 @@
 from __future__ import annotations
 
 from types import FrameType
-from typing import cast, Callable, Sequence
+from typing import cast, Sequence
+
+from coverage.types import TShouldStartContextFn
 
 
 def combine_context_switchers(
-    context_switchers: Sequence[Callable[[FrameType], str | None]],
-) -> Callable[[FrameType], str | None] | None:
+    context_switchers: Sequence[TShouldStartContextFn],
+) -> TShouldStartContextFn | None:
     """Create a single context switcher from multiple switchers.
 
     `context_switchers` is a list of functions that take a frame as an

coverage/pytracer.py

@@ -16,8 +16,16 @@
 
 from coverage import env
 from coverage.types import (
-    TArc, TFileDisposition, TLineNo, TTraceData, TTraceFileData, TTraceFn,
-    Tracer, TWarnFn,
+    TArc,
+    TFileDisposition,
+    TLineNo,
+    TShouldStartContextFn,
+    TShouldTraceFn,
+    TTraceData,
+    TTraceFileData,
+    TTraceFn,
+    TWarnFn,
+    Tracer,
 )
 
 # We need the YIELD_VALUE opcode below, in a comparison-friendly form.
@@ -64,9 +72,9 @@ def __init__(self) -> None:
         # Attributes set from the collector:
         self.data: TTraceData
         self.trace_arcs = False
-        self.should_trace: Callable[[str, FrameType], TFileDisposition]
+        self.should_trace: TShouldTraceFn
         self.should_trace_cache: dict[str, TFileDisposition | None]
-        self.should_start_context: Callable[[FrameType], str | None] | None = None
+        self.should_start_context: TShouldStartContextFn | None = None
         self.switch_context: Callable[[str | None], None] | None = None
         self.lock_data: Callable[[], None]
         self.unlock_data: Callable[[], None]

coverage/sysmon.py

@@ -29,6 +29,8 @@
     TArc,
     TFileDisposition,
     TLineNo,
+    TShouldStartContextFn,
+    TShouldTraceFn,
     TTraceData,
     TTraceFileData,
     Tracer,
@@ -180,11 +182,11 @@ def __init__(self, tool_id: int) -> None:
         # Attributes set from the collector:
         self.data: TTraceData
         self.trace_arcs = False
-        self.should_trace: Callable[[str, FrameType], TFileDisposition]
+        self.should_trace: TShouldTraceFn
         self.should_trace_cache: dict[str, TFileDisposition | None]
         # TODO: should_start_context and switch_context are unused!
         # Change tests/testenv.py:DYN_CONTEXTS when this is updated.
-        self.should_start_context: Callable[[FrameType], str | None] | None = None
+        self.should_start_context: TShouldStartContextFn | None = None
         self.switch_context: Callable[[str | None], None] | None = None
         self.lock_data: Callable[[], None]
         self.unlock_data: Callable[[], None]

coverage/types.py

@@ -78,14 +78,19 @@ class TFileDisposition(Protocol):
 
 TTraceData = Dict[str, TTraceFileData]
 
+# Functions passed into collectors.
+TShouldTraceFn = Callable[[str, FrameType], TFileDisposition]
+TCheckIncludeFn = Callable[[str, FrameType], bool]
+TShouldStartContextFn = Callable[[FrameType], Union[str, None]]
+
 class Tracer(Protocol):
     """Anything that can report on Python execution."""
 
     data: TTraceData
     trace_arcs: bool
-    should_trace: Callable[[str, FrameType], TFileDisposition]
+    should_trace: TShouldTraceFn
     should_trace_cache: Mapping[str, TFileDisposition | None]
-    should_start_context: Callable[[FrameType], str | None] | None
+    should_start_context: TShouldStartContextFn | None
     switch_context: Callable[[str | None], None] | None
     lock_data: Callable[[], None]
     unlock_data: Callable[[], None]