Python Best Practices

Guidelines for writing and reviewing Python. 70 rules across 8 categories, prioritized by impact.

A rule match is a signal, not a verdict. Most rules are design preferences for new code, not bugs to fix across the repo — check the rule's impact level before flagging in review or refactoring stable code.

When to Apply

Writing new Python modules, functions, classes, or data models
Reviewing code for correctness or type safety
Refactoring patterns in code that's being edited anyway

Avoid applying these rules as a blanket sweep across stable code — the churn rarely pays off.

Impact Levels

```
CRITICAL
```
— prevents a real bug class (data corruption, swallowed cancellations, insecure defaults). Fix when found.
```
HIGH
```
— meaningful correctness or maintainability win. Worth fixing in most contexts.
```
MEDIUM
```
— good practice; clarity or drift prevention. Apply to new code; don't churn stable code.
```
LOW-MEDIUM
```
/
```
LOW
```
— style or micro-optimizations. Apply opportunistically.

Python Version Baseline

Rules assume Python 3.11+. Rules depending on higher versions call it out inline:

```
warnings.deprecated()
```
— 3.13+
```
zoneinfo
```
— 3.9+
Union types in
```
isinstance()
```
— 3.10+
```
assert_never
```
— 3.11+ (backport via
```
typing_extensions
```
)

Rules tagged

applicability:pydantic

are Pydantic-specific.

Rule Categories by Priority


data-
error-
types-
api-
simplify-
perf-
naming-
imports-

Priority	Category	Impact	Prefix
1	Data Modeling	HIGH	`data-`
2	Error Handling	MEDIUM-HIGH	`error-`
3	Type Safety	MEDIUM-HIGH	`types-`
4	API Design	MEDIUM	`api-`
5	Code Simplification	LOW-MEDIUM	`simplify-`
6	Performance	LOW-MEDIUM	`perf-`
7	Naming	LOW-MEDIUM	`naming-`
8	Imports & Structure	LOW	`imports-`

Section impact is a typical-case label; individual rules range one level above or below — check the rule file.

Quick Reference

Data Modeling (

data-

)

data-mutable-defaults

— Never

def f(items=[])

; use

None

+ body construction or

default_factory

```
data-derive-dont-store
```
— Compute booleans from state; don't cache flags that mirror each other
```
data-mutation-contract
```
— Mutate OR return; not both

data-aware-datetimes

— Timezone-aware

datetime.now(timezone.utc)

;

utcnow()

is deprecated

```
data-discriminated-unions
```
— Tag variants instead of optional-field bags
```
data-explicit-variants
```
— Concrete classes per mode beat
```
is_thread
```
/
```
is_edit
```
flags
```
data-phased-composition
```
— Group co-present optionals into one nested optional
```
data-encapsulate-mutable-state
```
— Trap mutable state in the narrowest clear scope
```
data-sentinel-when-none-is-valid
```
— Private sentinel when
```
None
```
is a meaningful value

data-newtype-for-ids

—

NewType('UserId', str)

so IDs aren't interchangeable

```
data-delete-dead-variants
```
— Remove union arms that aren't constructed

Error Handling (

error-

)

```
error-specific-exceptions
```
— Catch specific types; never bare
```
except:
```
or
```
except BaseException:
```
(breaks Ctrl-C and async cancellation);
```
except Exception:
```
is cancellation-safe on 3.8+
```
error-context-managers
```
—
```
with
```
/
```
async with
```
for files, locks, sessions
```
error-assert-debug-only
```
—
```
assert
```
vanishes under
```
-O
```
; not for runtime contracts
```
error-validate-at-boundaries
```
— Fail fast at system edges before expensive work
```
error-trust-validated-state
```
— Trust immutable, locally-constructed state
```
error-consolidate-try-except
```
— Merge blocks with the same catch and handling

error-assert-never-exhaustiveness

—

typing.assert_never

for exhaustiveness

error-raise-from-for-chains

—

raise NewErr(...) from original

to preserve causality

```
error-inherit-base-exceptions
```
— New exceptions inherit existing bases for compatibility

error-log-exception-context

—

logger.exception(...)

inside

except

; keep the traceback in the log

```
error-repr-in-messages
```
—
```
f"tool {name!r}"
```
for identifiers in error text

Type Safety (

types-

)

types-fix-errors-not-ignore

— Fix type errors;

# type: ignore

is a last resort

```
types-avoid-any
```
— Protocols, TypeVars, unions over
```
Any
```
```
types-typeddict-over-dict-any
```
—
```
TypedDict
```
/ dataclass when structure is known

types-literal-for-fixed-sets

—

Literal["a", "b"]

for fixed strings

```
types-fix-types-not-cast
```
— Fix the definition;
```
cast()
```
only when runtime genuinely narrows

types-isinstance-for-narrowing

—

isinstance()

over

hasattr

type(x).__name__

```
types-narrow-to-runtime-reality
```
— Annotations match what control flow actually allows
```
types-trust-the-checker
```
— Drop runtime checks the types already enforce
```
types-remove-redundant-optional
```
— Drop
```
| None
```
when values are guaranteed present

types-type-checking-imports

—

if TYPE_CHECKING:

for optional or heavy imports

API Design (

api-

)

```
api-required-before-optional
```
— Required fields before optional (Python enforces this)
```
api-keyword-only-params
```
—
```
*
```
marker for optional/config params

api-no-boolean-flag-params

—

Literal

Enum

over

True, False

soup

```
api-immutable-transforms
```
— Return new collections; don't mutate inputs
```
api-model-cohesion
```
— Flat models; no duplicate or single-key-wrapped fields

api-underscore-for-private

—

_prefix

for internals; exclude from

__all__

api-deprecated-aliases

—

warnings.deprecated()

(3.13+) for renamed APIs

```
api-no-private-access
```
— Don't reach into
```
_prefixed
```
names from outside the module
```
api-instance-vs-module-fn
```
— Pick the namespace that matches ownership

Code Simplification (

simplify-

)

```
simplify-early-return
```
— Return early; don't nest the happy path
```
simplify-extract-after-duplication
```
— Second copy is the decision point; third is the safe default
```
simplify-cached-property
```
—
```
@cached_property
```
on immutable instances; not thread-safe
```
simplify-comprehensions
```
— Comprehensions over
```
for
```
+
```
.append()
```

simplify-any-all-builtins

—

any()

all()

over manual flag +

break

```
simplify-fallback-or
```
—
```
x or default
```
when falsy values aren't semantic

simplify-flatten-nested-if

—

if cond1 and cond2:

when no intervening code

```
simplify-inline-single-use-vars
```
— Drop intermediates used once
```
simplify-remove-dead-code
```
— Delete commented-out code; git preserves history

Performance (

perf-

)

```
perf-set-for-membership
```
—
```
set
```
for repeated
```
in
```
checks
```
perf-dict-index-over-nested-loops
```
— Build a
```
dict
```
for lookups

perf-lru-cache-pure-fns

—

functools.lru_cache

functools.cache

on pure functions

```
perf-generator-over-list
```
— Stream with generators when memory or latency matters
```
perf-combine-iterations
```
— Fuse
```
filter
```
+
```
map
```
into one pass
```
perf-compile-regex-module-level
```
— Compile static regex at module scope; matters in tight loops
```
perf-type-adapter-constant
```
— Module-scope
```
TypeAdapter
```
(applicability: pydantic)
```
perf-isinstance-tuple-syntax
```
— Tuple form is marginally faster; profiled hot paths only

Naming (

naming-

)

```
naming-rename-on-behavior-change
```
— Rename when behavior changes; stale names mislead
```
naming-consistent-terminology
```
— Same concept, same word across code/docs/errors

naming-specific-over-generic

—

toolset_id

; not bare

id

naming-drop-redundant-prefixes

—

ToolConfig.description

; not

ToolConfig.tool_description

```
naming-upper-case-constants
```
—
```
MAX_RETRIES
```
;
```
_
```
prefix for internal
```
naming-no-type-suffixes
```
— No
```
_dict
```
/
```
_list
```
suffixes; types annotate types

Imports & Structure (

imports-

)

```
imports-no-side-effects
```
— Modules must be cheap to import — no network/model/env reads at import
```
imports-top-of-file
```
— Imports at the top; documented exceptions for circular / optional / deferred

imports-optional-dependencies

—

try

except ImportError

with install hints

```
imports-scope-helpers-to-usage
```
— Define helpers near where they're used
```
imports-remove-unused
```
— Delete unused imports
```
imports-no-duplicates
```
— One import per name

How to Use

Read individual rule files for detail:

rules/data-mutable-defaults.md
rules/error-specific-exceptions.md

Each rule has:

Impact level in frontmatter
Brief explanation
Incorrect example
Correct example
Optional note on edge cases

For the full compiled guide with all rules expanded:

AGENTS.md

python-best-practices

NPX Install

Tags

SKILL.md Content

Python Best Practices

When to Apply

Impact Levels

Python Version Baseline

Rule Categories by Priority

Quick Reference

Data Modeling (
`data-`
)

Error Handling (
`error-`
)

Type Safety (
`types-`
)

API Design (
`api-`
)

Code Simplification (
`simplify-`
)

Performance (
`perf-`
)

Naming (
`naming-`
)

Imports & Structure (
`imports-`
)

How to Use

python-best-practices

NPX Install

Tags

SKILL.md Content

Python Best Practices

When to Apply

Impact Levels

Python Version Baseline

Rule Categories by Priority

Quick Reference

Data Modeling (data-)

Error Handling (error-)

Type Safety (types-)

API Design (api-)

Code Simplification (simplify-)

Performance (perf-)

Naming (naming-)

Imports & Structure (imports-)

How to Use

Data Modeling (
`data-`
)

Error Handling (
`error-`
)

Type Safety (
`types-`
)

API Design (
`api-`
)

Code Simplification (
`simplify-`
)

Performance (
`perf-`
)

Naming (
`naming-`
)

Imports & Structure (
`imports-`
)