some typing modernizations

Author: RobertBlackhart

docs/async_commands/index.rst

@@ -15,6 +15,7 @@ program that we will highlight below:
     """
 
     import asyncio
+    from typing import Annotated
 
     import recline
     from recline.formatters.table_formatter import TableFormat
@@ -24,7 +25,7 @@ program that we will highlight below:
 
 
     @recline.command
-    async def deploy(duration: int = 30) -> TableFormat:
+    async def deploy(duration: int = 30) -> Annotated[list[dict[str, int]], TableFormat]:
         """Runs a deployment operation over a period of time
 
         Args:

docs/todo/index.rst

@@ -23,7 +23,7 @@ This could look something like this:
 .. code-block:: Python
 
     @recline.command(name='cake show')
-    def show_cake() ->  Union[TableFormat, CSVFormat, JSONFormat]
+    def show_cake() -> TableFormat | CSVFormat | JSONFormat:
         return cakes
 
 In this case, TableFormat would be the default if the user didn't choose anything

examples/async.py

@@ -6,6 +6,7 @@
 """
 
 import asyncio
+from typing import Annotated
 
 import recline
 from recline.formatters.table_formatter import TableFormat
@@ -15,7 +16,7 @@
 
 
 @recline.command
-async def deploy(duration: int = 30) -> TableFormat:
+async def deploy(duration: int = 30) -> Annotated[list[dict[str, int]], TableFormat]:
     """Runs a deployment operation over a period of time
 
     Args:
@@ -24,15 +25,16 @@ async def deploy(duration: int = 30) -> TableFormat:
 
     global PERCENT_COMPLETE
 
+    seconds_slept = 0
     try:
-        seconds_slept = 0
         while seconds_slept < duration:
             await asyncio.sleep(1)
             seconds_slept += 1
             PERCENT_COMPLETE = (seconds_slept / duration) * 100
         return [{'duration': duration}]
     except asyncio.CancelledError:
         print('I only managed to get %s out of %s seconds of sleep before you interrupted me' % (seconds_slept, duration))
+        return [{'duration': duration, 'seconds_slept': seconds_slept}]
 
 
 @recline.command(name="deploy status")

examples/cake.py

@@ -7,6 +7,7 @@
 
 from collections import OrderedDict
 from time import sleep
+from typing import Annotated
 
 import recline
 from recline.arg_types.choices import Choices
@@ -61,7 +62,7 @@ def make_cake(
 
 
 @recline.command(name="cake show")
-def show_cake() -> TableFormat:
+def show_cake() -> Annotated[list[dict[str, int]], TableFormat]:
     """Show all of our completed cake work"""
 
     return CAKES

examples/hello.py

@@ -4,8 +4,6 @@
 A "hello world" application for CLI commands
 """
 
-from typing import List
-
 import recline
 
 
@@ -25,7 +23,7 @@ def hello(name: str = None) -> None:
 
 
 @recline.command(name="group hello")
-def group_hello(names: List[str], formal: bool = False) -> None:
+def group_hello(names: list[str], formal: bool = False) -> None:
     """A less-basic hello world
 
     You can greet several people with this command if they give you their names!

recline/arg_types/choices.py

@@ -10,7 +10,7 @@ def make_cake(flavor: Choices.define(["chocolate", "vanilla", "marble"])) -> Non
     # We can assume flavor is one of the choices in the body of the function
 """
 
-from typing import Callable, List, Union
+from typing import Callable
 
 from recline.arg_types.recline_type import ReclineType
 from recline.arg_types.recline_type_error import ReclineTypeError
@@ -21,7 +21,7 @@ class Choices(ReclineType):
 
     @staticmethod
     def define(
-            available_choices: Union[List, Callable], cache_choices: bool = False,
+            available_choices: list | Callable, cache_choices: bool = False,
             inexact: bool = False, data_type=str,
         ) -> "Choices":
         """A `recline.commands.types.Choices` is a way to assert that an argument

recline/arg_types/recline_type.py

@@ -6,7 +6,7 @@
 
 from abc import ABC
 import argparse
-from typing import Any, List, Optional, Union
+from typing import Any
 
 
 class UniqueParam(argparse.Action):  # pylint: disable=too-few-public-methods
@@ -32,14 +32,14 @@ class ReclineType(ABC):
     def __init__(self):
         self.arg_name = None
 
-    def choices(self, eager=False) -> Optional[List[Any]]:  # pylint: disable=unused-argument,no-self-use
+    def choices(self, eager=False) -> list[Any] | None:  # pylint: disable=unused-argument,no-self-use
         """If an argument has a set list of choices that can be provided for it,
         then the type can specify to only allow that list
         """
 
         return None
 
-    def completer(self, *args, **kwargs) -> List[Any]:  # pylint: disable=unused-argument,no-self-use
+    def completer(self, *args, **kwargs) -> list[Any]:  # pylint: disable=unused-argument,no-self-use
         """The completer function should return a list of values that are valid
         for the argument. This function will usually be implemented such that it
         is dynamic based on some API call or some current application state. If
@@ -49,7 +49,7 @@ def completer(self, *args, **kwargs) -> List[Any]:  # pylint: disable=unused-arg
 
         return [None]
 
-    def nargs(self) -> Optional[Union[int, str]]:  # pylint: disable=no-self-use
+    def nargs(self) -> int | str | None:  # pylint: disable=no-self-use
         """The number of arguments that this type can accept. See the argparse
         documentation for details: https://docs.python.org/3/library/argparse.html#nargs
         """

recline/commands/cli_command.py

@@ -13,7 +13,7 @@
 import io
 import json
 import logging
-from typing import Callable, List, Union
+from typing import Annotated, Callable, get_args, get_origin
 
 from recline import commands
 from recline.arg_types.recline_type import ReclineType, UniqueParam
@@ -65,10 +65,15 @@ def __init__(
         self.docstring = docstring_parser.parse(self.func.__doc__)
 
         return_type = signature.return_annotation
-        if return_type and issubclass(return_type, OutputFormatter):
-            self.output_formatter = return_type()
-        else:
-            self.output_formatter = None
+        formatter_type = None
+        if get_origin(return_type) is Annotated:
+            for arg in get_args(return_type)[1:]:
+                if isinstance(arg, type) and issubclass(arg, OutputFormatter):
+                    formatter_type = arg
+                    break
+        elif return_type and isinstance(return_type, type) and issubclass(return_type, OutputFormatter):
+            formatter_type = return_type
+        self.output_formatter = formatter_type() if formatter_type else None
         self.parser = self._create_parser()
 
         # Using a separate parser object to pass to argcomplete prevents an issue
@@ -172,7 +177,7 @@ def _recline_type_annotation_handler(arg_annotation, nargs=None):
 
         if arg.annotation:
             annotation_type = get_annotation_type(arg)
-            if issubclass(annotation_type, List):
+            if issubclass(annotation_type, list):
                 if issubclass(arg.annotation.__args__[0], ReclineType):
                     _recline_type_annotation_handler(arg.annotation.__args__[0], '+')
                 else:
@@ -223,7 +228,7 @@ def get_arg_metavar(self, arg):  #pylint: disable=no-self-use,too-many-return-st
             return basic
         if issubclass(annotation_type, ReclineType):
             return arg.annotation.metavar
-        if issubclass(annotation_type, List):
+        if issubclass(annotation_type, list):
             return f'<{arg.name}> [{arg.name} ...]'
         if issubclass(annotation_type, bool):
             return '<true|false>'
@@ -330,10 +335,10 @@ def command(
     func=None,
     name: str = None,
     group: str = None,
-    aliases: List[str] = None,
+    aliases: list[str] | None = None,
     atstart: bool = False,
     atexit: bool = False,
-    hidden: Union[Callable[[], bool], bool] = False,
+    hidden: Callable[[], bool] | bool = False,
     background: bool = False
 ):
     """Wrapping a function with this registers it with the recline library and

recline/repl/shell.py

@@ -11,7 +11,7 @@
 import signal
 import sys
 import traceback
-from typing import Callable, List, Union
+from typing import Callable
 
 import recline
 from recline import commands
@@ -25,7 +25,7 @@
 def relax(
     argv: str = None,
     program_name: str = None,
-    motd: Union[Callable[[], str], str] = None,
+    motd: Callable[[], str] | str | None = None,
     history_file: str = None,
     prompt: str = None,
     repl_mode: bool = True,
@@ -109,9 +109,9 @@ def relax(
             sys.exit(0)
 
 
-def _split_unquoted(current_input: str, separator: str) -> List[str]:
+def _split_unquoted(current_input: str, separator: str) -> list[str]:
     """Split `current_input` on `separator` only when outside quoted strings."""
-    parts: List[str] = []
+    parts: list[str] = []
     start = 0
     position = 0
     in_single = False
@@ -228,7 +228,7 @@ def run_one_command(current_input: str) -> int:
     return 1
 
 
-def _setup_repl(program_name: str, prompt: str, history_file: str, argv: List[str]) -> None:
+def _setup_repl(program_name: str, prompt: str, history_file: str, argv: list[str]) -> None:
     if not program_name:
         recline.PROGRAM_NAME = argv[0].split(os.path.sep)[-1]
     else:
@@ -258,7 +258,7 @@ def signal_handler(_signum, _frame):
             pass
 
 
-def _run_command(command: str, cmd_args: List[str]) -> int:
+def _run_command(command: str, cmd_args: list[str]) -> int:
     namespace = command.parser.parse_args(args=cmd_args)
 
     args = [getattr(namespace, arg.name) for arg in command.required_args]

recline/vendor/docstring_parser/parser/common.py

@@ -1,6 +1,6 @@
 """Common methods for parsing."""
 
-import typing as T
+from typing import Any
 
 
 class ParseError(RuntimeError):
@@ -19,7 +19,7 @@ class DocstringMeta:
         :raises ValueError: if something happens
     """
 
-    def __init__(self, args: T.List[str], description: str) -> None:
+    def __init__(self, args: list[str], description: str) -> None:
         """
         Initialize self.
 
@@ -30,7 +30,7 @@ def __init__(self, args: T.List[str], description: str) -> None:
         self.description = description
 
     @classmethod
-    def from_meta(cls, meta: "DocstringMeta") -> T.Any:
+    def from_meta(cls, meta: "DocstringMeta") -> Any:
         """Copy DocstringMeta from another instance."""
         return cls(args=meta.args, description=meta.description)
 
@@ -39,7 +39,7 @@ class DocstringTypeMeta(DocstringMeta):
     """Docstring meta whose only optional arg contains type information."""
 
     @property
-    def type_name(self) -> T.Optional[str]:
+    def type_name(self) -> str | None:
         """Return type name associated with given docstring metadata."""
         return self.args[1] if len(self.args) > 1 else None
 
@@ -48,7 +48,7 @@ class DocstringParam(DocstringMeta):
     """DocstringMeta symbolizing :param metadata."""
 
     @property
-    def arg_name(self) -> T.Optional[str]:
+    def arg_name(self) -> str | None:
         """Return argument name associated with given param."""
         if len(self.args) > 2:
             return self.args[2]
@@ -57,7 +57,7 @@ def arg_name(self) -> T.Optional[str]:
         return None
 
     @property
-    def type_name(self) -> T.Optional[str]:
+    def type_name(self) -> str | None:
         """Return type name associated with given param."""
         return self.args[1] if len(self.args) > 2 else None
 
@@ -78,7 +78,7 @@ class DocstringExamples(DocstringTypeMeta):
     """DocstringMeta symbolizing :examples metadata."""
 
     @property
-    def name(self) -> T.Optional[str]:
+    def name(self) -> str | None:
         """Return the example name associated with given param."""
         if self.args:
             return self.args[1]
@@ -90,14 +90,14 @@ class Docstring:
 
     def __init__(self) -> None:
         """Initializes self."""
-        self.short_description = None  # type: T.Optional[str]
-        self.long_description = None  # type: T.Optional[str]
+        self.short_description = None  # type: str | None
+        self.long_description = None  # type: str | None
         self.blank_after_short_description = False
         self.blank_after_long_description = False
-        self.meta = []  # type: T.List[DocstringMeta]
+        self.meta = []  # type: list[DocstringMeta]
 
     @property
-    def params(self) -> T.List[DocstringParam]:
+    def params(self) -> list[DocstringParam]:
         """Return parameters indicated in docstring."""
         return [
             DocstringParam.from_meta(meta)
@@ -107,7 +107,7 @@ def params(self) -> T.List[DocstringParam]:
         ]
 
     @property
-    def raises(self) -> T.List[DocstringRaises]:
+    def raises(self) -> list[DocstringRaises]:
         """Return exceptions indicated in docstring."""
         return [
             DocstringRaises.from_meta(meta)
@@ -116,7 +116,7 @@ def raises(self) -> T.List[DocstringRaises]:
         ]
 
     @property
-    def returns(self) -> T.Optional[DocstringReturns]:
+    def returns(self) -> DocstringReturns | None:
         """Return return information indicated in docstring."""
         try:
             return next(
@@ -128,7 +128,7 @@ def returns(self) -> T.Optional[DocstringReturns]:
             return None
 
     @property
-    def examples(self) -> T.Optional[DocstringExamples]:
+    def examples(self) -> DocstringExamples | None:
         """Return example information indicated in docstring."""
         return [
             DocstringExamples.from_meta(meta)