python-best-practices

SKILL.md

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

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.