Callable annotate (#163)

* explicitly define the type signature for koji CLI handler functions

* mention the type defining the signature

* squish import

koji_cli_plugins/kojismokydingometa.py

@@ -37,10 +37,10 @@ def __plugin__(glbls):
     # want to avoid leaving references around that it can see. So all
     # the action happens inside of this function.
 
-    import sys
     from operator import attrgetter
     from os import getenv
     from pkg_resources import iter_entry_points
+    from sys import stderr
 
     # these env var checks were introduced in v2.2.0
     verbose = getenv("KSD_VERBOSE", None) == "1"
@@ -57,7 +57,7 @@ def __plugin__(glbls):
             # function. This function is then invoked with the name of
             # the entry point. The return value should be either None
             # or a callable appropriate for use as a koji command
-            # handler.
+            # handler. See `kojismokydingo.types.CLIHandler`
 
             entry_fn = entry_point.resolve()
             handler = entry_fn(entry_point.name) if entry_fn else None
@@ -70,7 +70,7 @@ def __plugin__(glbls):
             if verbose:
                 # when KSD_VERBOSE=1 we announce than an error happened
                 message = f"Error loading plugin {entry_point!r}: {ex!r}"
-                print(message, file=sys.stderr)
+                print(message, file=stderr)
 
             if explode:
                 # when KSD_EXPLODE=1 we allow the exception to be

kojismokydingo/cli/__init__.py

@@ -41,12 +41,12 @@
 from os import devnull
 from os.path import basename
 from typing import (
-    Any, Callable, Dict, Iterable, List, Optional,
-    Sequence, TextIO, Tuple, Union, )
+    Any, Callable, Dict, Iterable, List, Optional, Sequence,
+    TextIO, Tuple, Union, )
 
 from .. import BadDingo, NotPermitted
 from ..common import itemsgetter, load_plugin_config
-from ..types import GOptions, HistoryEntry
+from ..types import CLIProtocol, GOptions, HistoryEntry
 
 
 __all__ = (
@@ -562,7 +562,7 @@ def print_history_results(
     return print_history(history, utc, show_events, verbose)
 
 
-class SmokyDingo(metaclass=ABCMeta):
+class SmokyDingo(CLIProtocol, metaclass=ABCMeta):
     """
     Base class for new sub-commands in Koji. Subclasses may be
     referenced via an entry point under the koji_smoky_dingo group to

kojismokydingo/types.py

@@ -27,19 +27,28 @@
 from enum import IntEnum
 from koji import (
     AUTHTYPES, BR_STATES, BR_TYPES, BUILD_STATES, CHECKSUM_TYPES,
-    REPO_STATES, TASK_STATES, USERTYPES, USER_STATUS, PathInfo, )
+    REPO_STATES, TASK_STATES, USERTYPES, USER_STATUS,
+    ClientSession, PathInfo, )
 from optparse import Values
 from typing import (
-    Any, Callable, Dict, Iterable, List,
-    Optional, Tuple, Union, )
+    Any, Callable, Dict, Iterable, List, Optional, Tuple, Union, )
 
 
 try:
     from typing import TypedDict  # type: ignore
 except ImportError:
+    # Python < 3.10 doesn't have typing.TypedDict
     from typing_extensions import TypedDict
 
 
+try:
+    from typing import Protocol
+except ImportError:
+    # Python < 3.8 doesn't have typing.Protocol
+    class Protocol:  # type: ignore
+        ...
+
+
 __all__ = (
     "ArchiveInfo",
     "ArchiveInfos",
@@ -58,6 +67,8 @@
     "ChannelSpec",
     "ChecksumType",
     "CGInfo",
+    "CLIHandler",
+    "CLIProtocol",
     "DecoratedBuildInfo",
     "DecoratedHostInfo",
     "DecoratedHostInfos",
@@ -1331,6 +1342,26 @@ class GOptions(Values):
     weburl: str
 
 
+CLIHandler = Callable[[GOptions, ClientSession, Optional[List[str]]],
+                      int]
+"""
+The callable signature used by Koji's CLI command handlers.
+"""
+
+
+class CLIProtocol(Protocol):
+    """
+    A Protocol variation on the `CLIHandler` callable definition.
+    """
+
+    def __call__(
+            self,
+            goptions: GOptions,
+            session: ClientSession,
+            args: Optional[List[str]] = None) -> int:
+        ...
+
+
 HistoryEntry = Tuple[int, str, bool, Dict[str, Any]]