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.
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 install pre-commit
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
.bash_aliases file, or other shell startup file. Restart your shell as necessary to pick up this setting.
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
See the instructions from the pre-commit project for installation for alternative ways of installing
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:
After running this command, pre-commit will automatically run when you do
However, if you don't do this, you can still run pre-commit manually.
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 add them and then try the commit again.
You can run the pre-commit checks on every file whenever you like with:
pre-commit run --all-files
For more info on
pre-commit see pre-commit.com.