Maintaining code is quite a challenge over the long-term. Over the lifetime of a library, many people read and edit it. Each person has a different background in coding and also a different goal in mind. These variations can lead to inconsistencies throughout the code that makes it a bit harder for the next person to understand. In CircuitPython libraries, we use tools like Pylint and Black to ensure consistency in new code.

As we've added more automated checks, we've changed to a system called pre-commit to manage the checks overall. Once installed properly, you can run pre-commit locally, before committing new code into Git. It also runs remotely on GitHub when a pull request has been proposed. pre-commit is set up to remotely run on all existing libraries. It will automatically run remotely on a new library thanks to cookiecutter.

However, it won't run locally unless you install it into your local directory. We highly recommend doing this because it will both check and fix your code locally.

One-time initial install of pre-commit

If you've never used pre-commit on your computer before, you'll need to install it globally (there is a second "install" for each repository.) The easiest way to install it is with pip.

pip install pre-commit

Workaround for pre-commit issues on Ubuntu 22.04 and Debian

In ubuntu 22.04 or the analogous Debian release, you may see the error "expected environment for python to be healthy immediately after install" when trying to use pre-commit. To fix this, add this line to your .bashrc or .bash_aliases file, or other shell startup file. Restart your shell as necessary to pick up this setting.

export SETUPTOOLS_USE_DISTUTILS=stdlib

This export must be present before pre-commit sets up its virtualenv environment, which happens the first time you do pre-commit run or you try to push a commit. If the virtualenv is already set up, do pre-commit clean, which removes the existing virtualenv.

See the instructions from the pre-commit project for installation for alternative ways of installing pre-commit.

Per-repository installation

For every new repository, you'll need to perform an pre-commit installation. This installs the specific versions of checks that the repository specifies. From within the repository do:

pre-commit install

After running this command, pre-commit will automatically run when you do git commit.

However, if you don't do this, you can still run pre-commit manually.

Running pre-commit

pre-commit will run each check every commit for all of the modified files and either pass or fail. Most checks that fail will also modify the source file to make it pass (like removing extra spaces). Once that happens, you'll see newly modified files in git status. git add them and then try the commit again.

Manually

You can run the pre-commit checks on every file whenever you like with:

pre-commit run --all-files

More Info

For more info on pre-commit see pre-commit.com.