DEV Community: Jorge Alvarado

Create your own pre-commit hook

Jorge Alvarado — Wed, 23 Feb 2022 15:31:49 +0000

In this tutorial we are going to create a very basic git hook, using the awesome package pre-commit, created by the one and only Anthony Sottile 👏👏.

The hook will be very basic. It won't have unit-tests nor will be very functional for a real project. Although it will show you the first steps you need to take in order to create something incredible.

I recommend you using a virtual environment to follow this tutorial.

Tutorial Index

Create the structure of the project
Create the functionality
Turn it into a python package
Turn it into a hook
Test it

1. Create the structure of the project

Create the following project structure:

.
├── test-the-hook-in-this-folder
└── the-hook
    ├── print_arguments
    │   ├── __init__.py
    │   └── main.py
    ├── setup.cfg
    └── setup.py

test-the-hook-in-this-folder: Folder in which we will test our hook by the end of the tutorial (we won't use it until step 5).
the-hook: Folder that contains all the files required for the package.
print_arguments: This is our python package (and also a spoiler of what our hook will do).
__init__.py: Turn the folder that contains it into a package.
main.py: Here is where the logic of the hook will be.
setup.py: Necessary for building our package.
setup.cfg: Describe our package.

2. Create the functionality

We will work in the the-hook folder for steps 2 to 4.

For creating the functionality, we only need to edit the main.py file:

# print_arguments/main.py
import argparse


def print_arguments(arguments: list[str]):
    for argument in arguments:
        print(argument)


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("filenames", nargs="*")
    args = parser.parse_args()

    print_arguments(args.filenames)


if __name__ == "__main__":
    main()

Yes, our hook will print the arguments we pass to it. We can test its functionality:

python print_arguments/main.py arg1 arg2 arg3

Output:

arg1
arg2
arg3

3. Turn it into a python package

To do this, we need to edit our 2 setup files.

setup.py:

# setup.py
from setuptools import setup

setup()

setup.cfg:

# setup.cfg
[metadata]
name = print-arguments
description = print the arguments you pass
version = 0.1.0
author = Jorge Alvarado
author_email = alvaradosegurajorge@gmail.com
license = MIT
url = https://jorgealvarado.me

[options]
packages = find:

[options.entry_points]
console_scripts =
    print-arguments = print_arguments.main:main

Important points:

packages = find:: It help us find our print_arguments package when packaging.
console_scripts: This is our entry point, with this we kind of expose our function to the world. The name of our single entry point, in this case print-arguments, will be used by pre-commit.

You can choose other values for the rest of the points.

Install the package with:

pip install .

Make sure you are in the-hook folder when running that command.

4. Turn it into a hook

For our hook to work we need our project to be a git repository. So let's do that by running the following commands (make sure you are in the the-hook folder):

Initialize the git repository:

git init

Add every file and commit them:

git add .; git commit -m "Create the package"

Now the hook part. First let's install pre-commit:

pip install pre-commit

Create a .pre-commit-hooks.yaml file inside the the-hook folder and edit it:

# .pre-commit-hooks.yaml
- id: some-id
  name: some-name
  description: some description
  entry: print-arguments
  language: python

id: The id of our hook. We will need it for testing and in the future if someone wants to use our hook, the id will be required.
name: The name of the hook, it is what is shown during hook execution.
description (optional): Description of the hook.
entry: The entry point, the executable to run. It has to match with the entry point name defined inside our setup.cfg.
language: The language of the hook, it tells pre-commit how to install the hook.

👀 See a complete list of the options.

To complete this step, we need to do a commit of our hook stuff:

git add .; git commit -m "Create a hook"

5. Test it

Time to use the test-the-hook-in-this-folder folder. Change directory to that folder, once there, let's create a very little git project:

Create some files

touch a.py b.py

Initialize the git repository:

git init

Commit the files:

git add .; git commit -m "Create the project"

Finally, let's test our hook:

pre-commit try-repo ../the-hook some-id --verbose --all-files

Output:

some-name................................................................Passed
- hook id: some-id
- duration: 0.08s

a.py
b.py

Notice:

We got some-name in the output, because that's what we defined in our .pre-commit-hooks.yaml file.
We used some-id (defined in the .pre-commit-hooks.yaml file as well) in the command to refer to our hook (we could have multiple hooks).
a.py and b.py were printed. That's because we used the flag --all-files in our command (If we didn't, the hook execution would have been skipped, because there are no new/edited files for git).

Remember that you need to be in the test-the-hook-in-this-folder folder for the command just used to work.

If we now add a new file to our test folder:

touch c.py

We track it with git:

git add c.py

And then we run the command without the --all-files flag:

pre-commit try-repo ../the-hook some-id --verbose

We get:

some-name................................................................Passed
- hook id: some-id
- duration: 0.07s

c.py

As you can see, only c.py was printed this time, because is the only new/edited file for git, so our hook was run only against that file. This is the behavior you will normally want.

Now you know how to create a pre-commit hook 🪝! Go and make cool things with this knowledge 😁.

Let me know if you create a hook or something. This is one I created a few weeks ago.

Another way of working with temporary files

Jorge Alvarado — Thu, 03 Feb 2022 13:32:30 +0000

🗂 tmp-folder allows you to easily use a temporary folder during the execution of a function. After it is done executing, the folder will be automatically deleted (with all its content of course).

Install it

pip install tmp-folder

Watch it in action

All you need to do is to decorate the function that needs a temporary folder and your function will get a free extra parameter, that's your tmp-folder:

# main.py
from pathlib import Path

from tmp_folder import use_tmp_folder


@use_tmp_folder  # This is the decorator
def do_some_stuff(my_tmp_folder: Path) -> Path:
    with open(my_tmp_folder / "some_file.txt", "w") as file:
        file.write("Hello World")

    assert my_tmp_folder.exists()

    return my_tmp_folder


if __name__ == "__main__":
    my_tmp_folder = do_some_stuff()
    assert not my_tmp_folder.exists()
    print("Everything went ok")

We execute the code with python main.py:

Everything went ok

✅ Cool, there are no assertion errors 👏🎉🎉🎉.

Key points:

The function that needs temporary stuff, is decorated with use_tmp_folder.
You get a new parameter in your decorated function (it can be named however you want, in this case my_tmp_folder). See how when you are calling do_some_stuff, you are not passing any argument, but on its definition there is a parameter, well, that's because tmp-folder adds it for you.
This new parameter is the temporary folder that tmp-folder gives you. You can store whatever you want in there. After the decorated function is done executing: bye bye temporary folder 👋.
The parameter is a Path object, so you get all the cool things pathlib offers.
The decorator is built on top of Python's TemporaryDirectory, so you know is a safe thing to use.

For more details see the package documentation.
Image author.

Don't forget to update that value in those files

Jorge Alvarado — Tue, 25 Jan 2022 13:13:48 +0000

Intro

The other day, based on a project needs, I created a pre-commit hook: version-checker. It helps you remember to update the version of your project in different files before doing a commit.

Setup

You only need to have pre-commit installed (and to use git, but who doesn't?):

pip install pre-commit

Create a basic project structure

Let's use a very basic project structure for the sake of the tutorial:

.
├── README.md
├── setup.cfg
└── src
    └── __init__.py

The files README.md and __init__.py will refer in some way to the version of the project, that lives in setup.cfg.

Let's see the content of these files:

setup.cfg

# setup.cfg
[metadata]
name = some-project
version = 0.1.0

README.md

# README.md

# You are using version 0.1.0 of this project

src/__init__.py

# src/__init__.py
__version__ = "0.1.0"

Now, if you update the version of your project (setup.cfg) you have to remember to update it in 2 more files (README.md and __init__.py). That sounds like something easy to forget right? This is when the hook comes to the rescue 🦸.

The hook

For setting up the hook you need to create a .pre-commit-config.yaml file (like any other pre-commit hook):

# .pre-commit-config.yaml
repos:
-   repo: https://github.com/jalvaradosegura/version-checker
    rev: v0.4.1-alpha
    hooks:
    -   id: version-checker
        args: [
          --files, README.md, src/__init__.py,
          --grab-version-from, setup.cfg
        ]

Most of the content is the typical config of a hook. Let's explain the args:

--files: mandatory argument. It indicates the path to the files that the hook will evaluate to contain the desired version.
--grab-version-from: optional argument. It tells the hook from where to grab the version to evaluate (By default it tries to grab it from a pyproject.toml file).

Then we install it with:

pre-commit install

Congrats, everything is ready, version-checker won't let you forget to update the files 🎉🎉.

See it in action 👀

Let's update the version in our setup.cfg to 0.2.0 and try to do a commit:

The hook is basically telling you that README.md and __init__.py are not using the latest version of the package within their content.

Update the corresponding files and try to commit again:

When it may be helpful and when it may not

I created this hook because I was working in a project which had a lot of files that were referring to the version of the project: python files, markdown files, some template files and even a Jenkinsfile. For python files it wasn't hard to handle the version, thanks to version from importlib.metadata, but the other files were trickier...

When do I think this hook may be helpful:

If your project refers to the version of the project in multiple files with different extensions.
If you are already using pre-commit hooks and you don't know another tool for this purpose.

When do I think it may not:

If you already use another tool for this purpose.
If for some reason the hook is harming the performance of pre-commit (in my experience the hook runs super fast). Take a look at this.

Other options

The other day I learned about 2 tools that seems to work for the same purpose (I haven't tried them yet):

And also I was shared this cool list.

Post image created by @circus.infernus