python-coding

Python Coding

Match the project's existing conventions. When uncertain, read 2-3 existing modules to infer the local style. Check pyproject.toml for Python version target, linter config, and tooling. These defaults apply only when the project has no established convention.

Never rules

These are unconditional. They prevent bugs and vulnerabilities regardless of project style.

• Never except: pass or bare except Exception without re-raise. Catch specific exception types. Broad catches silently swallow bugs — a KeyError from a typo looks the same as a network failure, and you'll spend hours debugging something the traceback would have told you instantly.
• Never datetime.now() or datetime.utcnow() -- both produce naive datetimes that lose timezone info. Naive datetimes cause subtle bugs when code crosses timezone boundaries (servers, users, DST). Use datetime.now(tz=timezone.utc). Use zoneinfo.ZoneInfo for other timezones, not pytz.
• Never random for security -- random uses a predictable PRNG; an attacker who observes a few outputs can predict future ones. Use secrets.token_hex(), secrets.token_urlsafe(), or secrets.token_bytes() for tokens, keys, session IDs.
• Never shell=True in subprocess -- shell interpretation enables command injection if any argument contains user input. Use argument lists: subprocess.run(["cmd", arg1, arg2]).
• Never interpolate or unsafely deserialize external input -- no string-formatted SQL (parameterized queries only), no yaml.load() (use yaml.safe_load()), no pickle.load() on untrusted data (use JSON/MessagePack), no eval()/exec() (use ast.literal_eval() for literals). All are injection or remote-code-execution vectors.
• Never mutable default arguments -- def f(items=[]) shares one list across all calls. Appending in one call mutates the default for every subsequent call. Use None sentinel: def f(items: list[str] | None = None) then if items is None: items = [] (not items = items or [], which also replaces a caller's passed-in empty list).
• Never shadow builtins -- don't use list, dict, id, type, input, hash, map, set, filter as variable names. Shadowing causes confusing errors when you later need the builtin in the same scope.
• Never blocking calls in async -- no time.sleep(), bare open(), or requests.get() inside async def. These block the entire event loop, freezing all concurrent tasks. Use asyncio.sleep(), aiofiles, httpx.
• Never += string concatenation in loops -- use "".join(parts). Strings are immutable, so repeated += is quadratic in the general case; CPython has a narrow in-place optimization that often masks it, but it is implementation-specific and easily defeated. join is reliably linear everywhere.