Python Best Practices

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

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

• warnings.deprecated()

  — 3.13+

• zoneinfo

  — 3.9+
• Union types in

  isinstance()

  — 3.10+

• assert_never

  — 3.11+ (backport via

  typing_extensions

  )

applicability:pydantic

Rule Categories by Priority

data-

error-

types-

api-

simplify-

perf-

naming-

imports-

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

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

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

AGENTS.md