Hooks
=====

Cookiecutter hooks are scripts executed at specific stages during the project generation process. They are either Python or shell scripts, facilitating automated tasks like data validation, pre-processing, and post-processing. These hooks are instrumental in customizing the generated project structure and executing initial setup tasks.

Types of Hooks
--------------

+------------------+------------------------------------------+------------------------------------------+--------------------+----------+
| Hook             | Execution Timing                         | Working Directory                        | Template Variables | Version  |
+==================+==========================================+==========================================+====================+==========+
| pre_prompt       | Before any question is rendered.         | A copy of the repository directory       | No                 | 2.4.0    |
+------------------+------------------------------------------+------------------------------------------+--------------------+----------+
| pre_gen_project  | After questions, before template process.| Root of the generated project            | Yes                | 0.7.0    |
+------------------+------------------------------------------+------------------------------------------+--------------------+----------+
| post_gen_project | After the project generation.            | Root of the generated project            | Yes                | 0.7.0    |
+------------------+------------------------------------------+------------------------------------------+--------------------+----------+

Creating Hooks
--------------

Hooks are added to the ``hooks/`` folder of your template. Both Python and Shell scripts are supported.

**Python Hooks Structure:**

.. code-block::

    cookiecutter-something/
    ├── {{cookiecutter.project_slug}}/
    ├── hooks
    │   ├── pre_prompt.py
    │   ├── pre_gen_project.py
    │   └── post_gen_project.py
    └── cookiecutter.json

**Shell Scripts Structure:**

.. code-block::

    cookiecutter-something/
    ├── {{cookiecutter.project_slug}}/
    ├── hooks
    │   ├── pre_prompt.sh
    │   ├── pre_gen_project.sh
    │   └── post_gen_project.sh
    └── cookiecutter.json

Python scripts are recommended for cross-platform compatibility. However, shell scripts or `.bat` files can be used for platform-specific templates.

Hook Execution
--------------

Hooks should be robust and handle errors gracefully. If a hook exits with a nonzero status, the project generation halts, and the generated directory is cleaned.

**Working Directory:**

* ``pre_prompt``: Scripts run in the root directory of a copy of the repository directory. That allows the rewrite of ``cookiecutter.json`` to your own needs.

* ``pre_gen_project`` and ``post_gen_project``: Scripts run in the root directory of the generated project, simplifying the process of locating generated files using relative paths.

**Template Variables:**

The ``pre_gen_project`` and ``post_gen_project`` hooks support Jinja template rendering, similar to project templates. For instance:

.. code-block:: python

    module_name = '{{ cookiecutter.module_name }}'

Examples
--------

**Pre-Prompt Sanity Check:**

A ``pre_prompt`` hook, like the one below in ``hooks/pre_prompt.py``, ensures prerequisites, such as Docker, are installed before prompting the user.

.. code-block:: python

    import sys
    import subprocess

    def is_docker_installed() -> bool:
        try:
            subprocess.run(["docker", "--version"], capture_output=True, check=True)
            return True
        except Exception:
            return False

    if __name__ == "__main__":
        if not is_docker_installed():
            print("ERROR: Docker is not installed.")
            sys.exit(1)

**Validating Template Variables:**

A ``pre_gen_project`` hook can validate template variables. The following script checks if the provided module name is valid.

.. code-block:: python

    import re
    import sys

    MODULE_REGEX = r'^[_a-zA-Z][_a-zA-Z0-9]+$'
    module_name = '{{ cookiecutter.module_name }}'

    if not re.match(MODULE_REGEX, module_name):
        print(f'ERROR: {module_name} is not a valid Python module name!')
        sys.exit(1)

**Conditional File/Directory Removal:**

A ``post_gen_project`` hook can conditionally control files and directories. The example below removes unnecessary files based on the selected packaging option.

.. code-block:: python

    import os

    REMOVE_PATHS = [
        '{% if cookiecutter.packaging != "pip" %}requirements.txt{% endif %}',
        '{% if cookiecutter.packaging != "poetry" %}poetry.lock{% endif %}',
    ]

    for path in REMOVE_PATHS:
        path = path.strip()
        if path and os.path.exists(path):
            os.unlink(path) if os.path.isfile(path) else os.rmdir(path)