󰑌 Simplify subcommand integration to one place

Previously, adding a new subcommand required importing it into two
separate Python modules, adding them into two mappings, maintaining
the same dictionary key string. This is prone to human error and is
underintegrated.

This patch makes it easier by defining a required subcommand module
shape on the typing level. Now, one just need to implement two hook-
functions and a constant with specific signatures and import it in
a single place.

Author: webknjaz

src/pre_commit_terraform/README.md

@@ -7,13 +7,13 @@ that ends up being installed into `site-packages/` of virtualenvs.
 
 When the Git repository is `pip install`ed, this [import package] becomes
 available for use within respective Python interpreter instance. It can be
-imported and sub-modules can be imported through the dot-syntax.
-Additionally, the modules within are able to import the neighboring ones
-using relative imports that have a leading dot in them.
+imported and sub-modules can be imported through the dot-syntax. Additionally,
+the modules within can import the neighboring ones using relative imports that
+have a leading dot in them.
 
 It additionally implements a [runpy interface], meaning that its name can
-be passed to `python -m` in order to invoke the CLI. This is the primary method
-of integration with the [`pre-commit` framework] and local development/testing.
+be passed to `python -m` to invoke the CLI. This is the primary method of
+integration with the [`pre-commit` framework] and local development/testing.
 
 The layout allows for having several Python modules wrapping third-party tools,
 each having an argument parser and being a subcommand for the main CLI
@@ -32,12 +32,11 @@ subcommand modules.
 2. Within that module, define two functions —
    `invoke_cli_app(parsed_cli_args: Namespace) -> ReturnCodeType | int` and
    `populate_argument_parser(subcommand_parser: ArgumentParser) -> None`.
-3. Edit [`_cli_parsing.py`], importing `populate_argument_parser` from
-   `subcommand_x` and adding it into `PARSER_MAP` with `subcommand-x` as
-   a key.
-5. Edit [`_cli_subcommands.py`] `invoke_cli_app` from `subcommand_x` and
-   adding it into `SUBCOMMAND_MAP` with `subcommand-x` as a key.
-6. Edit [`.pre-commit-hooks.yaml`], adding a new hook that invokes
+   Additionally, define a module-level constant
+   `CLI_SUBCOMMAND_NAME: Final[str] = 'subcommand-x'`.
+3. Edit [`_cli_subcommands.py`], importing `subcommand_x` as a relative module
+   and add it into the `SUBCOMMAND_MODULES` list.
+4. Edit [`.pre-commit-hooks.yaml`], adding a new hook that invokes
    `python -m pre_commit_terraform subcommand-x`.
 
 ## Manual testing
@@ -53,7 +52,7 @@ POSIX-inspired CLI app.
 
 ## DX/UX considerations
 
-Since it's an app that can be executed outside of the [`pre-commit` framework],
+Since it's an app that can be executed outside the [`pre-commit` framework],
 it is useful to check out and follow these [CLI guidelines][clig].
 
 [`.pre-commit-hooks.yaml`]: ../../.pre-commit-hooks.yaml

src/pre_commit_terraform/_cli.py

@@ -2,7 +2,6 @@
 
 from sys import stderr
 
-from ._cli_subcommands import choose_cli_app
 from ._cli_parsing import initialize_argument_parser
 from ._errors import (
     PreCommitTerraformBaseError,
@@ -21,14 +20,9 @@ def invoke_cli_app(cli_args: list[str]) -> ReturnCodeType:
     """
     root_cli_parser = initialize_argument_parser()
     parsed_cli_args = root_cli_parser.parse_args(cli_args)
-    try:
-        invoke_chosen_app = choose_cli_app(parsed_cli_args.check_name)
-    except LookupError as lookup_err:
-        print(f'Sourcing subcommand failed: {lookup_err !s}', file=stderr)
-        return ReturnCode.ERROR
 
     try:
-        return invoke_chosen_app(parsed_cli_args)
+        return parsed_cli_args.invoke_cli_app(parsed_cli_args)
     except PreCommitTerraformExit as exit_err:
         print(f'App exiting: {exit_err !s}', file=stderr)
         raise

src/pre_commit_terraform/_cli_parsing.py

@@ -6,14 +6,7 @@
 
 from argparse import ArgumentParser
 
-from .terraform_docs_replace import (
-    populate_argument_parser as populate_replace_docs_argument_parser,
-)
-
-
-PARSER_MAP = {
-    'replace-docs': populate_replace_docs_argument_parser,
-}
+from ._cli_subcommands import SUBCOMMAND_MODULES
 
 
 def attach_subcommand_parsers_to(root_cli_parser: ArgumentParser, /) -> None:
@@ -28,9 +21,12 @@ def attach_subcommand_parsers_to(root_cli_parser: ArgumentParser, /) -> None:
         help='A check to be performed.',
         required=True,
     )
-    for subcommand_name, initialize_subcommand_parser in PARSER_MAP.items():
-        replace_docs_parser = subcommand_parsers.add_parser(subcommand_name)
-        initialize_subcommand_parser(replace_docs_parser)
+    for subcommand_module in SUBCOMMAND_MODULES:
+        replace_docs_parser = subcommand_parsers.add_parser(subcommand_module.CLI_SUBCOMMAND_NAME)
+        replace_docs_parser.set_defaults(
+            invoke_cli_app=subcommand_module.invoke_cli_app,
+        )
+        subcommand_module.populate_argument_parser(replace_docs_parser)
 
 
 def initialize_argument_parser() -> ArgumentParser:

src/pre_commit_terraform/_cli_subcommands.py

@@ -1,31 +1,12 @@
 """A CLI sub-commands organization module."""
 
-from argparse import Namespace
-from typing import Callable
+from . import terraform_docs_replace
+from ._types import CLISubcommandModuleProtocol
 
-from ._structs import ReturnCode
-from .terraform_docs_replace import (
-    invoke_cli_app as invoke_replace_docs_cli_app,
-)
 
+SUBCOMMAND_MODULES: list[CLISubcommandModuleProtocol] = [
+    terraform_docs_replace,
+]
 
-SUBCOMMAND_MAP = {
-    'replace-docs': invoke_replace_docs_cli_app,
-}
 
-
-def choose_cli_app(
-        check_name: str,
-        /,
-) -> Callable[[Namespace], ReturnCode | int]:
-    """Return a subcommand callable by CLI argument name."""
-    try:
-        return SUBCOMMAND_MAP[check_name]
-    except KeyError as key_err:
-        raise LookupError(
-            f'{key_err !s}: Unable to find a callable for '
-            f'the `{check_name !s}` subcommand',
-        ) from key_err
-
-
-__all__ = ('choose_cli_app',)
+__all__ = ('SUBCOMMAND_MODULES',)

src/pre_commit_terraform/_types.py

@@ -1,6 +1,30 @@
 """Composite types for annotating in-project code."""
 
+from argparse import ArgumentParser, Namespace
+from typing import Final, Protocol
+
 from ._structs import ReturnCode
 
 
 ReturnCodeType = ReturnCode | int
+
+
+class CLISubcommandModuleProtocol(Protocol):
+    """A protocol for the subcommand-implementing module shape."""
+
+    CLI_SUBCOMMAND_NAME: Final[str]
+    """This constant contains a CLI."""
+
+    def populate_argument_parser(
+            self, subcommand_parser: ArgumentParser,
+    ) -> None:
+        """Run a module hook for populating the subcommand parser."""
+
+    def invoke_cli_app(
+            self, parsed_cli_args: Namespace,
+    ) -> ReturnCodeType | int:
+        """Run a module hook implementing the subcommand logic."""
+        ...  # pylint: disable=unnecessary-ellipsis
+
+
+__all__ = ('CLISubcommandModuleProtocol', 'ReturnCodeType')

src/pre_commit_terraform/terraform_docs_replace.py

@@ -2,11 +2,15 @@
 import subprocess
 import warnings
 from argparse import ArgumentParser, Namespace
+from typing import Final
 
 from ._structs import ReturnCode
 from ._types import ReturnCodeType
 
 
+CLI_SUBCOMMAND_NAME: Final[str] = 'replace-docs'
+
+
 def populate_argument_parser(subcommand_parser: ArgumentParser) -> None:
     subcommand_parser.description = (
         'Run terraform-docs on a set of files. Follows the standard '