python-best-practices

---
name: python-best-practices
description: Python software engineering guidelines from real PR review patterns. This skill should be used when writing, reviewing, or refactoring Python code — especially dataclasses, service interfaces, error handling, and type annotations. Triggers on tasks involving Python modules, API design, data modeling, type safety, exception handling, or refactoring for maintainability. For asyncio and concurrency guidance, see the python-async-best-practices skill.
license: MIT
---

# 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

| 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` — 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`.