Force use of future annotations to enable better support for modern type hints that don't require things like Optional

This also supports better runtime performance by allowing imports only used for type hints to be moved under `if TYPE_CHECKING:` blocks.

Author: tleonhardt

cmd2/__init__.py

@@ -1,5 +1,7 @@
 """Import certain things for backwards compatibility."""
 
+from __future__ import annotations
+
 import argparse
 import contextlib
 import importlib.metadata as importlib_metadata

cmd2/ansi.py

@@ -3,6 +3,8 @@
 These are used for things like applying style to text, setting the window title, and asynchronous alerts.
 """
 
+from __future__ import annotations
+
 import functools
 import re
 from enum import (
@@ -11,7 +13,6 @@
 from typing import (
     IO,
     Any,
-    Optional,
     cast,
 )
 
@@ -951,14 +952,14 @@ def __str__(self) -> str:
 def style(
     value: Any,
     *,
-    fg: Optional[FgColor] = None,
-    bg: Optional[BgColor] = None,
-    bold: Optional[bool] = None,
-    dim: Optional[bool] = None,
-    italic: Optional[bool] = None,
-    overline: Optional[bool] = None,
-    strikethrough: Optional[bool] = None,
-    underline: Optional[bool] = None,
+    fg: FgColor | None = None,
+    bg: BgColor | None = None,
+    bold: bool | None = None,
+    dim: bool | None = None,
+    italic: bool | None = None,
+    overline: bool | None = None,
+    strikethrough: bool | None = None,
+    underline: bool | None = None,
 ) -> str:
     """Apply ANSI colors and/or styles to a string and return it.
 

cmd2/argparse_completer.py

@@ -3,6 +3,8 @@
 See the header of argparse_custom.py for instructions on how to use these features.
 """
 
+from __future__ import annotations
+
 import argparse
 import inspect
 import numbers
@@ -11,7 +13,6 @@
 )
 from typing import (
     TYPE_CHECKING,
-    Optional,
     Union,
     cast,
 )
@@ -28,16 +29,16 @@
     from .cmd2 import (
         Cmd,
     )
+    from .command_definition import (
+        CommandSet,
+    )
 
 from .argparse_custom import (
     ChoicesCallable,
     ChoicesProviderFuncWithTokens,
     CompletionItem,
     generate_range_error,
 )
-from .command_definition import (
-    CommandSet,
-)
 from .exceptions import (
     CompletionError,
 )
@@ -104,8 +105,8 @@ class _ArgumentState:
 
     def __init__(self, arg_action: argparse.Action) -> None:
         self.action = arg_action
-        self.min: Union[int, str]
-        self.max: Union[float, int, str]
+        self.min: int | str
+        self.max: float | int | str
         self.count = 0
         self.is_remainder = self.action.nargs == argparse.REMAINDER
 
@@ -162,7 +163,7 @@ class ArgparseCompleter:
     """Automatic command line tab completion based on argparse parameters."""
 
     def __init__(
-        self, parser: argparse.ArgumentParser, cmd2_app: 'Cmd', *, parent_tokens: Optional[dict[str, list[str]]] = None
+        self, parser: argparse.ArgumentParser, cmd2_app: Cmd, *, parent_tokens: dict[str, list[str]] | None = None
     ) -> None:
         """Create an ArgparseCompleter.
 
@@ -202,7 +203,7 @@ def __init__(
                     self._subcommand_action = action
 
     def complete(
-        self, text: str, line: str, begidx: int, endidx: int, tokens: list[str], *, cmd_set: Optional[CommandSet] = None
+        self, text: str, line: str, begidx: int, endidx: int, tokens: list[str], *, cmd_set: CommandSet | None = None
     ) -> list[str]:
         """Complete text using argparse metadata.
 
@@ -227,10 +228,10 @@ def complete(
         skip_remaining_flags = False
 
         # _ArgumentState of the current positional
-        pos_arg_state: Optional[_ArgumentState] = None
+        pos_arg_state: _ArgumentState | None = None
 
         # _ArgumentState of the current flag
-        flag_arg_state: Optional[_ArgumentState] = None
+        flag_arg_state: _ArgumentState | None = None
 
         # Non-reusable flags that we've parsed
         matched_flags: list[str] = []
@@ -522,7 +523,7 @@ def _complete_flags(self, text: str, line: str, begidx: int, endidx: int, matche
 
         return matches
 
-    def _format_completions(self, arg_state: _ArgumentState, completions: Union[list[str], list[CompletionItem]]) -> list[str]:
+    def _format_completions(self, arg_state: _ArgumentState, completions: list[str] | list[CompletionItem]) -> list[str]:
         """Format CompletionItems into hint table."""
         # Nothing to do if we don't have at least 2 completions which are all CompletionItems
         if len(completions) < 2 or not all(isinstance(c, CompletionItem) for c in completions):
@@ -652,15 +653,15 @@ def _complete_arg(
         arg_state: _ArgumentState,
         consumed_arg_values: dict[str, list[str]],
         *,
-        cmd_set: Optional[CommandSet] = None,
+        cmd_set: CommandSet | None = None,
     ) -> list[str]:
         """Tab completion routine for an argparse argument.
 
         :return: list of completions
         :raises CompletionError: if the completer or choices function this calls raises one.
         """
         # Check if the arg provides choices to the user
-        arg_choices: Union[list[str], ChoicesCallable]
+        arg_choices: list[str] | ChoicesCallable
         if arg_state.action.choices is not None:
             arg_choices = list(arg_state.action.choices)
             if not arg_choices:

cmd2/argparse_custom.py

@@ -221,6 +221,8 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
 sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser` for more details.
 """
 
+from __future__ import annotations
+
 import argparse
 import re
 import sys
@@ -229,7 +231,6 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
     ZERO_OR_MORE,
     ArgumentError,
 )
-from collections.abc import Callable, Iterable, Sequence
 from gettext import (
     gettext,
 )
@@ -245,12 +246,16 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
     runtime_checkable,
 )
 
+from typing_extensions import Self
+
 from . import (
     ansi,
     constants,
 )
 
 if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Callable, Iterable, Sequence
+
     from .argparse_completer import (
         ArgparseCompleter,
     )
@@ -281,7 +286,7 @@ class CompletionItem(str):  # noqa: SLOT000
     See header of this file for more information
     """
 
-    def __new__(cls, value: object, *_args: Any, **_kwargs: Any) -> 'CompletionItem':
+    def __new__(cls, value: object, *_args: Any, **_kwargs: Any) -> Self:
         """Responsible for creating and returning a new instance, called before __init__ when an object is instantiated."""
         return super().__new__(cls, value)
 
@@ -371,7 +376,7 @@ class ChoicesCallable:
     def __init__(
         self,
         is_completer: bool,
-        to_call: Union[CompleterFunc, ChoicesProviderFunc],
+        to_call: CompleterFunc | ChoicesProviderFunc,
     ) -> None:
         """Initialize the ChoiceCallable instance.
 
@@ -432,7 +437,7 @@ def choices_provider(self) -> ChoicesProviderFunc:
 ############################################################################################################
 # Patch argparse.Action with accessors for choice_callable attribute
 ############################################################################################################
-def _action_get_choices_callable(self: argparse.Action) -> Optional[ChoicesCallable]:
+def _action_get_choices_callable(self: argparse.Action) -> ChoicesCallable | None:
     """Get the choices_callable attribute of an argparse Action.
 
     This function is added by cmd2 as a method called ``get_choices_callable()`` to ``argparse.Action`` class.
@@ -518,7 +523,7 @@ def _action_set_completer(
 ############################################################################################################
 # Patch argparse.Action with accessors for descriptive_header attribute
 ############################################################################################################
-def _action_get_descriptive_header(self: argparse.Action) -> Optional[str]:
+def _action_get_descriptive_header(self: argparse.Action) -> str | None:
     """Get the descriptive_header attribute of an argparse Action.
 
     This function is added by cmd2 as a method called ``get_descriptive_header()`` to ``argparse.Action`` class.
@@ -534,7 +539,7 @@ def _action_get_descriptive_header(self: argparse.Action) -> Optional[str]:
 setattr(argparse.Action, 'get_descriptive_header', _action_get_descriptive_header)
 
 
-def _action_set_descriptive_header(self: argparse.Action, descriptive_header: Optional[str]) -> None:
+def _action_set_descriptive_header(self: argparse.Action, descriptive_header: str | None) -> None:
     """Set the descriptive_header attribute of an argparse Action.
 
     This function is added by cmd2 as a method called ``set_descriptive_header()`` to ``argparse.Action`` class.
@@ -553,7 +558,7 @@ def _action_set_descriptive_header(self: argparse.Action, descriptive_header: Op
 ############################################################################################################
 # Patch argparse.Action with accessors for nargs_range attribute
 ############################################################################################################
-def _action_get_nargs_range(self: argparse.Action) -> Optional[tuple[int, Union[int, float]]]:
+def _action_get_nargs_range(self: argparse.Action) -> tuple[int, int | float] | None:
     """Get the nargs_range attribute of an argparse Action.
 
     This function is added by cmd2 as a method called ``get_nargs_range()`` to ``argparse.Action`` class.
@@ -569,7 +574,7 @@ def _action_get_nargs_range(self: argparse.Action) -> Optional[tuple[int, Union[
 setattr(argparse.Action, 'get_nargs_range', _action_get_nargs_range)
 
 
-def _action_set_nargs_range(self: argparse.Action, nargs_range: Optional[tuple[int, Union[int, float]]]) -> None:
+def _action_set_nargs_range(self: argparse.Action, nargs_range: tuple[int, int | float] | None) -> None:
     """Set the nargs_range attribute of an argparse Action.
 
     This function is added by cmd2 as a method called ``set_nargs_range()`` to ``argparse.Action`` class.
@@ -628,7 +633,7 @@ def _action_set_suppress_tab_hint(self: argparse.Action, suppress_tab_hint: bool
 _CUSTOM_ATTRIB_PFX = '_attr_'
 
 
-def register_argparse_argument_parameter(param_name: str, param_type: Optional[type[Any]]) -> None:
+def register_argparse_argument_parameter(param_name: str, param_type: type[Any] | None) -> None:
     """Register a custom argparse argument parameter.
 
     The registered name will then be a recognized keyword parameter to the parser's `add_argument()` function.
@@ -694,11 +699,11 @@ def _action_set_custom_parameter(self: argparse.Action, value: Any) -> None:
 def _add_argument_wrapper(
     self: argparse._ActionsContainer,
     *args: Any,
-    nargs: Union[int, str, tuple[int], tuple[int, int], tuple[int, float], None] = None,
-    choices_provider: Optional[ChoicesProviderFunc] = None,
-    completer: Optional[CompleterFunc] = None,
+    nargs: int | str | tuple[int] | tuple[int, int] | tuple[int, float] | None = None,
+    choices_provider: ChoicesProviderFunc | None = None,
+    completer: CompleterFunc | None = None,
     suppress_tab_hint: bool = False,
-    descriptive_header: Optional[str] = None,
+    descriptive_header: str | None = None,
     **kwargs: Any,
 ) -> argparse.Action:
     """Wrap ActionsContainer.add_argument() which supports more settings used by cmd2.
@@ -744,7 +749,7 @@ def _add_argument_wrapper(
     nargs_range = None
 
     if nargs is not None:
-        nargs_adjusted: Union[int, str, tuple[int], tuple[int, int], tuple[int, float], None]
+        nargs_adjusted: int | str | tuple[int] | tuple[int, int] | tuple[int, float] | None
         # Check if nargs was given as a range
         if isinstance(nargs, tuple):
             # Handle 1-item tuple by setting max to INFINITY
@@ -885,7 +890,7 @@ def _match_argument_wrapper(self: argparse.ArgumentParser, action: argparse.Acti
 ATTR_AP_COMPLETER_TYPE = 'ap_completer_type'
 
 
-def _ArgumentParser_get_ap_completer_type(self: argparse.ArgumentParser) -> Optional[type['ArgparseCompleter']]:  # noqa: N802
+def _ArgumentParser_get_ap_completer_type(self: argparse.ArgumentParser) -> type[ArgparseCompleter] | None:  # noqa: N802
     """Get the ap_completer_type attribute of an argparse ArgumentParser.
 
     This function is added by cmd2 as a method called ``get_ap_completer_type()`` to ``argparse.ArgumentParser`` class.
@@ -901,7 +906,7 @@ def _ArgumentParser_get_ap_completer_type(self: argparse.ArgumentParser) -> Opti
 setattr(argparse.ArgumentParser, 'get_ap_completer_type', _ArgumentParser_get_ap_completer_type)
 
 
-def _ArgumentParser_set_ap_completer_type(self: argparse.ArgumentParser, ap_completer_type: type['ArgparseCompleter']) -> None:  # noqa: N802
+def _ArgumentParser_set_ap_completer_type(self: argparse.ArgumentParser, ap_completer_type: type[ArgparseCompleter]) -> None:  # noqa: N802
     """Set the ap_completer_type attribute of an argparse ArgumentParser.
 
     This function is added by cmd2 as a method called ``set_ap_completer_type()`` to ``argparse.ArgumentParser`` class.
@@ -996,10 +1001,10 @@ class Cmd2HelpFormatter(argparse.RawTextHelpFormatter):
 
     def _format_usage(
         self,
-        usage: Optional[str],
+        usage: str | None,
         actions: Iterable[argparse.Action],
         groups: Iterable[argparse._ArgumentGroup],
-        prefix: Optional[str] = None,
+        prefix: str | None = None,
     ) -> str:
         if prefix is None:
             prefix = gettext('Usage: ')
@@ -1053,7 +1058,7 @@ def _format_usage(
                 # End cmd2 customization
 
                 # helper for wrapping lines
-                def get_lines(parts: list[str], indent: str, prefix: Optional[str] = None) -> list[str]:
+                def get_lines(parts: list[str], indent: str, prefix: str | None = None) -> list[str]:
                     lines: list[str] = []
                     line: list[str] = []
                     line_len = len(prefix) - 1 if prefix is not None else len(indent) - 1
@@ -1133,8 +1138,8 @@ def _format_action_invocation(self, action: argparse.Action) -> str:
     def _determine_metavar(
         self,
         action: argparse.Action,
-        default_metavar: Union[str, tuple[str, ...]],
-    ) -> Union[str, tuple[str, ...]]:
+        default_metavar: str | tuple[str, ...],
+    ) -> str | tuple[str, ...]:
         """Determine what to use as the metavar value of an action."""
         if action.metavar is not None:
             result = action.metavar
@@ -1150,7 +1155,7 @@ def _determine_metavar(
     def _metavar_formatter(
         self,
         action: argparse.Action,
-        default_metavar: Union[str, tuple[str, ...]],
+        default_metavar: str | tuple[str, ...],
     ) -> Callable[[int], tuple[str, ...]]:
         metavar = self._determine_metavar(action, default_metavar)
 
@@ -1161,7 +1166,7 @@ def format_tuple(tuple_size: int) -> tuple[str, ...]:
 
         return format_tuple
 
-    def _format_args(self, action: argparse.Action, default_metavar: Union[str, tuple[str, ...]]) -> str:
+    def _format_args(self, action: argparse.Action, default_metavar: str | tuple[str, ...]) -> str:
         """Handle ranged nargs and make other output less verbose."""
         metavar = self._determine_metavar(action, default_metavar)
         metavar_formatter = self._metavar_formatter(action, default_metavar)
@@ -1191,23 +1196,23 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
 
     def __init__(
         self,
-        prog: Optional[str] = None,
-        usage: Optional[str] = None,
-        description: Optional[str] = None,
-        epilog: Optional[str] = None,
+        prog: str | None = None,
+        usage: str | None = None,
+        description: str | None = None,
+        epilog: str | None = None,
         parents: Sequence[argparse.ArgumentParser] = (),
         formatter_class: type[argparse.HelpFormatter] = Cmd2HelpFormatter,
         prefix_chars: str = '-',
-        fromfile_prefix_chars: Optional[str] = None,
-        argument_default: Optional[str] = None,
+        fromfile_prefix_chars: str | None = None,
+        argument_default: str | None = None,
         conflict_handler: str = 'error',
         add_help: bool = True,
         allow_abbrev: bool = True,
         exit_on_error: bool = True,
         suggest_on_error: bool = False,
         color: bool = False,
         *,
-        ap_completer_type: Optional[type['ArgparseCompleter']] = None,
+        ap_completer_type: type[ArgparseCompleter] | None = None,
     ) -> None:
         """Initialize the Cmd2ArgumentParser instance, a custom ArgumentParser added by cmd2.
 
@@ -1341,7 +1346,7 @@ def format_help(self) -> str:
         # determine help from format above
         return formatter.format_help() + '\n'
 
-    def _print_message(self, message: str, file: Optional[IO[str]] = None) -> None:  # type: ignore[override]
+    def _print_message(self, message: str, file: IO[str] | None = None) -> None:  # type: ignore[override]
         # Override _print_message to use style_aware_write() since we use ANSI escape characters to support color
         if message:
             if file is None: