Python Guidelines

Python Guidelines

Integrate into existing code. Don't append to it.

> Simple is better than complex. Flat is better than nested.

> Errors should never pass silently. Unless explicitly silenced.

> If the implementation is hard to explain, it's a bad idea.

>

> -- The Zen of Python (PEP 20)

Code Philosophy

• Match existing naming, importing, and signature patterns. Use existing utilities and data structures.
• Functions have a single purpose. Don't hardcode behavior that makes them less general.
• No trivial wrappers for 2 lines or less. Inline it.
• Inline single-use variables at the usage site.
• No try/except unless critical. Let errors surface.
• No duplicate code.
• Functions handle their own input validation. No if-else checks in main.
• Use pathlib, not os.path.
• Consider API and time costs for MongoDB/Gemini/OpenAI/Claude/Voyage.

Don't do this:

# Generate comment report only if requested
if include_comments:
    comment_report = generate_comments_report(start_date, end_date, team, verbose)
else:
    comment_report = ""
    print("   Skipping comment analysis (disabled)")

Do this:

comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""

Ask yourself: "Am I adding code, or integrating into what exists?"

Simplicity Over Abstraction

YAGNI: You Aren't Gonna Need It.

Don't build for hypothetical future requirements. Add complexity only when the current task demands it.

Avoid:

• Abstract base classes for a single implementation
• Configuration options nobody asked for
• Error handling for impossible scenarios
• Wrapper classes around a single function
• Dependency injection when direct calls work
• Generic type parameters for one concrete type

Three similar lines of code is better than a premature abstraction. Refactor when the third real use case appears, not before.

But simplicity does not mean chaos. Always maintain:

• Clear function names that describe what they do
• Logical grouping of related code into modules
• Consistent naming conventions across the project
• Clean separation between I/O and logic
• Explicit parameters over global state or side effects

Ask yourself: "Is this abstraction solving a problem I have right now, or one I'm imagining?"

Environment

• Package manager: uv (NOT pip)
• Virtual env: source .venv/bin/activate or uv run python -c "..."
• 3rd party packages: Find source with python -c "import pkg; print(pkg.__file__)", then Read.

Testing Discipline

Never assume anything. Run python -c "..." to verify hypotheses about code behavior, package functions, or data structures before suggesting a plan or exiting plan mode.

Ask yourself: "Did I verify this with python -c before building on it?"

Google-Style Docstrings

• Summary: Imperative mood ("Calculate", not "Calculates")
• Args: All parameters with types and descriptions. No default values. Indent 4 spaces.
• Types: int | str unions, uppercase shapes (N, M), lowercase builtins list/dict/tuple, capitalize Any/Path
• Optional: name (type, optional): Description
• Returns: Always (type) in parentheses. Never tuple types. Separate named values for multiple returns.
• Sections: Examples (>>>), Notes, References (plaintext only). Section titles at 0 indent.
• Omit: "Returns:" if nothing returned, "Args:" if no args, "Raises:" unless critical
• Classes: Attributes section only, omit Methods/Args. Don't convert single-line to multiline.
• __init__: Args only. No Examples/Notes/Methods/References.
• Tests: Single-line docstrings only.
• Erase default values from existing arg descriptions. Optionally include minimal Examples.

Ask yourself: "Would a new developer understand this function from the docstring alone?"

Reference Files

Read the matching file before you write the code, not after:

• references/idiomatic-patterns.md -- read when writing loops, comprehensions, unpacking, context managers, or dataclasses. 18 idioms with before/after code
• references/zen-of-python.md -- read when choosing between two designs or judging whether an abstraction earns its place. PEP 20 with annotations
• references/google-style-guide.md -- read when deciding on exceptions, mutable defaults, import style, naming, or comments
• references/effective-python-tips.md -- read when reviewing or refactoring existing code. Key tips from "Effective Python" (Brett Slatkin)