Python Best Practices

Guidelines for writing and reviewing Python. 75 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.

Quick-reference lines are triggers, not licenses: before applying a rule as a review finding or a transformation, open the rule file and check its counter-signal — the marker-opened paragraph (**When ...** / **Scope:** / **Preserve ...**) saying when NOT to apply it.

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)
• PEP 695 type statement and generic syntax — 3.12+ (noted inline in types-modern-syntax)

Rules tagged applicability:pydantic are Pydantic-specific.

Rule Categories by Priority

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 — One unambiguous contract per function: mutate (new-info returns fine) or return new — never the mutated object as if fresh
• 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
• data-reject-bool-as-int — bool subclasses int; reject it explicitly before numeric checks

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
• error-match-types-not-messages — Classify by exception type and status code, never message substrings

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
• types-modern-syntax — X | None, list[str]; not Optional / Union / typing.List
• types-sequence-over-list-params — Sequence / Mapping for read-only params; list is invariant

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
• imports-lightweight-init — Parent __init__.py runs on every submodule import; keep heavy/optional deps out

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.