agentharness python.instructions.md

Generated from languages/python/CONVENTIONS.md by tools/generate-copilot-instructions.sh (https://github.com/andr-ca/agentharness) — do not hand-edit; regenerate instead. Only applied by Copilot when editing a file matching *.py.

---

Python Conventions & Best Practices

.claude/skills/python-conventions/SKILL.md has the terse, actionable version of this doc (naming, imports, type hints, three pitfalls, testing structure) — load that for day-to-day work. This doc adds: the handful of choices this repo actually makes among multiple valid options (most Python style below is just PEP 8/typing convention, not a decision — see PEP 8 and the Google Python Style Guide for everything not listed here), plus two pitfalls the skill doesn't cover.

Choices this repo makes (not just "the PEP 8 default")

• Line length: 88 characters (Black's default), not PEP 8's original 79 — check the project's own pyproject.toml first, since an existing project may have picked something else.
• String quotes: double by default ("like this"); single only to avoid escaping ('It\'s here' reads better than "It's here" when it would otherwise need a backslash). A formatter normalizes this — don't hand-police it in review.
• Docstrings: Google style (reference), unless the project's existing code already uses a different one consistently.

Two pitfalls the skill doesn't cover

Global mutable state — module-level dicts/lists accumulating shared state are hard to test and reason about; encapsulate in a class instead:

# Avoid: module-level cache any caller can mutate
_cache = {}
def get_cached(key):
    if key not in _cache:
        _cache[key] = expensive_operation(key)
    return _cache[key]

# Prefer: instance-scoped, explicit lifetime
class Cache:
    def __init__(self):
        self._cache = {}
    def get(self, key):
        return self._cache.setdefault(key, expensive_operation(key))