Conventions

Use Ruff

Python has an official style guide, PEP 8, covering things like how to name variables, how long a line should be, and where blank lines go. A linter checks your code against those rules automatically, so you don’t have to remember them all.

We’ll use ruff. Install it and check your code, with your virtual environment active and from your project directory:

pip install ruff
ruff check .

Note

Older versions of this workshop taught flake8. ruff has since become the standard choice because it’s much faster and implements the same underlying rule codes, so everything you learn here about reading the output applies to either.

How do you know it worked? If your code is already clean, ruff prints:

All checks passed!

Otherwise you get a block per problem, naming the rule, the exact file, line and column, and often a suggested fix. If you had an unused import, for example:

F401 [*] `os` imported but unused
 --> plain_magic/cli.py:1:8
  |
1 | import os
  |        ^^
  |
help: Remove unused import: `os`

Found 1 error.
[*] 1 fixable with the `--fix` option.

Each code identifies a specific rule: F codes come from pyflakes (likely bugs — an unused import, an undefined name), E codes from pycodestyle (formatting), UP codes suggest more modern Python syntax. You can look up any code in ruff’s rules reference.

Fix them by editing the named lines. Problems marked [*] can be fixed for you:

ruff check --fix .

Re-run ruff check . until you get All checks passed!.

If you want ruff to run automatically alongside your tests, add it to the tox.ini you created in the previous chapter:

[testenv:ruff]
deps = ruff
commands = ruff check .

and compare with the template tox.ini.

Add .gitignore

Some files should never go into git: your virtual environment, Python’s compiled caches, and build artifacts. They’re large, machine-specific, and regenerated automatically — committing them just creates noise and merge conflicts.

Create a .gitignore file in your project root listing patterns to ignore:

.gitignore
.venv/
__pycache__/
*.egg-info/
.tox/
.pytest_cache/

Each line is a pattern; * matches anything. See the template’s example for a fuller version.

Important

.gitignore only stops files being added in future — it does not remove anything git is already tracking. If you committed .venv/ or __pycache__/ earlier (quite likely by now), check with git status, and if they appear, untrack them:

git rm -r --cached .venv __pycache__
git commit -m "Stop tracking generated files"

The files stay on your disk; git just stops following them.

How do you know it worked? git status no longer lists .venv, __pycache__ or .tox as untracked or modified.

Finishing up

Commit and push these last changes through a merge request, like every other change you’ve made — and check the pipeline goes green one final time.

Congratulations — you’ve now completed all four parts of this curriculum. You can use git’s branch/commit/merge-request workflow, write and run tests, write and publish documentation, and package your own code properly. These four skills together cover the day-to-day mechanics of working on a real, shared Python codebase.