Zen Python

Zen Python

Write Python a senior Pythonista would approve of on first read: concise, typed, flat, and idiomatic, while matching the target repo's version and style.

Use repo-wide custom instructions for always-on conventions. Use this skill for deeper Python-specific judgment.

For concrete examples, load only the relevant section from patterns reference instead of reading the whole file by default.

Workflows

When writing or refactoring

1. Confirm the target Python version and repo conventions first. Infer them from pyproject.toml, CI, lockfiles, imports, and surrounding code before introducing newer syntax.
2. Choose the data model before writing logic.
3. Write typed signatures early when the repo uses type hints pervasively; in lighter-weight codebases, keep the typing level consistent with surrounding code.
4. Keep the happy path at the shallowest indentation level. Reach for guard clauses and small helpers before adding more nesting.
5. Load only the relevant pattern section from references/patterns.md when you need a concrete before/after example.
6. Run the self-check before presenting code.

When reviewing

1. Start with correctness and regressions: behavior changes, hidden exceptions, API misuse, resource leaks, concurrency issues, and bad edge-case handling.
2. Check compatibility next: supported Python version, stdlib availability, repo conventions, serialization boundaries, and migration risk.
3. Check tests after that: missing coverage for changed behavior, error paths, async paths, and compatibility-sensitive branches.
4. Suggest maintainability or style improvements only after correctness, compatibility, and testing concerns are covered.
5. Load only the relevant pattern section from references/patterns.md if it sharpens a concrete review comment.
6. Preserve existing behavior when refactoring for style alone.

When to relax these defaults

• Throwaway scripts and REPL exploration: type hints, dataclasses, and polished error handling are optional. Optimize for speed.
• Performance-critical hot paths: break a style rule if profiling justifies it. Add a comment explaining the tradeoff.
• Matching an existing codebase: consistency with the project beats local preferences. Do not force 3.12 idioms into an older or intentionally conservative repo.
• Prototypes and spikes: keep the code clean, but avoid ceremony that slows iteration without changing the outcome.

Principles

• Flat over nested. Use guard clauses and early returns so the happy path is easiest to read.
• Explicit over implicit. Prefer clear data flow, names, and interfaces over cleverness.
• Practicality beats purity. Treat these as defaults, not laws. Match the repo and the task.
• Names explain what; comments explain why. Use both intentionally.
• Version-aware advice beats generic advice. Choose syntax and libraries that fit the target Python version.

Typing

• Prefer type hints on function signatures, especially for public APIs, shared helpers, and new modules.
• Prefer str | None over Optional[str] and built-in generics in 3.10+ codebases. If the repo targets older versions or consistently uses older typing syntax, match the repo.
• Prefer type UserId = int in 3.12+ codebases. Use TypeAlias or assignment when supporting older versions.
• Prefer Protocol over ABCs for structural subtyping unless shared behavior, registration, or inheritance-based APIs make an ABC clearer.
• Use @overload when callers genuinely benefit from narrower signatures. Otherwise keep the callable surface simple.
• Avoid Any unless the boundary is genuinely dynamic, third-party typed, or intentionally untyped.

Data modeling

Choose the right container before writing logic:

If you're repeatedly accessing the same internal dict keys, consider a dataclass. Keep raw dicts or TypedDict when keys are dynamic, external, short-lived, or primarily about serialization.

Functions

• Prefer one job per function, but do not split a function so aggressively that the flow becomes harder to follow.
• Aim for fewer than 30 lines when it improves readability. Keep a longer function when the whole flow is easier to reason about together.
• Use keyword-only args when call sites become ambiguous, not as a blanket rule.
• Return consistent types. Raise when a None return would only defer an error downstream.
• Prefer dependency injection over module-level singletons.

Error handling

• Catch specific exceptions when possible.
• Prefer exception chaining when translating or enriching an error. Plain raise is fine when re-raising unchanged.
• Keep try blocks tight so unrelated failures do not get folded into the wrong handler.
• Add structured context to custom exceptions when it helps callers, logs, or tests reason about failures.

Async

• Prefer asyncio.TaskGroup in 3.11+ codebases when you want structured concurrency and fail-fast cancellation.
• Keep asyncio.gather when the repo targets older versions or when its ordered-results behavior is the clearest fit. Decide intentionally how exceptions should behave.
• Do not call blocking IO (requests.get, time.sleep, CPU-heavy loops, sync file/network APIs) inside async functions unless the code explicitly offloads it.
• Use an async_ prefix only when both sync and async variants coexist.

Testing

• Prefer pytest-style tests with plain functions and @pytest.mark.parametrize when multiple cases share the same shape.
• Name tests as test_<unit>_<scenario>_<expected> when that fits the repo's existing conventions.
• Test behavior, not implementation details. The tests should survive refactors.
• In review mode, call out missing or weak tests before minor style suggestions.

Docstrings

• Prefer the docstring style already used by the repo. If the repo has no strong convention, default to concise Google-style docstrings.
• Focus on public APIs, non-obvious behavior, and surprising edge cases.
• Keep the first line imperative when that matches the surrounding style.

Gotchas

These are mistakes agents commonly make in Python. Pay special attention:

• Mutable default arguments. def f(items=[]) shares one list across all calls. Use None plus conditional assignment.
• except Exception hiding bugs. Broad handlers can swallow TypeError, KeyError, or programmer mistakes. Catch the narrowest exception you can, or log and re-raise.
• os.path vs pathlib. Prefer pathlib.Path in modern codebases unless the repo consistently uses os.path or an API requires plain strings.
• Legacy typing imports. Prefer modern typing syntax in 3.10+ codebases. Keep older imports when version support or repo consistency requires them.
• from __future__ import annotations. It is often unnecessary in 3.12+ modules. Do not add or remove it blindly; match the repo's supported versions.
• Forgetting from in wrapped exceptions. Use raise NewError() from err when adding meaning or context to an exception.
• Returning None for real errors. Raise when the caller would otherwise hit a less useful failure later.
• Raw dicts as default data containers. Prefer dataclasses for stable internal shapes; keep dicts or TypedDict for external payloads, dynamic keys, or serialization-heavy layers.
• Silent pass in except blocks. At minimum log the exception. Prefer handling it intentionally.
• gather() without a failure model. Choose TaskGroup for fail-fast structured concurrency or gather when collecting results is intentional.
• Nested comprehensions. Anything deeper than one level is usually harder to read than an explicit loop.
• Stringly-typed comparisons. Repeated literals like if status == "active" often want an enum or named constant.

Never suggest

• type: ignore without an inline explanation.
• Single-letter variables outside comprehensions, lambdas, and tiny local scopes.
• Base classes or mixins before there is a clear shared abstraction.
• God classes. Prefer functions or small focused classes.
• from x import *.
• Bare except: or except Exception: pass.

Self-check before finishing

Before presenting Python code or review findings, verify:

• Target Python version and repo conventions were checked before introducing newer syntax.
• Signatures follow the repo's typing level, and new code is typed where it matters.
• No mutable default arguments.
• No bare except or silent except ... pass.
• Wrapped exceptions use from when adding context.
• try blocks wrap only the lines that can raise.
• Data containers match the use case instead of defaulting to raw dicts.
• Nesting is shallow where practical; guard clauses are used when they clarify the flow.
• Path handling matches the repo style; prefer pathlib in modern code.
• Async code uses TaskGroup or gather intentionally.
• In review mode, correctness, compatibility, and test coverage come before style suggestions.