chore(refactoring): Introduce a Python CLI app layout

.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

@@ -41,6 +41,3 @@ email = 'yz@yz.kiev.ua'
 [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/README.md

@@ -0,0 +1,93 @@
+# Maintainer's manual
+
+## Structure
+
+This folder is what's called an [importable package]. It's a top-level folder
+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 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` 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
+interface.
+
+## Control flow
+
+When `python -m pre_commit_terraform` is executed, it imports `__main__.py`.
+Which in turn, performs the initialization of the main argument parser and the
+parsers of subcommands, followed by executing the logic defined in dedicated
+subcommand modules.
+
+## Integrating a new subcommand
+
+1. Create a new module called `subcommand_x.py`.
+2. Within that module, define two functions —
+   `invoke_cli_app(parsed_cli_args: Namespace) -> ReturnCodeType | int` and
+   `populate_argument_parser(subcommand_parser: ArgumentParser) -> None`.
+   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
+
+Usually, having a development virtualenv where you `pip install -e .` is enough
+to make it possible to invoke the CLI app. Do so first. Most source code
+updates do not require running it again. But sometimes, it's needed.
+
+Once done, you can run `python -m pre_commit_terraform` and/or
+`python -m pre_commit_terraform subcommand-x` to see how it behaves. There's
+`--help` and all other typical conventions one would usually expect from a
+POSIX-inspired CLI app.
+
+## DX/UX considerations
+
+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].
+
+## Subcommand development
+
+`populate_argument_parser()` accepts a regular instance of
+[`argparse.ArgumentParser`]. Call its methods to extend the CLI arguments that
+would be specific for the subcommand you are creating. Those arguments will be
+available later, as an argument to the `invoke_cli_app()` function — through an
+instance of [`argparse.Namespace`]. For the `CLI_SUBCOMMAND_NAME` constant,
+choose `kebab-space-sub-command-style`, it does not need to be `snake_case`.
+
+Make sure to return a `ReturnCode` instance or an integer from
+`invoke_cli_app()`. Returning a non-zero value will result in the CLI app
+exiting with a return code typically interpreted as an error while zero means
+success. You can `import errno` to use typical POSIX error codes through their
+human-readable identifiers.
+
+Another way to interrupt the CLI app control flow is by raising an instance of
+one of the in-app errors. `raise PreCommitTerraformExit` for a successful exit,
+but it can be turned into an error outcome via
+`raise PreCommitTerraformExit(1)`.
+`raise PreCommitTerraformRuntimeError('The world is broken')` to indicate
+problems within the runtime. The framework will intercept any exceptions
+inheriting `PreCommitTerraformBaseError`, so they won't be presented to the
+end-users.
+
+[`.pre-commit-hooks.yaml`]: ../../.pre-commit-hooks.yaml
+[`_cli_parsing.py`]: ./_cli_parsing.py
+[`_cli_subcommands.py`]: ./_cli_subcommands.py
+[`argparse.ArgumentParser`]:
+https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser
+[`argparse.Namespace`]:
+https://docs.python.org/3/library/argparse.html#argparse.Namespace
+[clig]: https://clig.dev
+[importable package]: https://docs.python.org/3/tutorial/modules.html#packages
+[import package]: https://packaging.python.org/en/latest/glossary/#term-Import-Package
+[`pre-commit` framework]: https://pre-commit.com
+[runpy interface]: https://docs.python.org/3/library/__main__.html

src/pre_commit_terraform/__main__.py

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

src/pre_commit_terraform/_cli.py

@@ -0,0 +1,50 @@
+"""Outer CLI layer of the app interface."""
+
+from sys import stderr
+
+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:
+        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
+    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,39 @@
+"""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 ._cli_subcommands import SUBCOMMAND_MODULES
+
+
+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_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:
+    """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,12 @@
+"""A CLI sub-commands organization module."""
+
+from . import terraform_docs_replace
+from ._types import CLISubcommandModuleProtocol
+
+
+SUBCOMMAND_MODULES: list[CLISubcommandModuleProtocol] = [
+    terraform_docs_replace,
+]
+
+
+__all__ = ('SUBCOMMAND_MODULES',)

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,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

@@ -1,33 +1,46 @@
-import argparse
 import os
 import subprocess
-import sys
 import warnings
+from argparse import ArgumentParser, Namespace
+from typing import Final
 
+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."""
+
+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 '
+        '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 +50,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())