Applying the code style

[khaeru]

This discussion is for general points about easy ways to follow the code style that applies ixmp, message_ix, message-ix-models, and message_data (private) (but are also good practices to follow in your own code that uses MESSAGEix).

For tips that apply in specific editors/IDEs (integrated development environments), see: #672 for VS Code — #675 for Spyper — (others TBA)

[khaeru]

For typing with mypy, I use a Git pre-commit hook.

For what hooks are, see §8.3 Customizing Git - Git Hooks in the (official) Git Book. A web search turns up lots of results for setting up git pre-commit hooks.

Here's the contents of the file I have at .git/hooks/pre-commit in many of the repositories I work with, with comments for explanation. The two functions called are:

• isort.hooks.git_hook()
• mypy.api.run()

#!/usr/bin/env python

import sys

import isort.hooks
import mypy.api

# Run isort's built-in git hook and store the error code ("_ec"), if any.
# If this check passes, the result is 0.
isort_ec = isort.hooks.git_hook(strict=True)

# Run mypy through its API, and collect the output and error code
*mypy_output, mypy_ec = mypy.api.run(["--show-error-codes", "--color-output", "."])

if mypy_ec:
    # Non-zero → mypy found some errors. Print them.
    print(*mypy_output)

# sys.exit(0) tells git that the pre-commit hook was successful.
# If either of the checks failed, the addition of the error codes is non-zero;
# telling git to stop and not finish the commit.
sys.exit(isort_ec + mypy_ec)

[gidden]

Clarifying question - do we not have these hooks in the message family of repos? (I can not find a hook folder in .github)

[khaeru]

See the note in this particular section of the first link:

It’s important to note that client-side hooks are not copied when you clone a repository. If your intent with these scripts is to enforce a policy, you’ll probably want to do that on the server side; see the example in An Example Git-Enforced Policy.

There was also a typo in my comment above: I had put the directory as .github instead of .git, per the docs. Now fixed, sorry!

[khaeru]

Also, per the note:

If your intent with these scripts is to enforce a policy, you’ll probably want to do that on the server side.

GitHub (the people/company) run a Git server. They use the server-side hooks to, for example, display the message that suggests you open a pull request for a newly pushed branch. We, as GitHub users, cannot modify the server-side hooks that GitHub uses. That's one reason why we instead use a "lint" CI workflow to run this check for code in PRs etc.

[khaeru]

An update: currently I use/we recommend using pre-commit, as this is the same tool used to invoke mypy, ruff, and (for the moment) black in the GitHub CI workflow. The configuration is stored in the repository .pre-commit-config.yaml.

This has the advantage of being more robust than the custom script from my November 2022 comment.