Skip to content

Python

The Python pack has 29 rules, and xpd can fix 2 of them.

The Python rules report style choices that no formatter or type checker makes, and they run on every file, whatever it imports. The python-best-practices skill in skills/ holds the rest of the style, and the python-review skill reviews code against it.

Group Rules
Names module-private-name, vague-module-name
Modules import-side-effect
Types typing-cast, dict-str-any, record-without-namedtuple, json-without-type, same-type-conversion, float-around-number
Functions pass-through-function, multi-line-call-argument
Tests mock-import, test-skip, test-rerun, test-sleep, test-suppressed-health-check
Comprehensions comprehension-merges-dicts, unpacked-comprehension, comprehension-two-fors, comprehension-multi-line, comprehension-among-arguments
Standard library setdefault-without-defaultdict, counting-loop-without-counter, strptime-without-fromisoformat, elapsed-without-perf-counter, toml-without-tomllib
Speed and memory front-insert-in-loop, orjson-loads-decoded, slotted-base-without-slots

Name each module after what it holds, and leave the underscore off module level names.

Rule Severity Fix What it finds
module-private-name warning none A module level name that starts with an underscore hides code that other modules may need.
vague-module-name warning none A module named utils, helpers or common does not say what it holds.

Keep calls and environment reads out of the top level of a module, so an import runs no work.

Rule Severity Fix What it finds
import-side-effect warning none A call at module level runs whenever the module is imported.

State the real type in a signature, so the type checker can check the keys and the values the function uses.

Rule Severity Fix What it finds
typing-cast warning none cast() overrides the type checker without any check at run time.
dict-str-any warning none dict[str, Any] in a signature hides which keys and values the function works with.
record-without-namedtuple warning none A frozen dataclass or attrs class that only holds fields can be a NamedTuple, which is cheaper to define and build.
json-without-type warning none Returning the result of json.loads gives the caller Any, so nothing names the shape of the data.
same-type-conversion warning unsafe float(), int(), str() or bool() around a value that already has that type does nothing.
float-around-number warning none A number from a float64 array or a Series is a float already, and so is arithmetic on it.

Call a function directly when a second function would only pass its parameters on.

Rule Severity Fix What it finds
pass-through-function warning none A function that only passes its parameters to one call adds a name without adding behavior.
multi-line-call-argument warning none A call that runs over several lines inside another call's arguments is hard to read.

Test with real objects and let every test run once, because a mock, a skip, a rerun or a sleep lets a test pass while the code is wrong.

Rule Severity Fix What it finds
mock-import warning none A test with a mock checks the mock and not the real code.
test-skip warning none A skipped test never runs, so it proves nothing.
test-rerun warning none Rerunning a test until it passes hides why it fails some of the time.
test-sleep warning none A test that waits a fixed time is slow and still fails when the wait is too short.
test-suppressed-health-check warning none A property test that turns off a Hypothesis check of correctness can pass while it checks the wrong thing.

Write a loop when a comprehension merges dicts, unpacks, holds two for clauses or runs over several lines, and give a comprehension a name before you pass it with other arguments, because both are easier to read.

Rule Severity Fix What it finds
comprehension-merges-dicts warning none A comprehension that merges dicts with ** for every item builds a new dict for each item and is hard to read.
unpacked-comprehension warning none A dict literal that unpacks a comprehension with ** is hard to read.
comprehension-two-fors warning none A comprehension with more than one for is hard to read.
comprehension-multi-line warning none A comprehension that runs over more than one line is hard to read.
comprehension-among-arguments warning none A comprehension that is one of several arguments of a call makes the call hard to read.

Use what the standard library already has before you write it by hand.

Rule Severity Fix What it finds
setdefault-without-defaultdict warning none setdefault with an empty list, set or dict builds a new empty value on every call.
counting-loop-without-counter warning none A loop whose only job is to count items with a dict does what collections.Counter does in one call.
strptime-without-fromisoformat warning none strptime with an ISO 8601 format does what fromisoformat does without a format.
elapsed-without-perf-counter warning none Measuring a duration with time.time() uses the system clock, which can be set back.
toml-without-tomllib warning none The standard library reads TOML since Python 3.11.

Leave out work that the measured alternative skips, when the code can always take the alternative.

Rule Severity Fix What it finds
front-insert-in-loop warning none Each insert(0, x) moves every item already in the list, so a loop of them gets slow.
orjson-loads-decoded warning unsafe orjson reads UTF-8 bytes directly, so decoding them to a str first only adds work.
slotted-base-without-slots warning none A subclass without slots gives its instances a dict again, so the memory that the base class saved is lost.