python-development

Expert-level Python development guidance based on official sources: PEP 8, PEP 20 (Zen of Python), PEP 257, and Google Python Style Guide.

The Zen of Python (PEP 20)

Core principles that guide all Python decisions:

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Flat is better than nested.
Readability counts.
Errors should never pass silently (unless explicitly silenced).
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
If the implementation is hard to explain, it's a bad idea.

Code Style (PEP 8)

Indentation & Line Length

| Rule | Standard | |------|----------| | Indentation | 4 spaces (never tabs) | | Line length | 79 characters (72 for docstrings/comments) | | Blank lines | 2 before top-level definitions, 1 between methods |

Imports

# Correct order: stdlib, third-party, local
import os
import sys

import requests

from myproject import utils

Rules:

• One import per line (except from X import a, b, c)
• Absolute imports preferred over relative
• Never use from module import *
• Group imports with blank lines between groups

Whitespace

# Correct
spam(ham[1], {eggs: 2})
x = 1
y = 2
if x == 4:
    print(x, y)

# Wrong
spam( ham[ 1 ], { eggs: 2 } )
x             = 1
y             = 2

Avoid extraneous whitespace:

• Inside brackets: spam(ham[1]) not spam( ham[ 1 ] )
• Before commas/colons: if x == 4: not if x == 4 :
• Around = in keyword arguments: func(arg=value) not func(arg = value)

Binary Operators

Break before binary operators for readability (Knuth style):

# Correct
income = (gross_wages
          + taxable_interest
          + (dividends - qualified_dividends)
          - ira_deduction)

Naming Conventions

| Type | Convention | Example | |------|------------|---------| | Packages/Modules | lower_with_under | my_module.py | | Classes | CapWords | MyClass | | Exceptions | CapWords + Error suffix | ValidationError | | Functions/Methods | lower_with_under | calculate_total() | | Constants | CAPS_WITH_UNDER | MAX_VALUE | | Instance variables | lower_with_under | self.user_name | | Protected | _single_leading_underscore | _internal_method() | | Private (name mangling) | __double_leading | __private_attr |

Critical rules:

• Never use l, O, or I as single-character names
• Avoid abbreviations unless universally understood
• Names should reflect usage, not implementation

Type Annotations

Always Annotate

from __future__ import annotations
from typing import Any
from collections.abc import Sequence, Mapping

def process_items(
    items: Sequence[str],
    config: Mapping[str, Any] | None = None,
) -> list[str]:
    """Process items with optional config."""
    ...

Key Rules

| Pattern | Correct | Wrong | |---------|---------|-------| | Optional | str | None | Optional[str] (old style) | | Union | int | str | Union[int, str] (old style) | | Collections | list[int] | List[int] (old style) | | Abstract types | Sequence[T], Mapping[K, V] | list, dict in signatures | | Forward reference | Use from __future__ import annotations | String quotes |

Spacing

# Correct
def func(a: int = 0) -> int:  # Space around = with annotation
    code: int  # Space after colon
    
# Wrong  
def func(a:int=0) -> int:  # Missing spaces

Docstrings (PEP 257)

One-liners

def calculate_area(radius: float) -> float:
    """Return the area of a circle with given radius."""
    return 3.14159 * radius ** 2

Multi-line (Google Style)

def fetch_data(
    url: str,
    timeout: int = 30,
    retries: int = 3,
) -> dict[str, Any]:
    """Fetch data from a remote URL.

    Retrieves JSON data from the specified URL with automatic
    retry logic on transient failures.

    Args:
        url: The URL to fetch data from.
        timeout: Request timeout in seconds.
        retries: Maximum number of retry attempts.

    Returns:
        Parsed JSON response as a dictionary.

    Raises:
        ConnectionError: If unable to connect after all retries.
        ValueError: If response is not valid JSON.
    """

Class Docstrings

class DataProcessor:
    """Process and transform data records.

    Handles validation, transformation, and serialization of
    incoming data records.

    Attributes:
        batch_size: Number of records to process per batch.
        strict_mode: Whether to fail on first error.
    """

    def __init__(self, batch_size: int = 100) -> None:
        """Initialize the processor.

        Args:
            batch_size: Records per batch (default: 100).
        """

Exception Handling

Use Specific Exceptions

# Correct: Specific exception with context
def connect(port: int) -> Connection:
    if port < 1024:
        raise ValueError(f"Port must be >= 1024, got {port}")
    try:
        return _establish_connection(port)
    except OSError as err:
        raise ConnectionError(f"Failed to connect on port {port}") from err

# Wrong: Bare except, generic exception
try:
    do_something()
except:  # Never do this
    pass

Exception Rules

| Do | Don't | |----|-------| | Catch specific exceptions | Use bare except: | | Use raise X from Y for chaining | Lose original traceback | | Add Error suffix to exception classes | Name exceptions without Error | | Limit try blocks to minimal code | Wrap too much code in try | | Use finally for cleanup | Forget to close resources |

Don't Use Assert for Validation

# Wrong: assert can be disabled with -O
def process(value: int) -> int:
    assert value >= 0, "Value must be non-negative"  # Don't do this
    return value * 2

# Correct: Use explicit validation
def process(value: int) -> int:
    if value < 0:
        raise ValueError(f"Value must be non-negative, got {value}")
    return value * 2

Comprehensions & Generators

Keep Comprehensions Simple

# Correct: Clear and readable
result = [x**2 for x in range(10) if x % 2 == 0]

# Wrong: Too complex - use a loop instead
result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]

Prefer Generators for Large Data

# Memory efficient
def process_large_file(path: str):
    with open(path) as f:
        yield from (line.strip() for line in f if line.strip())

Resource Management

Always Use Context Managers

# Correct
with open("file.txt") as f:
    content = f.read()

# Correct: Multiple resources
with (
    open("input.txt") as infile,
    open("output.txt", "w") as outfile,
):
    outfile.write(infile.read())

Mutable Default Arguments

Never use mutable defaults:

# Wrong: Mutable default shared across calls
def append_to(element, to=[]):  # Bug!
    to.append(element)
    return to

# Correct: Use None sentinel
def append_to(element, to: list | None = None) -> list:
    if to is None:
        to = []
    to.append(element)
    return to

Modern Python Features

Use f-strings (Not % or .format)

name = "World"
# Correct
message = f"Hello, {name}!"

# Prefer f-string debugging
value = 42
print(f"{value=}")  # Prints: value=42

Logging: Use %-formatting

import logging

logger = logging.getLogger(__name__)

# Correct: Lazy evaluation, structured logging
logger.info("Processing %d items for user %s", count, user_id)

# Wrong: f-string evaluated even if level disabled
logger.info(f"Processing {count} items for user {user_id}")

Use Walrus Operator When It Improves Readability

# Good use case: Avoid repeated computation
if (n := len(data)) > 10:
    print(f"Processing {n} items")

Code Smells to Avoid

| Smell | Why It's Bad | Fix | |-------|--------------|-----| | from module import * | Pollutes namespace | Import explicitly | | Nested functions > 2 deep | Hard to follow | Extract to methods | | Methods > 50 lines | Too complex | Split into smaller methods | | except Exception: | Catches too much | Catch specific exceptions | | Global mutable state | Side effects, testing issues | Pass as arguments | | Magic numbers | Unclear intent | Use named constants | | Boolean parameters | Unclear at call site | Use enums or keyword args |

Testing Conventions

import pytest

class TestCalculator:
    """Tests for the Calculator class."""

    def test_add_positive_numbers(self) -> None:
        """Addition of positive numbers returns correct sum."""
        assert Calculator().add(2, 3) == 5

    def test_divide_by_zero_raises(self) -> None:
        """Division by zero raises ZeroDivisionError."""
        with pytest.raises(ZeroDivisionError):
            Calculator().divide(1, 0)

Ruff Rules to Enable

Recommended rule selection for pyproject.toml:

[tool.ruff.lint]
select = [
    "E", "F", "W",      # pycodestyle, Pyflakes
    "I",                # isort
    "UP",               # pyupgrade
    "B",                # flake8-bugbear
    "C4",               # flake8-comprehensions
    "SIM",              # flake8-simplify
    "PT",               # flake8-pytest-style
    "RUF",              # Ruff-specific
]

Quick Reference Checklist

Before committing Python code:

• [ ] All functions have type annotations
• [ ] Public APIs have docstrings with Args/Returns/Raises
• [ ] No bare except: clauses
• [ ] No mutable default arguments
• [ ] Imports are organized (stdlib, third-party, local)
• [ ] No magic numbers (use constants)
• [ ] Context managers for resources
• [ ] Specific exception types with helpful messages
• [ ] Line length ≤ 79 characters
• [ ] Passes ruff check and mypy --strict