💅 Introduce a Python CLI app layout

This includes a structure with purpose-based modules and a standard
mechanism for adding more subcommands.

When adding a new subcommand, one has to wire the `invoke_cli_app()`
and `populate_argument_parser()` from their new module into the
mappings defined in `_cli_subcommands.py` and `_cli_parsing.py`
respectively. This is the only integration point necessary.

`populate_argument_parser()` accepts a subparser instance of
`argparse.ArgumentParser()` that a new subcommand would need to attach
new arguments into. It does not need to return anything. And the
`invoke_cli_app()` hook is called with an instance of
`argparse.Namespace()` with all the arguments parsed and pre-processed.
This function is supposed to have the main check logic and return an
instance of `._structs.ReturnCode()` or `int`.

Author: webknjaz

.pre-commit-hooks.yaml

@@ -37,7 +37,7 @@
   name: Terraform docs (overwrite README.md)
   description: Overwrite content of README.md with terraform-docs.
   require_serial: true
-  entry: terraform_docs_replace
+  entry: python -Im pre_commit_terraform replace-docs
   language: python
   files: (\.tf)$
   exclude: \.terraform/.*$

pyproject.toml

@@ -31,6 +31,3 @@ name = 'Contributors'  # FIXME
 [project.readme]
 file = 'README.md'
 content-type = 'text/markdown'
-
-[project.scripts]
-terraform_docs_replace = 'pre_commit_terraform.terraform_docs_replace:main'

src/pre_commit_terraform/__main__.py

@@ -0,0 +1,10 @@
+"""A runpy-style CLI entry-point module."""
+
+from sys import argv, exit as exit_with_return_code
+
+from ._cli import invoke_cli_app
+
+
+if __name__ == '__main__':
+    return_code = invoke_cli_app(argv[1:])
+    exit_with_return_code(return_code)

src/pre_commit_terraform/_cli.py

@@ -0,0 +1,56 @@
+"""Outer CLI layer of the app interface."""
+
+from sys import stderr
+
+from ._cli_subcommands import choose_cli_app
+from ._cli_parsing import initialize_argument_parser
+from ._errors import (
+    PreCommitTerraformBaseError,
+    PreCommitTerraformExit,
+    PreCommitTerraformRuntimeError,
+)
+from ._structs import ReturnCode
+from ._types import ReturnCodeType
+
+
+def invoke_cli_app(cli_args: list[str]) -> ReturnCodeType:
+    """Run the entry-point of the CLI app.
+
+    Includes initializing parsers of all the sub-apps and
+    choosing what to execute.
+    """
+    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)
+    except PreCommitTerraformExit as exit_err:
+        print(f'App exiting: {exit_err !s}', file=stderr)
+        raise
+    except PreCommitTerraformRuntimeError as unhandled_exc:
+        print(
+            f'App execution took an unexpected turn: {unhandled_exc !s}. '
+            'Exiting...',
+            file=stderr,
+        )
+        return ReturnCode.ERROR
+    except PreCommitTerraformBaseError as unhandled_exc:
+        print(
+            f'A surprising exception happened: {unhandled_exc !s}. Exiting...',
+            file=stderr,
+        )
+        return ReturnCode.ERROR
+    except KeyboardInterrupt as ctrl_c_exc:
+        print(
+            f'User-initiated interrupt: {ctrl_c_exc !s}. Exiting...',
+            file=stderr,
+        )
+        return ReturnCode.ERROR
+
+
+__all__ = ('invoke_cli_app',)

src/pre_commit_terraform/_cli_parsing.py

@@ -0,0 +1,43 @@
+"""Argument parser initialization logic.
+
+This defines helpers for setting up both the root parser and the parsers
+of all the sub-commands.
+"""
+
+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,
+}
+
+
+def attach_subcommand_parsers_to(root_cli_parser: ArgumentParser, /) -> None:
+    """Connect all sub-command parsers to the given one.
+
+    This functions iterates over a mapping of subcommands to their
+    respective population functions, executing them to augment the
+    main parser.
+    """
+    subcommand_parsers = root_cli_parser.add_subparsers(
+        dest='check_name',
+        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)
+
+
+def initialize_argument_parser() -> ArgumentParser:
+    """Return the root argument parser with sub-commands."""
+    root_cli_parser = ArgumentParser(prog=f'python -m {__package__ !s}')
+    attach_subcommand_parsers_to(root_cli_parser)
+    return root_cli_parser
+
+
+__all__ = ('initialize_argument_parser',)

src/pre_commit_terraform/_cli_subcommands.py

@@ -0,0 +1,31 @@
+"""A CLI sub-commands organization module."""
+
+from argparse import Namespace
+from typing import Callable
+
+from ._structs import ReturnCode
+from .terraform_docs_replace import (
+    invoke_cli_app as invoke_replace_docs_cli_app,
+)
+
+
+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',)

src/pre_commit_terraform/_errors.py

@@ -0,0 +1,16 @@
+"""App-specific exceptions."""
+
+
+class PreCommitTerraformBaseError(Exception):
+    """Base exception for all the in-app errors."""
+
+
+class PreCommitTerraformRuntimeError(
+        PreCommitTerraformBaseError,
+        RuntimeError,
+):
+    """An exception representing a runtime error condition."""
+
+
+class PreCommitTerraformExit(PreCommitTerraformBaseError, SystemExit):
+    """An exception for terminating execution from deep app layers."""

src/pre_commit_terraform/_structs.py

@@ -0,0 +1,16 @@
+"""Data structures to be reused across the app."""
+
+from enum import IntEnum
+
+
+class ReturnCode(IntEnum):
+    """POSIX-style return code values.
+
+    To be used in check callable implementations.
+    """
+
+    OK = 0
+    ERROR = 1
+
+
+__all__ = ('ReturnCode',)

src/pre_commit_terraform/_types.py

@@ -0,0 +1,6 @@
+"""Composite types for annotating in-project code."""
+
+from ._structs import ReturnCode
+
+
+ReturnCodeType = ReturnCode | int

src/pre_commit_terraform/terraform_docs_replace.py

@@ -1,33 +1,42 @@
-import argparse
 import os
 import subprocess
-import sys
 import warnings
+from argparse import ArgumentParser, Namespace
 
+from ._structs import ReturnCode
+from ._types import ReturnCodeType
 
-def main(argv=None):
-    parser = argparse.ArgumentParser(
-        description="""Run terraform-docs on a set of files. Follows the standard convention of
-                       pulling the documentation from main.tf in order to replace the entire
-                       README.md file each time."""
+
+def populate_argument_parser(subcommand_parser: ArgumentParser) -> None:
+    subcommand_parser.description = (
+        'Run terraform-docs on a set of files. Follows the standard '
+        'convention of pulling the documentation from main.tf in order to '
+        'replace the entire README.md file each time.'
     )
-    parser.add_argument(
+    subcommand_parser.add_argument(
         '--dest', dest='dest', default='README.md',
     )
-    parser.add_argument(
+    subcommand_parser.add_argument(
         '--sort-inputs-by-required', dest='sort', action='store_true',
         help='[deprecated] use --sort-by-required instead',
     )
-    parser.add_argument(
+    subcommand_parser.add_argument(
         '--sort-by-required', dest='sort', action='store_true',
     )
-    parser.add_argument(
-        '--with-aggregate-type-defaults', dest='aggregate', action='store_true',
+    subcommand_parser.add_argument(
+        '--with-aggregate-type-defaults',
+        dest='aggregate',
+        action='store_true',
         help='[deprecated]',
     )
-    parser.add_argument('filenames', nargs='*', help='Filenames to check.')
-    args = parser.parse_args(argv)
+    subcommand_parser.add_argument(
+        'filenames',
+        nargs='*',
+        help='Filenames to check.',
+    )
+
 
+def invoke_cli_app(parsed_cli_args: Namespace) -> ReturnCodeType:
     warnings.warn(
         '`terraform_docs_replace` hook is DEPRECATED.'
         'For migration instructions see '
@@ -37,29 +46,28 @@ def main(argv=None):
     )
 
     dirs = []
-    for filename in args.filenames:
+    for filename in parsed_cli_args.filenames:
         if (os.path.realpath(filename) not in dirs and
                 (filename.endswith(".tf") or filename.endswith(".tfvars"))):
             dirs.append(os.path.dirname(filename))
 
-    retval = 0
+    retval = ReturnCode.OK
 
     for dir in dirs:
         try:
             procArgs = []
             procArgs.append('terraform-docs')
-            if args.sort:
+            if parsed_cli_args.sort:
                 procArgs.append('--sort-by-required')
             procArgs.append('md')
             procArgs.append("./{dir}".format(dir=dir))
             procArgs.append('>')
-            procArgs.append("./{dir}/{dest}".format(dir=dir, dest=args.dest))
+            procArgs.append(
+                './{dir}/{dest}'.
+                format(dir=dir, dest=parsed_cli_args.dest),
+            )
             subprocess.check_call(" ".join(procArgs), shell=True)
         except subprocess.CalledProcessError as e:
             print(e)
-            retval = 1
+            retval = ReturnCode.ERROR
     return retval
-
-
-if __name__ == '__main__':
-    sys.exit(main())