chore: Backpush to main changes to skeleton of python hooks

.github/CONTRIBUTING.md

@@ -18,6 +18,7 @@ Enjoy the clean, valid, and documented code!
   * [Prepare basic documentation](#prepare-basic-documentation)
   * [Add code](#add-code)
   * [Finish with the documentation](#finish-with-the-documentation)
+* [Testing python hooks](#testing-python-hooks)
 
 ## Run and debug hooks locally
 
@@ -154,3 +155,27 @@ You can use [this PR](https://github.com/antonbabenko/pre-commit-terraform/pull/
 
 1. Add hook description to [Available Hooks](../README.md#available-hooks).
 2. Create and populate a new hook section in [Hooks usage notes and examples](../README.md#hooks-usage-notes-and-examples).
+
+
+## Testing python hooks
+
+To run tests, you need:
+
+```bash
+pip install pytest pytest-mock
+
+pytest -vv
+```
+
+To run and debug hooks as CLI:
+
+1. Create [`venv`](https://docs.python.org/3/library/venv.html) and activate it, IE by `virtualenv venv`
+2. Inside virtual env install pre-commit-terraform as package:
+	```bash
+	pip install --editable .
+	```
+
+3. Run next to show basic help:
+	```bash
+	python -Im pre_commit_terraform --help
+	```

.github/workflows/pre-commit.yaml

@@ -38,7 +38,7 @@ jobs:
     # Skip terraform_tflint which interferes to commit pre-commit auto-fixes
     - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
       with:
-        python-version: '3.9'
+        python-version: '3.10'
     - name: Execute pre-commit
       uses: pre-commit/action@9b88afc9cd57fd75b655d5c71bd38146d07135fe # v2.0.3
       env:

.gitignore

@@ -1 +1,4 @@
 tests/results/*
+__pycache__/
+*.py[cod]
+node_modules/

.pre-commit-config.yaml

@@ -45,7 +45,7 @@ repos:
 
 # Dockerfile linter
 - repo: https://github.com/hadolint/hadolint
-  rev: v2.12.1-beta
+  rev: v2.13.1-beta
   hooks:
     - id: hadolint
       args: [
@@ -61,8 +61,99 @@ repos:
 
 # JSON5 Linter
 - repo: https://github.com/pre-commit/mirrors-prettier
-  rev: v3.1.0
+  rev: v4.0.0-alpha.8
   hooks:
   - id: prettier
     # https://prettier.io/docs/en/options.html#parser
     files: '.json5$'
+
+
+##########
+# PYTHON #
+##########
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.8.4
+  hooks:
+    - id: ruff
+      args: [--fix]
+      types_or: [python, pyi]
+    - id: ruff-format
+      types_or: [python, pyi]
+      args: [--config, format.quote-style = 'single', --config, line-length = 100]
+
+- repo: https://github.com/pycqa/isort
+  rev: 5.13.2
+  hooks:
+    - id: isort
+      name: isort
+      args: [--force-single-line, --profile=black]
+      exclude: |
+        (?x)
+          # It set wrong indent in imports in place where it shouldn't
+          # https://github.com/PyCQA/isort/issues/2315#issuecomment-2566703698
+          (^tests/pytest/test__cli_subcommands.py$
+        )
+
+- repo: https://github.com/asottile/add-trailing-comma
+  rev: v3.1.0
+  hooks:
+    - id: add-trailing-comma
+
+- repo: https://github.com/pre-commit/mirrors-autopep8
+  rev: v2.0.4
+  hooks:
+    - id: autopep8
+      args:
+      - -i
+      - --max-line-length=100
+
+# Usage: http://pylint.pycqa.org/en/latest/user_guide/message-control.html
+- repo: https://github.com/PyCQA/pylint
+  rev: v3.3.3
+  hooks:
+    - id: pylint
+      args:
+      - --disable=import-error # E0401. Locally you could not have all imports.
+      - --disable=fixme # W0511. 'TODO' notations.
+      - --disable=logging-fstring-interpolation # Conflict with "use a single formatting" WPS323
+      - --disable=ungrouped-imports # ignore `if TYPE_CHECKING` case. Other do reorder-python-imports
+      - --disable=R0801 # Similar lines in 2 files. Currently I don't think that it possible to DRY hooks unique files boilerplate
+
+      exclude: test_.+\.py$
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v1.14.1
+  hooks:
+    - id: mypy
+      additional_dependencies:
+          - types-PyYAML
+      args: [
+        --ignore-missing-imports,
+        --disallow-untyped-calls,
+        --warn-redundant-casts,
+      ]
+
+- repo: https://github.com/wemake-services/wemake-python-styleguide
+  rev: 1.0.0
+  hooks:
+    - id: wemake-python-styleguide
+      args:
+      - --allowed-module-metadata=__all__ # Default to ''
+      - --max-local-variables=6 # Default to 5
+      - --max-returns=6 # Default to 5
+      - --max-imports=15 # Default to 12
+      # https://wemake-python-stylegui.de/en/latest/pages/usage/violations/index.html
+      - --extend-ignore=
+          E501   <!-- line too long (> 79 characters). Use 100 -->
+          WPS115 <!-- Found upper-case constant in a class. All occurrences are false positive -->
+          WPS226 <!-- Found string literal over-use - append > 3 -->
+
+
+      exclude: |
+        (?x)
+          # Ignore tests
+          (^tests/pytest/test_.+\.py$
+          # Ignore deprecated hook
+          |^src/pre_commit_terraform/terraform_docs_replace.py$
+        )

.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: python -Im pre_commit_terraform replace-docs
+  entry: python -Im pre_commit_terraform terraform_docs_replace
   language: python
   files: (\.tf)$
   exclude: \.terraform/.*$

.vscode/settings.json

@@ -7,4 +7,7 @@
     "code-block-style": false
   },
   "markdown.validate.enabled": true,
+  "python.analysis.extraPaths": [
+    "./src"
+  ],
 }

hatch.toml

@@ -1,5 +1,6 @@
 [build.targets.sdist]
 include = [
+  '.pre-commit-hooks.yaml',
   'src/',
 ]
 
@@ -8,6 +9,9 @@ packages = [
   'src/pre_commit_terraform/',
 ]
 
+[build.targets.wheel.force-include]
+'.pre-commit-hooks.yaml' = 'pre_commit_terraform/_artifacts/.pre-commit-hooks.yaml'
+
 [metadata.hooks.vcs.urls]
 'Source Archive' = 'https://github.com/antonbabenko/pre-commit-terraform/archive/{commit_hash}.tar.gz'
 'GitHub: repo' = 'https://github.com/antonbabenko/pre-commit-terraform'

pyproject.toml

@@ -9,16 +9,15 @@ build-backend = 'hatchling.build'
 name = 'pre-commit-terraform'
 classifiers = [
   'License :: OSI Approved :: MIT License',
-  'Programming Language :: Python :: 2',
-  'Programming Language :: Python :: 2.7',
   'Programming Language :: Python :: 3',
-  'Programming Language :: Python :: 3.6',
-  'Programming Language :: Python :: 3.7',
+  'Programming Language :: Python :: 3 :: Only',
   'Programming Language :: Python :: Implementation :: CPython',
   'Programming Language :: Python :: Implementation :: PyPy',
 ]
-description = 'Pre-commit hooks for terraform_docs_replace'
-dependencies = []
+description='Pre-commit hooks for terraform'
+dependencies = [
+  'pyyaml',
+]
 dynamic = [
   'urls',
   'version',

pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+pythonpath = src
+
+testpaths =
+    tests/pytest

src/pre_commit_terraform/__main__.py

@@ -1,9 +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
+from sys import argv
+from sys import exit as exit_with_return_code
 
+from pre_commit_terraform._cli import invoke_cli_app
 
 return_code = invoke_cli_app(argv[1:])
 exit_with_return_code(return_code)

src/pre_commit_terraform/_cli.py

@@ -2,14 +2,12 @@
 
 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
+from pre_commit_terraform._cli_parsing import initialize_argument_parser
+from pre_commit_terraform._errors import PreCommitTerraformBaseError
+from pre_commit_terraform._errors import PreCommitTerraformExit
+from pre_commit_terraform._errors import PreCommitTerraformRuntimeError
+from pre_commit_terraform._structs import ReturnCode
+from pre_commit_terraform._types import ReturnCodeType
 
 
 def invoke_cli_app(cli_args: list[str]) -> ReturnCodeType:
@@ -21,15 +19,14 @@ 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:
+    try:  # noqa: WPS225 - Found too many `except` cases: 4 > 3
         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...',
+            f'App execution took an unexpected turn: {unhandled_exc !s}. Exiting...',
             file=stderr,
         )
         return ReturnCode.ERROR

src/pre_commit_terraform/_cli_parsing.py

@@ -6,7 +6,50 @@
 
 from argparse import ArgumentParser
 
-from ._cli_subcommands import SUBCOMMAND_MODULES
+from pre_commit_terraform._cli_subcommands import SUBCOMMAND_MODULES
+
+
+def populate_common_argument_parser(parser: ArgumentParser) -> None:
+    """
+    Populate the argument parser with the common arguments.
+
+    Args:
+        parser (argparse.ArgumentParser): The argument parser to populate.
+    """
+    parser.add_argument(
+        '-a',
+        '--args',
+        action='append',
+        help='Arguments that configure wrapped tool behavior',
+        default=[],
+    )
+    parser.add_argument(
+        '-h',
+        '--hook-config',
+        action='append',
+        metavar='KEY=VALUE',
+        help='Arguments that configure hook behavior',
+        default=[],
+    )
+    parser.add_argument(
+        '-i',
+        '--tf-init-args',
+        '--init-args',
+        action='append',
+        help='Arguments for `tf init` command',
+        default=[],
+    )
+    parser.add_argument(
+        '-e',
+        '--env-vars',
+        '--envs',
+        dest='env_vars_strs',
+        metavar='KEY=VALUE',
+        action='append',
+        help='Setup additional Environment Variables during hook execution',
+        default=[],
+    )
+    parser.add_argument('files', nargs='*', help='Changed files paths')
 
 
 def attach_subcommand_parsers_to(root_cli_parser: ArgumentParser, /) -> None:
@@ -18,19 +61,27 @@ def attach_subcommand_parsers_to(root_cli_parser: ArgumentParser, /) -> None:
     """
     subcommand_parsers = root_cli_parser.add_subparsers(
         dest='check_name',
-        help='A check to be performed.',
         required=True,
     )
     for subcommand_module in SUBCOMMAND_MODULES:
-        subcommand_parser = subcommand_parsers.add_parser(subcommand_module.CLI_SUBCOMMAND_NAME)
+        subcommand_parser = subcommand_parsers.add_parser(
+            subcommand_module.HOOK_ID,
+            add_help=False,
+        )
         subcommand_parser.set_defaults(
             invoke_cli_app=subcommand_module.invoke_cli_app,
         )
-        subcommand_module.populate_argument_parser(subcommand_parser)
+        populate_common_argument_parser(subcommand_parser)
+        subcommand_module.populate_hook_specific_argument_parser(subcommand_parser)
 
 
 def initialize_argument_parser() -> ArgumentParser:
-    """Return the root argument parser with sub-commands."""
+    """
+    Parse the command line arguments and return the parsed arguments.
+
+    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

src/pre_commit_terraform/_cli_subcommands.py

@@ -1,12 +1,9 @@
 """A CLI sub-commands organization module."""
 
-from . import terraform_docs_replace
-from ._types import CLISubcommandModuleProtocol
+from pre_commit_terraform import terraform_docs_replace
+from pre_commit_terraform._types import CLISubcommandModuleProtocol
 
-
-SUBCOMMAND_MODULES: list[CLISubcommandModuleProtocol] = [
-    terraform_docs_replace,
-]
+SUBCOMMAND_MODULES: tuple[CLISubcommandModuleProtocol, ...] = (terraform_docs_replace,)
 
 
 __all__ = ('SUBCOMMAND_MODULES',)