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. |
Modules
Section titled “Modules”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. |
Functions
Section titled “Functions”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. |
Comprehensions
Section titled “Comprehensions”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. |
Standard library
Section titled “Standard library”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. |
Speed and memory
Section titled “Speed and memory”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. |