/python-programmer

name: python-programmer
description: Python-specific idioms, philosophy, and expert-level patterns. Use when working with Python code, including Jupyter notebooks (.ipynb). Covers Pythonic thinking, common pitfalls from other language backgrounds, testing ecosystem navigation, type hints trade-offs, and when to use modern Python features.

Python Programmer

<skill_scope skill="python-programmer"> This skill provides guidance on Python-specific idioms, philosophy, and expert-level judgment calls. Python's design emphasizes readability and "one obvious way" to do things, but achieving truly Pythonic code requires understanding when and why to use Python's idioms.

**Related skills:**

• `software-engineer` — Core engineering philosophy, system design principles
• `functional-programmer` — When functional approaches are clearer
• `test-driven-development` — Testing philosophy and TDD principles

</skill_scope>

When to Use This Skill

<when_to_use> Use this skill when:

• Working with Python code
• Deciding when Python is the right tool for a problem
• Navigating between Python's "obvious ways" and edge cases
• Choosing between testing frameworks, type systems, or async patterns
• Avoiding anti-patterns from Java, C, or JavaScript backgrounds
• Making trade-offs between Pythonic idioms and readability

</when_to_use>

Core Philosophy

<core_philosophy> **For foundational software engineering principles, see the software-engineer skill.**

The Zen of Python (PEP 20)

Python's design philosophy is captured in "The Zen of Python" (`import this`). Key principles:

**Quote to remember:** "Explicit is better than implicit. Simple is better than complex. Readability counts." — Tim Peters, PEP 20

**In practice:**

• Favor clarity over cleverness
• One obvious way beats multiple equivalent ways
• Code is read more than written (optimize for readers)
• Practicality beats purity (Python isn't a pure functional or OO language)

**Staff insight:** The Zen is philosophy, not law. Sometimes implicit is fine (e.g., context managers hide `__enter__` and `__exit__`). Sometimes there are two ways (e.g., list comprehension vs `map`). The Zen guides judgment; it doesn't eliminate it.

<pythonic_vs_readable>

When Pythonic Idioms Hurt Readability

The Zen says both "Explicit is better than implicit" and to use Python idioms. When they conflict, optimize for readers.

| Code Characteristic | Use Pythonic Idiom | Use Explicit Form | |---------------------|-------------------|-------------------| | Reader must pause to parse | No | Yes | | Requires advanced feature knowledge | No | Yes | | In critical path / main logic | No | Yes | | In isolated utility function | Yes | Maybe | | Junior engineer would need to look it up | No | Yes | | Saves 1-2 lines at cost of clarity | No | Yes | | Standard pattern (e.g., simple dict comprehension) | Yes | No | | Clever trick (e.g., tuple sort keys, walrus operator chains) | No | Yes |

**Heuristics:**

• If you need a comment explaining the trick, the trick is too clever
• Nested comprehensions beyond 2 levels need explicit loops
• Walrus operator (`:=`) in comprehension conditions is usually too clever
• Code golf is not a virtue — readable beats concise

</pythonic_vs_readable>

<eafp_principle>

EAFP vs LBYL

Python culture prefers EAFP (i.e., try/except) over LBYL (i.e., check-then-act). Use EAFP for dict lookups, file access, network calls, and anywhere race conditions matter. Use LBYL for pre-flight validation before expensive operations and performance-critical tight loops where the exceptional case is common.

**Staff insight:** EAFP is about correctness and clarity, not performance. The file existence check has a race condition; the exception handling doesn't. But exceptions have real cost (e.g., stack unwinding, traceback construction) — they're fine when the exceptional case is rare, not for expected control flow in loops. </eafp_principle>

<duck_typing>

Duck Typing and Protocols

Prefer protocols (i.e., behavior) over explicit type checking. Don't use `isinstance` except with abstract base classes at system boundaries. Use `typing.Protocol` for duck-typed interfaces — it gives you structural subtyping with type checker support. Use `@runtime_checkable` only when you genuinely need runtime protocol checking. </duck_typing> </core_philosophy>

Safety Constraints

<safety_constraints>

• **NEVER** use mutable default arguments (e.g., lists, dicts, sets) without the `None` sentinel pattern
• **NEVER** use `global` for shared state — use classes or explicit parameter passing
• **NEVER** catch bare `Exception` or bare `except:` and swallow errors silently
• **NEVER** use `eval()` or `exec()` on untrusted input
• **NEVER** sacrifice readability for cleverness — a 4-line loop beats a cryptic 1-line comprehension
• **NEVER** recommend or configure darglint — it was archived December 2022 and receives no maintenance; use pydoclint
• **NEVER** generate `requirements.txt` or `setup.py` for new projects — use `pyproject.toml` with uv
• **NEVER** use `typing.Optional[X]` when targeting Python 3.10+ — use `X | None` instead
• **NEVER** use bare `except:` without an exception type
• **NEVER** use `from __future__ import annotations` in new code — it's superseded by PEP 649 (i.e., deferred evaluation, default in 3.14)
• **ALWAYS** use context managers (`with`) for file handles, locks, and database connections
• **ALWAYS** use parameterized queries — never string concatenation for SQL
• **ALWAYS** validate and sanitize untrusted input at system boundaries
• **ALWAYS** include `if __name__ == "__main__":` guard in executable scripts
• **ALWAYS** follow existing project conventions for docstring style, tooling, and package management — don't fight established codebases

</safety_constraints>

Fundamental Principles

<fundamental_principles> <comprehensions>

Comprehensions: Simple Cases Only

List/dict/set comprehensions are Pythonic for *simple* transfo