# Follow PEP 8
# Use type hints
from typing import List, Optional

async def get_devices(
    limit: int = 100,
    offset: int = 0
) -> List[dict]:
    """
    Get list of devices.
    
    Args:
        limit: Maximum number of devices to return
        offset: Number of devices to skip
        
    Returns:
        List of device dictionaries
    """
    # Implementation
    pass

# Use descriptive variable names
device_power_consumption = calculate_power()  # Good
pwr = calc()  # Bad

# Constants in UPPER_CASE
MAX_RETRY_ATTEMPTS = 3
DEFAULT_TIMEOUT = 30

# tests/test_device_manager.py
import pytest
from unittest.mock import Mock, patch
from backend.device_manager import DeviceManager

@pytest.fixture
def device_manager():
    return DeviceManager()

@pytest.fixture
def mock_device():
    return {
        'device_ip': '192.168.1.100',
        'device_name': 'Test Device',
        'is_active': True
    }

async def test_add_device(device_manager, mock_device):
    """Test adding a new device."""
    result = await device_manager.add_device(mock_device)
    assert result['device_ip'] == mock_device['device_ip']
    assert result['success'] is True

async def test_device_discovery_timeout():
    """Test discovery timeout handling."""
    with patch('backend.device_manager.discover') as mock_discover:
        mock_discover.side_effect = TimeoutError()
        
        manager = DeviceManager()
        result = await manager.discover_devices()
        
        assert result == []
        assert manager.last_error == "Discovery timeout"

# Use docstrings for all public functions/classes
def calculate_energy_cost(
    kwh: float,
    rate: float,
    tax_rate: float = 0.0
) -> float:
    """
    Calculate energy cost including taxes.
    
    Args:
        kwh: Energy consumption in kilowatt-hours
        rate: Electricity rate per kWh
        tax_rate: Tax rate as decimal (e.g., 0.08 for 8%)
        
    Returns:
        Total cost including taxes
        
    Raises:
        ValueError: If kwh or rate is negative
        
    Example:
        >>> calculate_energy_cost(100, 0.12, 0.08)
        12.96
    """
    if kwh < 0 or rate < 0:
        raise ValueError("Energy and rate must be non-negative")
    
    base_cost = kwh * rate
    return base_cost * (1 + tax_rate)

@app.get("/api/devices/{device_ip}/stats")
async def get_device_stats(
    device_ip: str,
    period: str = Query("day", regex="^(hour|day|week|month)$")
) -> dict:
    """
    Get device statistics for specified period.
    
    **Path Parameters:**
    - `device_ip`: IP address of the device
    
    **Query Parameters:**
    - `period`: Time period (hour, day, week, month)
    
    **Returns:**
    ```json
    {
        "device_ip": "192.168.1.100",
        "period": "day",
        "total_kwh": 2.5,
        "average_power": 104.2,
        "peak_power": 1500,
        "cost": 0.30
    }
    ```
    
    **Errors:**
    - 404: Device not found
    - 400: Invalid period
    """
    # Implementation

# Use async/await for I/O operations
async def fetch_device_data(device_ip: str):
    async with aiohttp.ClientSession() as session:
        async with session.get(f"http://{device_ip}/data") as response:
            return await response.json()

# Batch operations when possible
async def update_multiple_devices(devices: List[str]):
    tasks = [fetch_device_data(ip) for ip in devices]
    return await asyncio.gather(*tasks)

# Validate all inputs
from pydantic import BaseModel, validator, IPvAnyAddress

class DeviceInput(BaseModel):
    device_ip: IPvAnyAddress
    device_name: str
    
    @validator('device_name')
    def validate_name(cls, v):
        if not v or len(v) > 100:
            raise ValueError('Invalid device name')
        return v

# Use parameterized queries
db.execute(
    "SELECT * FROM devices WHERE device_ip = ?",
    (device_ip,)
)  # Good

# Never do this:
db.execute(f"SELECT * FROM devices WHERE device_ip = '{device_ip}'")  # Bad!

# Provide meaningful error messages
class DeviceNotFoundError(Exception):
    def __init__(self, device_ip: str):
        self.device_ip = device_ip
        super().__init__(f"Device not found: {device_ip}")

# Handle errors gracefully
try:
    device = await get_device(device_ip)
except DeviceNotFoundError as e:
    logger.warning(f"Device lookup failed: {e}")
    return JSONResponse(
        status_code=404,
        content={"error": str(e)}
    )
except Exception as e:
    logger.error(f"Unexpected error: {e}", exc_info=True)
    return JSONResponse(
        status_code=500,
        content={"error": "Internal server error"}
    )