feat: add support for typing

Author: guludo

CHANGELOG.md

@@ -6,6 +6,11 @@ Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## Unreleased
+### Added
+- Added support for typing (tested with mypy).
+
+
 ## 0.1.0 - 2021-11-23
 ### Added
 - First release!

argparse_subdec/subdec.py

@@ -8,6 +8,44 @@
 import typing as ty
 
 
+F = ty.TypeVar('F', bound=ty.Callable[..., ty.Any])
+
+
+Decorator = ty.Callable[[F], F]
+
+
+DecoratorFactory = ty.Callable[..., Decorator[F]]
+
+
+AnyCallable = ty.Callable[..., ty.Any]
+
+
+AnyDecoratorFactory = DecoratorFactory[AnyCallable]
+
+
+class CommandDescriptor(ty.TypedDict):
+    name: ty.Optional[str]
+    fn: AnyCallable
+    subparser_call_stack: ty.List[SubparserCallDescriptor]
+    add_parser_args: ty.Optional[ty.Tuple[ty.Sequence[ty.Any],
+                                          ty.Dict[str, ty.Any]]]
+
+class SubparserCallDescriptor(ty.TypedDict):
+    method_name: str
+    args: ty.Tuple[ty.Any, ...]
+    kwargs: ty.Dict[str, ty.Any]
+
+
+class SubparsersProtocol(ty.Protocol):
+    """
+    A protocol class to describe the returned value of
+    ``argparse.ArgumentParser.add_subparsers()``, since the official
+    documentation does not point to a public type for the returned value.
+    """
+    def add_parser(self, name: str, **kw: ty.Any) -> argparse.ArgumentParser:
+        ... # pragma: no cover
+
+
 class SubDec:
     """
     This class provides a way to decorate functions as subcommands for
@@ -75,37 +113,37 @@ def __init__(self,
         replace the underscore character ("_") when converting the name of the
         decorated function to a subcommand name.
         """
-        self.__decorators_cache = {}
-        self.__commands = {}
+        self.__decorators_cache: ty.Dict[str, AnyDecoratorFactory] = {}
+        self.__commands: ty.Dict[AnyCallable, CommandDescriptor] = {}
         self.__name_prefix = name_prefix
         self.__fn_dest = fn_dest
         self.__sep = sep
 
-    def create_parsers(self, subparsers):
+    def create_parsers(self, subparsers: SubparsersProtocol) -> None:
         """
         Create subparsers by calling ``subparsers.add_parser()`` for each
         decorated function.
         """
         for cmd in self.__commands.values():
             self.__create_parser(cmd, subparsers)
 
-    def cmd(self, *k, **kw):
+    def cmd(self, *k: ty.Any, **kw: ty.Any) -> DecoratorFactory[F]:
         """
         Special decorator to register arguments to be passed do
         ``add_parser()``.
         """
-        def decorator(fn):
+        def decorator(fn: F) -> F:
             cmd = self.__get_command(fn)
             cmd['add_parser_args'] = (k, kw)
             return fn
         return decorator
 
-    def __getattr__(self, name: str):
+    def __getattr__(self, name: str) -> AnyDecoratorFactory:
         if name in self.__decorators_cache:
             return self.__decorators_cache[name]
 
-        def decorator_wrapper(*k, **kw):
-            def decorator(fn):
+        def decorator_wrapper(*k: ty.Any, **kw: ty.Any) -> Decorator[F]:
+            def decorator(fn: F) -> F:
                 cmd = self.__get_command(fn)
                 cmd['subparser_call_stack'].append({
                     'method_name': name,
@@ -118,7 +156,7 @@ def decorator(fn):
         self.__decorators_cache[name] = decorator_wrapper
         return decorator_wrapper
 
-    def __get_command(self, fn: ty.Callable):
+    def __get_command(self, fn: AnyCallable) -> CommandDescriptor:
         if fn not in self.__commands:
             self.__commands[fn] = {
                 'name': None,
@@ -128,7 +166,10 @@ def __get_command(self, fn: ty.Callable):
             }
         return self.__commands[fn]
 
-    def __create_parser(self, cmd: dict, subparsers: ty.Any):
+    def __create_parser(self,
+                        cmd: CommandDescriptor,
+                        subparsers: SubparsersProtocol,
+                        ) -> None:
         name = cmd['name']
         if not name:
             name = cmd['fn'].__name__
@@ -137,7 +178,7 @@ def __create_parser(self, cmd: dict, subparsers: ty.Any):
             if self.__sep is not None:
                 name = name.replace('_', self.__sep)
 
-        if cmd['add_parser_args']:
+        if cmd['add_parser_args'] is not None:
             add_parser_args, add_parser_kwargs = cmd['add_parser_args']
             if not add_parser_args:
                 add_parser_args = (name,)

mypy.ini

@@ -1,3 +1,3 @@
 [mypy]
 strict = True
-files = argparse_subdec/**.py
+files = argparse_subdec/**.py,tests/**.py

tests/test_subdec.py

@@ -3,31 +3,31 @@
 import argparse_subdec
 
 
-def test_command_decorator():
+def test_command_decorator() -> None:
     sd = argparse_subdec.SubDec()
 
     @sd.cmd()
-    def foo():
+    def foo() -> None:
         pass
 
     @sd.cmd()
-    def two_words():
+    def two_words() -> None:
         pass
 
     @sd.add_argument('--option-for-bar')
     @sd.add_argument('--another-option-for-bar')
-    def bar():
+    def bar() -> None:
         pass
 
     @sd.cmd('changed-name')
     @sd.add_argument('--option')
-    def original_name():
+    def original_name() -> None:
         pass
 
     # Test changing order of decorators
     @sd.add_argument('--option')
     @sd.cmd('changed-name-2')
-    def another_original_name():
+    def another_original_name() -> None:
         pass
 
     parser = argparse.ArgumentParser()