python-idiomatic ยท diff
git:20261103.ed222c7 to git:20261103.8277e03
7 added, 3 removed. Audit A to A.
---
name: python-idiomatic
description: >
Use when writing or reviewing Python language semantics, fixing aliasing,
- mutable defaults, late-bound closures, exhausted generators, import cycles,
+ mutable defaults, late-bound closures, `locals()` snapshots, exhausted
+ generators, import cycles,
swallowed exceptions, or resource leaks; choosing comprehensions, decorators,
context managers, match statements, or Python environment/debugging tools.
---
# Python Idiomatic
Target Python **3.15**, checked against **3.15.2 on 2026-11-03**. Recheck the
stable release when updating this guide; preserve an existing project's explicit
compatibility contract when applying it.
## Route by symptom
| Task | Load |
|---|---|
- | Identity/equality, copying, defaults, scope, numbers/text, ordinary classes | [Language semantics](references/language-semantics.md) |
+ | Identity/equality, copying, defaults, `locals()`, scope, numbers/text, ordinary classes | [Language semantics](references/language-semantics.md) |
| Generator exhaustion, comprehensions, zip, match, decorators/caches | [Iteration and decorators](references/iteration-decorators.md) |
| Narrow handlers, exception chaining, cleanup, lazy resource lifetime | [Errors and resources](references/errors-resources.md) |
| Imports, environment mismatch, lint/debug/profile, version gates | [Workflow and versions](references/workflow-versions.md) |
Load only the relevant guide. All guidance needed for this scope is local;
detailed library APIs, architecture, algorithms, concurrency and test methodology
are separate tasks.
## Workflow
1. Read the project's supported Python versions and tool configuration. Establish
absence semantics, aliasing/mutation, single-pass versus reusable input, and
resource ownership before changing behavior.
2. Trace the failure through object identities/rebinding, iterator consumption,
traceback causes, or module execution order. Ask the owner if unresolved
ownership or data-loss policy determines the fix.
3. Prefer a built-in/stdlib operation or direct loop. Preserve failure, lifetime,
and execution-model behavior; laziness, copying and argument binding are
observable contracts, not cosmetic choices.
4. Update affected callers together. For multi-file work, track pending, complete
and blocked changes/checks.
5. Separate observable defects from style preferences; explain a concrete failure
or cite the repository rule. Select checks under repository policy: repeated
calls, passed empty containers, alias independence, one-shot streams,
malformed input and cleanup on failure
as relevant. Preserve the supported runtime instead of adopting local syntax
or replacing tools by habit.
## High-risk gotchas
- Assignment and shallow copying share objects; frozen outer containers are not
deeply immutable. Default arguments and closure capture can retain shared state.
- Preserve valid zero/empty values: use `is None` or a private sentinel for absence.
An exhausted generator is still truthy.
+ - In optimized function scopes, `locals()` yields a snapshot; mutating its dict
+ cannot update the actual local variables. Frame-local debugger access differs.
- Lazy execution defers errors and can retain resources. `break` does not promise
iterator closure. Never return an iterator over a closed resource or close a
borrowed stream without ownership transfer.
- Catch expected failures around the smallest relevant operation. Preserve causes
and consumer failures during cleanup; silent empty results are not recovery.
Assertions and type annotations do not validate untrusted input.
- Context-manager exit behavior is resource-specific. Decorators must preserve
arguments, results, exceptions and sync/async/generator execution models.
- Check [version gates](references/workflow-versions.md#version-gates-preserve-the-declared-minimum)
before changing imports, encodings or introspection. The guide and stdlib
examples target Python 3.15; third-party tools need separate compatibility checks.
## Completion and evidence
Report the semantic change and affected callers, mutation/resource policy, boundary
cases, exact checks actually run and remaining runtime/version gaps. Do not silently
skip required work or call static review runtime verification.
Optional installed-skill handoffs: **python-stdlib** for library APIs,
**python-api-design** for typing/class protocols, **python-concurrency** for
execution coordination, **python-algorithms** for data structures/complexity,
- **python-tdd** for tests, **python-system-design** for packaging/deployment.
+ **python-tdd** for tests, **python-system-design** for packaging/deployment,
+ **python-performance** for profiling, benchmarking and evidence-based optimization.
None is an installation dependency.
See [README](README.md#sources-and-adaptation) for pinned source coverage,
correction decisions, installation and example commands;
[LICENSE.upstream](LICENSE.upstream) preserves attribution.