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:
.. code-block:: none
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:
.. code-block:: none
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:
.. code-block:: ini
[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:
.. code-block:: none
:caption: .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:
.. code-block:: none
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.