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

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: 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