python

Python Best Practices

Overview

Aspect	Recommendation
Version	Python 3.11+
Type Hints	Always use
Formatter	Ruff or Black
Linter	Ruff
Package Manager	uv or Poetry

---

Type Hints

Basic Types

from typing import Optional

# ✅ Use type hints everywhere
def greet(name: str) -> str:
    return f"Hello, {name}!"

# ✅ Optional (can be None)
def find_user(user_id: int) -> Optional[dict]:
    # Returns dict or None
    pass

# ✅ Python 3.10+ union syntax
def process(value: str | int) -> str:
    return str(value)

Collections

from typing import TypedDict

# ✅ List, dict, set (Python 3.9+)
def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# ✅ TypedDict for structured dicts
class User(TypedDict):
    id: int
    name: str
    email: str

def get_user() -> User:
    return {"id": 1, "name": "John", "email": "[email protected]"}

Generics

from typing import TypeVar, Generic

T = TypeVar('T')

class Repository(Generic[T]):
    def __init__(self) -> None:
        self.items: list[T] = []
    
    def add(self, item: T) -> None:
        self.items.append(item)
    
    def get_all(self) -> list[T]:
        return self.items

---

Modern Python Idioms

Dataclasses

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class User:
    id: int
    name: str
    email: str
    created_at: datetime = field(default_factory=datetime.now)
    tags: list[str] = field(default_factory=list)

# Frozen (immutable)
@dataclass(frozen=True)
class Config:
    api_url: str
    timeout: int = 30

Pydantic Models (Validation)

from pydantic import BaseModel, EmailStr, Field

class UserCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    email: EmailStr
    age: int = Field(..., ge=0, le=150)

class UserResponse(BaseModel):
    id: int
    name: str
    email: str
    
    model_config = {"from_attributes": True}  # Pydantic v2