standards-python

Python Coding Standards

Core Principles

1. Simplicity: Simple, understandable code
2. Readability: Readability over cleverness
3. Maintainability: Code that's easy to maintain
4. Testability: Code that's easy to test
5. DRY: Don't Repeat Yourself - but don't overdo it

General Rules

• Early Returns: Use early returns to avoid nesting
• Descriptive Names: Meaningful names for variables and functions
• Minimal Changes: Only change relevant code parts
• No Over-Engineering: No unnecessary complexity
• Minimal Comments: Code should be self-explanatory. No redundant comments!

Naming Conventions

Element	Convention	Example
Variables/Functions	snake_case	get_user_by_id, is_active
Classes	PascalCase	UserService, ApiClient
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT
Private	Prefix with _	_internal_method
Files/Modules	snake_case	user_service.py

Project Structure

myproject/
├── src/
│   ├── __init__.py
│   ├── main.py              # Entry point
│   ├── config.py            # Settings, env vars
│   ├── models.py            # Domain models (dataclasses/Pydantic)
│   ├── schemas.py           # Request/response DTOs
│   ├── services/
│   │   ├── __init__.py
│   │   └── user_service.py  # Business logic
│   └── repositories/
│       ├── __init__.py
│       └── user_repo.py     # Data access
├── tests/
│   ├── __init__.py
│   ├── test_services.py
│   └── test_repositories.py
├── pyproject.toml
└── README.md

Code Style (PEP 8 + PEP 484)

from dataclasses import dataclass

@dataclass
class User:
    id: str
    name: str
    email: str
    age: int | None = None  # Python 3.10+ union syntax

def get_user_by_id(user_id: str) -> User | None:
    if not user_id:
        raise ValueError("user_id cannot be empty")
    # implementation...

Best Practices

# Type hints everywhere
def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# Pydantic v2 for validation
from pydantic import BaseModel, Field, field_validator, EmailStr

class UserCreate(BaseModel):
    name: str = Field(..., min_length=2, max_length=50)
    email: EmailStr
    age: int | None = Field(None, ge=0, le=150)

    @field_validator('name')
    @classmethod
    def name_must_be_alphanumeric(cls, v: str) -> str:
        if not v.replace(' ', '').isalnum():
            raise ValueError('Name must be alphanumeric')
        return v.strip()

# Context managers
with open('file.txt', 'r') as f:
    content = f.read()

# Prefer pathlib over os.path
from pathlib import Path
config_path = Path(__file__).parent / 'config.yaml'