Python Style Rules

Ordered by how much damage breaking them does.

Failures must be visible

1. Never write a bare except: or except Exception: that continues. It catches the typo in the line above it too. Catch the specific exception you expect.
2. Never swallow an exception silently. If ignoring it is right, log it or comment why in one line.
3. Do not return None to signal an error in a function that also returns None legitimately. Raise, or return an explicit result type.
4. Chain exceptions. raise X from err. Dropping the cause discards the traceback that explains the failure.
5. Validate at the boundary. Data from a network, a file, or a subprocess is untrusted. Check it once on the way in, not defensively at every use.

The obvious traps

6. No mutable default arguments. def f(x=[]) shares one list across every call. Use None and build inside.
7. Do not mutate a collection you are iterating. Build a new one.
8. Close what you open. Use with, always, including for subprocesses and locks.
9. Compare with is only for None, True, False. Not for strings or numbers.
10. Beware truthiness on containers and numbers. if not count is true for zero. Say if count is None when that is what you mean.

Types and data

11. Type hints must be honest. If it can return None, the hint says | None. A wrong hint is worse than none, because tools trust it.
12. Prefer a dataclass or NamedTuple to a dict for anything with a fixed shape. A dict of known keys is a class that has not admitted it yet.
13. Do not use a tuple with more than three elements as a return value. Name the fields.

Dependencies

14. Do not add a dependency for something the standard library does. pathlib, json, itertools, dataclasses, subprocess cover an enormous amount.
15. Do not add a dependency for one function. Copy the twenty lines, with credit.
16. Pin what you add, and say in the commit why it is needed.

Structure

17. Functions do one thing and are named after it. A name with and in it is two functions.
18. No side effects at import time. No network calls, no file writes, no environment mutation in module scope. Import must be free.
19. Match the file you are editing. Its conventions win over your preferences.

Comments

20. Comment the why. The constraint, the workaround, the reason for the odd choice.
21. Docstring the contract, not the implementation: what it takes, what it returns, what it raises.
22. Delete commented-out code.

What good looks like

# The vendor API returns 200 with an empty body on rate limit, so a status
# check is not enough to tell success from throttling here.
try:
    payload = json.loads(response.text)
except json.JSONDecodeError as err:
    raise UpstreamError(f"non-JSON body from {url}") from err

Specific exception, cause preserved, and a comment explaining something the reader could not have guessed from the code.