Python in practice, part 4 of 9
Python Code Quality
Code that works is the start. Code that the next person can read, and that a machine has checked for common mistakes, is the goal. This page covers the Python style guide, then three kinds of tool: a formatter that fixes layout, a linter that finds likely bugs, and a type checker that finds calls that do not fit. The examples keep using the bank project from Python Project Setup. Every tool output shown was captured from a real run of black 25.11.0, ruff 0.17.5 and mypy 1.19.1 on Python 3.9, unless the text says it is illustrative.
Style
Group 1 of 3 · what readable Python looks like
- Why style and checks matter: code is read far more than it is written
- PEP 8 in ten rules: with a before and after
- Naming conventions: one table
Why style and checks matter
You write a line once. After that it is read many times: by reviewers, by teammates fixing a bug near it, and by you six months later. Most of a programmer's day is reading code, so anything that makes reading faster pays for itself.
Two things help:
- One shared style. When every file is laid out the same way, your eyes skip the layout and see the logic. Reviews stop being about spaces and quotes.
- Automated checks. A program that reads your code and reports problems never gets tired and never forgets. It finds an unused variable or a wrong argument type in a second, before the code runs at all.
None of these tools run your program. They only read the source text. That is called static analysis, and it is why they are fast and safe to run on every save.
| Kind of tool | Question it answers | Changes your files? |
|---|---|---|
| Formatter | Is the layout consistent? | Yes, it rewrites them |
| Linter | Does this look like a mistake? | Only if you ask it to fix |
| Type checker | Do the values fit where they are used? | No |
PEP 8 in ten rules
PEP 8 is the official style guide for Python code. A PEP is a "Python Enhancement Proposal", a numbered design document. These ten rules cover most of what it asks for.
- Indent with 4 spaces per level. Never mix tabs and spaces.
- Keep lines short. PEP 8 says 79 characters. Many teams, and the tools below, use 88.
- Put two blank lines around top-level functions and classes, and one between methods.
- Put imports at the top, one module per line, in three groups: standard library, third-party, your own.
- Put one space around operators such as
=,+and>=, and one after each comma. Put none just inside brackets, and none around=in a keyword argument:Account(owner, balance=0). - Name functions and variables in
snake_case, classes inCapWords, constants inUPPER_CASE. - Write one statement per line. No semicolons.
- Compare with
Noneusingisandis not. Do not compare withTrueorFalseusing==. - Test for an empty list or string with
if items:, notif len(items) > 0:. - Catch a named exception. Never write a bare
except:.
Here is a small transfer written with none of that. It runs and gives the right answer.
The same program following the rules. The behaviour is identical.
What changed: the two unused imports are gone, names are lower case and say what they hold, there is one statement per line, the long list is split, and l, which looks like the digit 1, became moved.
Note: PEP 8 itself says consistency within a project matters more than any single rule. If a project already has a style, follow it.
Naming conventions
The shape of a name tells the reader what kind of thing it is before they look it up.
| Thing | Style | Example |
|---|---|---|
| Package (folder) | short, all lower case, no underscores if possible | bank |
| Module (file) | lower_snake_case | transfers.py |
| Class | CapWords | SavingsAccount |
| Exception class | CapWords, usually ending in Error | InsufficientFundsError |
| Function, method | lower_snake_case, usually a verb | find_account |
| Variable, parameter | lower_snake_case, usually a noun | opening_balance |
| Constant | UPPER_SNAKE_CASE, defined at module level | TRANSFER_FEE |
| Internal name, not for outside use | one leading underscore | _validate |
| Name that clashes with a keyword | one trailing underscore | class_ |
| Names Python itself defines | two underscores on each side. Do not invent your own | __init__ |
Python does not enforce any of this. A constant in upper case can still be reassigned, and _validate can still be called from outside. The styles are a message to the reader.
Tip: avoid the single letters l, O and I as names. In many fonts they cannot be told apart from 1 and 0.
Tools
Group 2 of 3 · a formatter, a linter and a type checker
- Installing the tools: what needs
pip install - Formatting with black: a real before and after
- ruff format: the same job, faster
- Linting with ruff: four real problems in one file
- Fixing what ruff finds:
--fix, by hand, andnoqa - Choosing rules: configuration in
pyproject.toml - Type checking with mypy: a wrong call caught before it runs
- The None mistake: what
Optionalcatches - Gradual typing: add hints a little at a time
Installing the tools
The tools are ordinary packages. Install them into the project's virtual environment, never globally.
Every Python block on this page runs on the standard library alone. Only the terminal commands black, ruff and mypy need the install above. The last group also uses pytest and the bank project, which lists these tools as its dev dependencies so that pip install -e ".[dev]" brings them all.
Versions: these tools change their output and their default rules between releases. The outputs below come from black 25.11.0, ruff 0.17.5 and mypy 1.19.1. With other versions the wording and the set of reported problems can differ.
Formatting with black
A formatter rewrites your file so the layout follows one fixed style. black is the best known one for Python. It has almost no options on purpose, so there is nothing to argue about.
Here is a statement printer written in a hurry. It runs correctly.
Run black on it. black also prints a decorative line of symbols before the summary. It is left out here.
This is the file exactly as black left it:
The output of the program is the same four lines. What black changed:
- Spaces after commas and around operators, none around
=in defaults. - Single quotes became double quotes.
- The two-line
defwas joined, because it fits in 88 characters. - Lines longer than 88 characters were split, one item per line, with a trailing comma.
if ...: statementon one line became two lines.- Two blank lines after the function.
What black does not change: names, logic, or the order of anything. It only moves white space, quotes, commas and brackets.
| Command | What it does |
|---|---|
black statement.py | Rewrite one file |
black . | Rewrite every Python file under the current folder |
black --check . | Change nothing. Print would reformat statement.py and exit with code 1 if any file needs formatting |
black --diff statement.py | Change nothing. Show what would change |
Habit: set your editor to format on save. Then you never think about layout again, and every commit is already formatted.
ruff format
ruff is a newer tool that is both a linter and a formatter, and is very fast. Its formatter is designed to produce the same style as black. Running it on the same messy statement.py gave a file identical to the black result above, character for character.
The second run changes nothing, because the file is already in the target style. ruff format --check . is the report-only form. It exits with code 1 if a file would change.
Which one: use one formatter per project, not both. If you already use ruff for linting, ruff format saves you a tool. If the project already uses black, keep black.
Linting with ruff
A linter reads code and reports patterns that are legal Python but are probably mistakes. This file runs without any error. It has four problems.
Look at the third line of output. Hemkesh's list contains Sandhya's entry. That is a real bug, and nothing crashed. Now ask ruff:
Each report has a rule code, a message, the file with line and column, and the lines around the problem.
| Code | Problem | Why it matters |
|---|---|---|
F401 | Unused import | Dead code. The reader looks for where os is used and finds nothing |
E722 | Bare except: | It catches everything, even Ctrl+C and typos in your own code, and hides them |
B006 | Mutable default argument | The [] is created once, when the function is defined, and shared by every call. That is the bug in the output above |
F841 | Unused variable | Often the sign of an unfinished thought or a wrong name further down |
A shorter report with one line per problem is available with --output-format concise:
Tip: ruff rule B006 prints a full explanation of one rule in the terminal, with an example of the problem and the fix.
Fixing what ruff finds
The [*] mark means ruff can repair the problem itself. --fix applies those repairs and reports what is left. The output below is the last lines of the real run.
It removed import os and nothing else. The two "unsafe" fixes are ones that could change what the program does, so ruff only applies them if you add --unsafe-fixes. Its suggestion for the unused variable shows why: it would leave a pointless len(amounts) line behind. Fix the rest by hand.
Hemkesh's list is now his own. ruff agrees:
Silencing one line
Sometimes the linter is wrong for your case. A # noqa comment with the rule code turns off that rule for that line only. Always give the code, so other rules still apply, and say why.
Choosing rules
ruff has hundreds of rules, grouped by a letter prefix. With no configuration it uses a default selection. That selection has grown over time: ruff 0.17.5, used here, reports B006 by default, while older releases only did so if you turned the B group on. So do not rely on the default. Write down the groups you want in pyproject.toml.
| Prefix | Group | Example of what it reports |
|---|---|---|
E, W | pycodestyle: PEP 8 layout | Several statements on one line, line too long |
F | Pyflakes: likely errors | Unused import, unused variable, undefined name |
B | flake8-bugbear: bug-prone patterns | Mutable default argument |
I | isort: import order | Imports not sorted or not grouped |
UP | pyupgrade: old syntax | Code that has a newer, simpler form in your Python version |
SIM | flake8-simplify | An if that can be written more simply |
N | pep8-naming | A function named Transfer |
target-version tells ruff the oldest Python you support, so it does not suggest syntax that version lacks. per-file-ignores turns rules off for matching files. Here it allows __init__.py files to import names only to pass them on.
You can also choose groups for one run with --select. This is the PEP 8 "before" file from the earlier chapter, saved as messy.py, checked for layout and naming only:
Advice: start with a small set such as E, F and B, fix everything, then add one group at a time. Turning on every rule at once on an existing project gives hundreds of reports and nobody reads them.
Type checking with mypy
A type hint is a note in the code that says what kind of value a parameter takes and what a function returns. deposit: int means "an integer", and -> int means "returns an integer". Python does not check hints when the program runs. It ignores them.
The second call passes text instead of a number. Python does not complain, because "500" * 2 is legal: it repeats the string. The customer would be credited 500500. mypy is a type checker: it reads the hints and reports every place where the code does not fit them.
Read it as: file, line 7, what is wrong, and in square brackets the name of the check. The mistake was found without running the program and without writing a test.
Concept: hints are also documentation that cannot go out of date without someone noticing. The signature transfer(source: Account, target: Account, amount: int) -> None tells you how to call the function before you read its body.
The None mistake
The most common runtime error in Python is AttributeError: 'NoneType' object has no attribute .... It happens when a function sometimes returns None and the caller forgets that. The hint Optional[Account] means "an Account or None", and mypy then makes every caller deal with both.
It runs and prints 1500, because Hemkesh has an account. With the name "Subhash" it would crash. mypy sees the risk without trying any name:
The fix is to check for None first. Inside the else branch mypy knows the value can only be an Account.
Note: from Python 3.10 you can write Account | None instead of Optional[Account]. This page uses Optional because it also works on Python 3.9.
Gradual typing
You do not have to add hints everywhere at once. By default mypy checks only the functions that have hints and skips the body of any function without them. That is called gradual typing. All three functions below contain a mistake. The file runs, because it only defines functions and never calls them.
Lines 6 and 10 are reported. Line 2, in the function without hints, is not. The --strict flag turns on every optional check, including one that demands hints on every function:
A sensible path for an existing project: add hints to new code and to the functions other code calls most, run plain mypy, and move towards --strict one module at a time.
Limits: mypy only knows what the hints tell it. It cannot check values that arrive while the program runs, such as user input or the contents of a file. Those still need validation code and tests.
Habits and automation
Group 3 of 3 · words for people, checks that run by themselves
- Docstrings: one consistent style
- Comments that explain why
- One configuration file: ruff, black and mypy in
pyproject.toml - The check sequence: four commands before every push
- Pre-commit hooks: run the checks on every commit
- Checks in CI: run them again on a server
- Quick reference
Docstrings
A docstring is a string placed as the first statement of a module, class or function. Python stores it in __doc__, and help() and editors show it. It tells the caller what the thing does and how to use it, not how it works inside.
Pick one layout and use it everywhere. The one below is called Google style: a one-line summary, a blank line, then sections named Args, Returns and Raises.
- Start with one short line in the imperative: "Move money", not "This function moves money".
- Use triple double quotes, even for a one-line docstring.
- Describe what the caller must pass and what comes back, including the unit (rupees, seconds).
- List the exceptions the caller should expect.
- A small private helper with a clear name does not need more than one line, or any docstring at all.
Note: other common layouts are NumPy style and reStructuredText style. They carry the same information. ruff can check docstrings with its D rule group once you tell it which style you use.
Comments that explain why
The code already says what happens. A comment is for what the code cannot say: the reason, the business rule, the trap someone fell into. A comment that only repeats the line below it is noise, and it becomes wrong the day the line changes.
- If a comment explains what a block does, try a better name or a small function first.
charge_transfer_fee(account)needs no comment. - Write comments as full sentences, above the line they describe.
- Update the comment in the same change as the code.
- Delete commented-out code. Version control keeps the old version.
One configuration file
All three tools read their settings from pyproject.toml, each from its own [tool.name] section. Add this below the [project] sections of the bank project.
| Setting | Meaning |
|---|---|
line-length | Keep ruff and black on the same number, or they will disagree |
[tool.black] | Only needed if you format with black. With ruff format, leave it out |
files = ["src"] | What to check when you type mypy with no arguments |
check_untyped_defs | Also look inside functions that have no hints |
warn_unused_ignores | Report # type: ignore comments that are no longer needed |
[[tool.mypy.overrides]] | Different settings for the listed modules |
The last section is there for a real reason. The bank's cli.py imports tabulate, which ships without type hints. Without the override, mypy stops with this:
There are two honest answers. Install the hints as a separate package, as the message suggests, and add it to the dev dependencies. Or tell mypy to treat that one library as unknown, which is what the override does. Do not switch ignore_missing_imports on for the whole project, because that also hides typos in import names.
Concept: a stub package such as types-tabulate contains only type hints for a library that has none of its own.
The check sequence
Run the checks in the same order every time, fastest first. This was run in the bank project with the configuration above and the tools installed in its virtual environment.
ruff counts 7 files because this version also formats the code samples inside README.md. If you format with black, replace the second line with black --check ..
Joined with &&, the commands become one line that stops at the first failure. It gave the same output.
Concept: each tool exits with code 0 when it finds nothing and a non-zero code when it finds a problem. && runs the next command only if the one before it exited with 0. Scripts, hooks and CI servers all rely on that number.
Pre-commit hooks
A check only helps if it is run. Git can run a program just before it records a commit, called a pre-commit hook. The pre-commit tool manages such hooks from a file named .pre-commit-config.yaml in the project root.
This chapter was not run for this page. The file and commands follow the documented usage of the tool. Treat the version numbers after rev as placeholders.
What happens after pre-commit install, each time you type git commit:
- Each hook runs on the files that are staged for this commit.
- If every hook passes, the commit is made as usual.
- If a hook fails or changes a file, the commit is stopped. A formatter may already have fixed the file. You look at the change,
git addit, and commit again.
Two things to know. Each hook runs in its own private environment that pre-commit builds on first use, so the first run is slow. And because of that, the mypy hook does not see the packages your project installed. Libraries it needs for checking are listed under an additional_dependencies key of the hook.
Note: a hook can be skipped with git commit --no-verify, so hooks are a convenience for the author, not a guarantee. The guarantee is the next chapter.
Checks in CI
CI, continuous integration, is a server that runs your checks on every push or pull request, on a clean machine. It catches what a local run misses: someone skipped the hooks, forgot to commit a file, or has a package installed that the project never declared. The job is always the same four steps: get the code, install the project with its dev tools, run the check sequence, and fail if any command exits with a non-zero code. Every CI service has its own file format for that. The sketch below is illustrative: it is not the syntax of any particular service and was not run.
Use the same commands in CI as on your own machine. If CI runs something different, a failure there is hard to reproduce locally.
Quick reference
| Tool | What it catches | Command |
|---|---|---|
| black | Inconsistent layout: spacing, quotes, line breaks. Rewrites the file | black . to fix, black --check . to report |
| ruff format | The same as black, in the same style | ruff format . to fix, ruff format --check . to report |
| ruff check | Unused imports and variables, bare except, mutable defaults, naming, import order | ruff check ., add --fix for safe repairs |
| mypy | Wrong argument and return types, forgotten None checks | mypy or mypy file.py, --strict for everything |
| pytest | Wrong behaviour. See Python Testing | pytest |
| pre-commit | Commits made without running the checks | pre-commit install once, then automatic |
| CI | Everything above, on a clean machine, for every push | The same commands, in the service's own file |
Formatters, linters and type checkers find different problems, so a project normally uses one of each. None of them replaces tests: they check how the code is written, not whether a transfer moves the right amount.
Next in the practice path: Python Standard Library Tour.