Added "from __future__ import annotations" to each cmd2 module.

Fixed circular import between utils.py and completion.py.

Author: kmvanbrunt

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 dataclasses
 import inspect
@@ -22,33 +24,31 @@
     cast,
 )
 
-from rich.text import Text
-
-from .constants import INFINITY
-from .rich_utils import Cmd2GeneralConsole
-
-if TYPE_CHECKING:  # pragma: no cover
-    from .cmd2 import Cmd
-
 from rich.box import SIMPLE_HEAD
 from rich.table import (
     Column,
     Table,
 )
+from rich.text import Text
 
 from .argparse_custom import (
     ChoicesCallable,
     generate_range_error,
 )
-from .command_definition import CommandSet
 from .completion import (
     CompletionItem,
     Completions,
     all_display_numeric,
 )
+from .constants import INFINITY
 from .exceptions import CompletionError
+from .rich_utils import Cmd2GeneralConsole
 from .styles import Cmd2Style
 
+if TYPE_CHECKING:  # pragma: no cover
+    from .cmd2 import Cmd
+    from .command_definition import CommandSet
+
 # If no table header is supplied, then this will be used instead
 DEFAULT_TABLE_HEADER: Sequence[str | Column] = ['Description']
 
@@ -166,7 +166,7 @@ class ArgparseCompleter:
     def __init__(
         self,
         parser: argparse.ArgumentParser,
-        cmd2_app: 'Cmd',
+        cmd2_app: Cmd,
         *,
         parent_tokens: Mapping[str, MutableSequence[str]] | None = None,
     ) -> None:

cmd2/argparse_custom.py

@@ -261,6 +261,8 @@ def get_choices(self) -> Choices:
 sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser` for more details.
 """
 
+from __future__ import annotations
+
 import argparse
 import re
 import sys
@@ -884,7 +886,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) -> type['ArgparseCompleter'] | None:  # 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.
@@ -900,7 +902,7 @@ def _ArgumentParser_get_ap_completer_type(self: argparse.ArgumentParser) -> type
 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.
@@ -1186,7 +1188,7 @@ def __init__(
         suggest_on_error: bool = False,
         color: bool = False,
         *,
-        ap_completer_type: type['ArgparseCompleter'] | None = None,
+        ap_completer_type: type[ArgparseCompleter] | None = None,
     ) -> None:
         """Initialize the Cmd2ArgumentParser instance, a custom ArgumentParser added by cmd2.
 

cmd2/clipboard.py

@@ -1,5 +1,7 @@
 """Module provides basic ability to copy from and paste to the clipboard/pastebuffer."""
 
+from __future__ import annotations
+
 import typing
 
 import pyperclip  # type: ignore[import-untyped]

cmd2/cmd2.py

@@ -22,10 +22,8 @@
 Documentation: https://cmd2.readthedocs.io/
 """
 
-# This module has many imports, quite a few of which are only
-# infrequently utilized. To reduce the initial overhead of
-# import this module, many of these imports are lazy-loaded
-# i.e. we only import the module when we use it.
+from __future__ import annotations
+
 import argparse
 import contextlib
 import copy
@@ -56,14 +54,13 @@
     dataclass,
     field,
 )
-from types import FrameType
 from typing import (
     IO,
     TYPE_CHECKING,
     Any,
     TextIO,
+    TypeAlias,
     TypeVar,
-    Union,
     cast,
 )
 
@@ -96,7 +93,6 @@
 )
 from . import rich_utils as ru
 from . import string_utils as su
-from .argparse_custom import Cmd2ArgumentParser
 from .clipboard import (
     get_paste_buffer,
     write_to_paste_buffer,
@@ -147,13 +143,6 @@
     RichPrintKwargs,
 )
 from .styles import Cmd2Style
-from .types import (
-    ChoicesProviderUnbound,
-    CmdOrSet,
-    CompleterBound,
-    CompleterUnbound,
-    Matchable,
-)
 
 with contextlib.suppress(ImportError):
     from IPython import start_ipython
@@ -198,6 +187,24 @@ def __init__(self, msg: str = '') -> None:
     suggest_similar,
 )
 
+if TYPE_CHECKING:  # pragma: no cover
+    StaticArgParseBuilder = staticmethod[[], argparse.ArgumentParser]
+    ClassArgParseBuilder = classmethod['Cmd' | CommandSet, [], argparse.ArgumentParser]
+    from types import FrameType
+
+    from .argparse_custom import Cmd2ArgumentParser
+    from .types import (
+        ChoicesProviderUnbound,
+        CmdOrSet,
+        CompleterBound,
+        CompleterUnbound,
+        Matchable,
+    )
+
+else:
+    StaticArgParseBuilder = staticmethod
+    ClassArgParseBuilder = classmethod
+
 
 class _SavedCmd2Env:
     """cmd2 environment settings that are backed up when entering an interactive Python shell."""
@@ -211,21 +218,13 @@ def __init__(self) -> None:
 DisabledCommand = namedtuple('DisabledCommand', ['command_function', 'help_function', 'completer_function'])  # noqa: PYI024
 
 
-if TYPE_CHECKING:  # pragma: no cover
-    StaticArgParseBuilder = staticmethod[[], argparse.ArgumentParser]
-    ClassArgParseBuilder = classmethod['Cmd' | CommandSet, [], argparse.ArgumentParser]
-else:
-    StaticArgParseBuilder = staticmethod
-    ClassArgParseBuilder = classmethod
-
-
 class _CommandParsers:
     """Create and store all command method argument parsers for a given Cmd instance.
 
     Parser creation and retrieval are accomplished through the get() method.
     """
 
-    def __init__(self, cmd: 'Cmd') -> None:
+    def __init__(self, cmd: Cmd) -> None:
         self._cmd = cmd
 
         # Keyed by the fully qualified method names. This is more reliable than
@@ -1005,7 +1004,7 @@ def check_parser_uninstallable(parser: argparse.ArgumentParser) -> None:
                 if command_parser is not None:
                     check_parser_uninstallable(command_parser)
 
-    def _register_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
+    def _register_subcommands(self, cmdset: CommandSet | Cmd) -> None:
         """Register subcommands with their base command.
 
         :param cmdset: CommandSet or cmd2.Cmd subclass containing subcommands
@@ -1098,7 +1097,7 @@ def find_subcommand(
 
                     break
 
-    def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
+    def _unregister_subcommands(self, cmdset: CommandSet | Cmd) -> None:
         """Unregister subcommands from their base command.
 
         :param cmdset: CommandSet containing subcommands
@@ -2195,8 +2194,8 @@ def _determine_ap_completer_type(parser: argparse.ArgumentParser) -> type[argpar
         :param parser: the parser to examine
         :return: type of ArgparseCompleter
         """
-        Completer = type[argparse_completer.ArgparseCompleter] | None  # noqa: N806
-        completer_type: Completer = parser.get_ap_completer_type()  # type: ignore[attr-defined]
+        CompleterType: TypeAlias = type[argparse_completer.ArgparseCompleter] | None
+        completer_type: CompleterType = parser.get_ap_completer_type()  # type: ignore[attr-defined]
 
         if completer_type is None:
             completer_type = argparse_completer.DEFAULT_AP_COMPLETER
@@ -5661,7 +5660,7 @@ def register_cmdfinalization_hook(
     def _resolve_func_self(
         self,
         cmd_support_func: Callable[..., Any],
-        cmd_self: Union[CommandSet, 'Cmd', None],
+        cmd_self: CommandSet | Cmd | None,
     ) -> object | None:
         """Attempt to resolve a candidate instance to pass as 'self'.
 

cmd2/colors.py

@@ -1,5 +1,7 @@
 """Provides a convenient StrEnum for Rich color names."""
 
+from __future__ import annotations
+
 import sys
 
 if sys.version_info >= (3, 11):

cmd2/command_definition.py

@@ -1,5 +1,7 @@
 """Supports the definition of commands in separate classes to be composed into cmd2.Cmd."""
 
+from __future__ import annotations
+
 from collections.abc import (
     Callable,
     Mapping,
@@ -15,10 +17,10 @@
     COMMAND_FUNC_PREFIX,
 )
 from .exceptions import CommandSetRegistrationError
-from .utils import Settable
 
 if TYPE_CHECKING:  # pragma: no cover
     from .cmd2 import Cmd
+    from .utils import Settable
 
 #: Callable signature for a basic command  function
 #: Further refinements are needed to define the input parameters
@@ -98,7 +100,7 @@ def __init__(self) -> None:
         self._settable_prefix = self.__class__.__name__
 
     @property
-    def _cmd(self) -> 'Cmd':
+    def _cmd(self) -> Cmd:
         """Property for child classes to access self.__cmd_internal.
 
         Using this property ensures that self.__cmd_internal has been set
@@ -122,7 +124,7 @@ def _cmd(self) -> CustomCmdApp:
             raise CommandSetRegistrationError('This CommandSet is not registered')
         return self.__cmd_internal
 
-    def on_register(self, cmd: 'Cmd') -> None:
+    def on_register(self, cmd: Cmd) -> None:
         """First step to registering a CommandSet, called by cmd2.Cmd.
 
         The commands defined in this class have not been added to the CLI object at this point.

cmd2/completion.py

@@ -1,18 +1,15 @@
 """Provides classes and functions related to command-line completion."""
 
+from __future__ import annotations
+
 import re
 import sys
-from collections.abc import (
-    Collection,
-    Iterable,
-    Iterator,
-    Sequence,
-)
 from dataclasses import (
     dataclass,
     field,
 )
 from typing import (
+    TYPE_CHECKING,
     Any,
     cast,
     overload,
@@ -28,7 +25,14 @@
 from rich.protocol import is_renderable
 
 from . import rich_utils as ru
-from . import utils
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Collection,
+        Iterable,
+        Iterator,
+        Sequence,
+    )
 
 # Regular expression to identify strings which we should sort numerically
 NUMERIC_RE = re.compile(
@@ -143,6 +147,8 @@ class CompletionResultsBase:
 
     def __post_init__(self) -> None:
         """Finalize the object after initialization."""
+        from . import utils
+
         unique_items = utils.remove_duplicates(self.items)
         if not self.is_sorted:
             if all_display_numeric(unique_items):

cmd2/constants.py

@@ -1,7 +1,10 @@
-"""Constants used throughout ``cmd2``."""
+"""Constants used throughout ``cmd2``.
 
-# Unless documented in https://cmd2.readthedocs.io/en/latest/api/index.html
-# nothing here should be considered part of the public API of this module
+Unless documented in https://cmd2.readthedocs.io/en/latest/api/index.html
+nothing here should be considered part of the public API of this module
+"""
+
+from __future__ import annotations
 
 INFINITY = float('inf')
 

cmd2/decorators.py

@@ -1,5 +1,7 @@
 """Decorators for ``cmd2`` commands."""
 
+from __future__ import annotations
+
 import argparse
 from collections.abc import (
     Callable,
@@ -65,7 +67,7 @@ def cat_decorator(func: CommandFunc) -> CommandFunc:
 # in cmd2 command functions/callables. As long as the 2-ple of arguments we expect to be there can be
 # found we can swap out the statement with each decorator's specific parameters
 ##########################
-def _parse_positionals(args: tuple[Any, ...]) -> tuple['Cmd', Statement | str]:
+def _parse_positionals(args: tuple[Any, ...]) -> tuple[Cmd, Statement | str]:
     """Inspect the positional arguments until the cmd2.Cmd argument is found.
 
     Assumes that we will find cmd2.Cmd followed by the command statement object or string.

cmd2/exceptions.py

@@ -1,5 +1,7 @@
 """Custom exceptions for cmd2."""
 
+from __future__ import annotations
+
 from typing import Any
 
 ############################################################################################################