Style and Idioms

## Module names: short, lowercase, no underscores for readability if single word
import collections
import json_parser

## Package names: same as modules
# mypackage/

# Class names: CapWords (CamelCase)
class UserRepository:
    pass

class HTTPConnectionError(Exception):
    pass

# Exception names: end with "Error" if they indicate an error
class ValidationError(ValueError):
    pass

# Function and variable names: snake_case
def calculate_total(order_items):
    subtotal = sum(item.price for item in order_items)
    return subtotal

# Constants: UPPER_SNAKE_CASE at module level
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30.0

# Private attributes: single leading underscore (convention, not enforced)
class Database:
    def __init__(self):
        self._connection = None
        self._pool = []

    def _ensure_connected(self):
        if self._connection is None:
            self._connect()

# Name mangling: double leading underscore (actually enforced by interpreter)
class Base:
    def __init__(self):
        self.__value = 42  # stored as _Base__value

class Derived(Base):
    def get_parent_value(self):
        # self.__value would be _Derived__value -- different attribute
        return self._Base__value

# Implicit line continuation inside brackets -- the preferred way
result = some_function(
    first_argument,
    second_argument,
    third_argument,
    fourth_argument,
)

# Dictionary display
config = {
    "database_url": "postgresql://localhost/mydb",
    "max_connections": 10,
    "timeout_seconds": 30,
}

# Long string -- use parentheses, not backslash continuation
query = (
    "SELECT users.id, users.name, orders.total "
    "FROM users "
    "JOIN orders ON users.id = orders.user_id "
    "WHERE orders.created_at > %s"
)

# Avoid backslash continuation except in rare cases
# Bad:
if a == 1 and \
   b == 2 and \
   c == 3:
    pass

# Good:
if (
    a == 1
    and b == 2
    and c == 3
):
    pass

# Standard library
import os
import sys
from pathlib import Path
from typing import Optional

# Third-party
import httpx
from pydantic import BaseModel, field_validator

# Local application
from myapp.models import User
from myapp.services import AuthService
from myapp.utils import format_date

# Avoid wildcard imports -- they pollute the namespace and make it
# impossible to determine where a name came from
# Bad:
from os.path import *

# Good:
from os.path import join, exists, isfile

# Use absolute imports by default -- they are unambiguous
# Bad (relative):
from ..models import User

# Good (absolute):
from myapp.models import User

# Relative imports are acceptable only within a package when the
# package structure makes absolute paths unwieldy

from typing import Optional, Union

def greet(name: str) -> str:
    return f"Hello, {name}"

def divide(numerator: float, denominator: float) -> Optional[float]:
    if denominator == 0:
        return None
    return numerator / denominator

def process(value: Union[int, str]) -> str:
    return str(value)

# Union via pipe operator (3.10+)
def process(value: int | str) -> str:
    return str(value)

# Optional is just a shorthand for X | None
def find_user(user_id: int) -> User | None:
    return db.query(User).filter_by(id=user_id).first()

# Type alias with the `type` statement (3.12+)
type JSONValue = dict[str, "JSONValue"] | list["JSONValue"] | str | int | float | bool | None

def parse(data: JSONValue) -> None:
    ...

from typing import TypeVar, Generic, Protocol, Any
from collections.abc import Sequence

T = TypeVar("T")

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

    def __len__(self) -> int:
        return len(self._items)

# Use Sequence instead of list for function parameters -- it accepts
# any iterable sequence type (list, tuple, range, etc.)
def first_item(items: Sequence[T]) -> T | None:
    return items[0] if items else None

# Protocol for structural subtyping (duck typing with static checking)
class Drawable(Protocol):
    def draw(self, surface: Any) -> None: ...

class Circle:
    def draw(self, surface: Any) -> None:
        print(f"Drawing circle on {surface}")

class Rectangle:
    def draw(self, surface: Any) -> None:
        print(f"Drawing rectangle on {surface}")

def render_all(objects: list[Drawable], surface: Any) -> None:
    for obj in objects:
        obj.draw(surface)  # type checker verifies draw() exists

result = complex_third_party_function(data)  # type: ignore[return-value]  # bug in library stubs

[project]
name = "myapp"
version = "2.1.0"
description = "A well-structured Python application"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.27",
    "pydantic>=2.0",
    "sqlalchemy>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=5.0",
    "ruff>=0.4",
    "mypy>=1.10",
    "hypothesis>=6.100",
]
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.5",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
target-version = "py311"
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]

[tool.mypy]
strict = true
python_version = "3.11"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"

myproject/
    pyproject.toml
    README.md
    myproject/
        __init__.py
        main.py
        models.py
        services.py
    tests/
        test_main.py
        test_models.py

myproject/
    pyproject.toml
    README.md
    src/
        myproject/
            __init__.py
            main.py
            models.py
            services.py
    tests/
        test_main.py
        test_models.py

myproject/
    pyproject.toml
    README.md
    .gitignore
    .github/
        workflows/
            ci.yml
    src/
        myproject/
            __init__.py
            __main__.py
            models.py
            services.py
            utils.py
    tests/
        __init__.py
        conftest.py
        test_models.py
        test_services.py

# unittest style -- verbose and rigid
import unittest

class TestCalculator(unittest.TestCase):
    def test_add(self):
        self.assertEqual(1 + 1, 2)

    def test_divide_by_zero(self):
        with self.assertRaises(ZeroDivisionError):
            1 / 0

# pytest style -- concise and Pythonic
def test_add():
    assert 1 + 1 == 2

def test_divide_by_zero():
    with pytest.raises(ZeroDivisionError):
        1 / 0

import pytest
from myproject.models import User, Session

@pytest.fixture
def db_session():
    """Creates a database session that rolls back after each test."""
    session = Session()
    session.begin_nested()
    yield session
    session.rollback()
    session.close()

@pytest.fixture
def sample_user(db_session):
    """Creates a user that exists in the database for the test."""
    user = User(name="Alice", email="alice@example.com")
    db_session.add(user)
    db_session.commit()
    return user

def test_user_retrieval(db_session, sample_user):
    found = db_session.query(User).filter_by(name="Alice").first()
    assert found is not None
    assert found.email == "alice@example.com"

def test_user_update(db_session, sample_user):
    sample_user.name = "Bob"
    db_session.commit()
    found = db_session.query(User).filter_by(name="Bob").first()
    assert found is not None

import pytest

@pytest.mark.parametrize(
    "input_value, expected",
    [
        ("hello", "HELLO"),
        ("World", "WORLD"),
        ("", ""),
        ("123", "123"),
        ("already UPPER", "ALREADY UPPER"),
    ],
)
def test_uppercase(input_value, expected):
    assert input_value.upper() == expected

@pytest.mark.parametrize("x", [0, 1, 2, 3, 10, 100])
@pytest.mark.parametrize("y", [0, 1, 5, 10])
def test_multiply(x, y):
    assert x * y == y * x  # commutativity property

from unittest.mock import MagicMock, patch, PropertyMock

def test_external_api_call():
    with patch("myproject.services.httpx.Client") as MockClient:
        mock_response = MagicMock()
        mock_response.status_code = 200
        mock_response.json.return_value = {"id": 1, "name": "Alice"}

        mock_instance = MockClient.return_value.__enter__.return_value
        mock_instance.get.return_value = mock_response

        from myproject.services import fetch_user
        result = fetch_user(1)

        assert result["name"] == "Alice"
        mock_instance.get.assert_called_once_with("https://api.example.com/users/1")

# Bad: return code pattern (Java/C style, un-Pythonic)
def read_config(path):
    if not os.path.exists(path):
        return None, "File not found"
    try:
        with open(path) as f:
            return json.load(f), None
    except json.JSONDecodeError as e:
        return None, str(e)

config, error = read_config("config.json")
if error:
    print(f"Error: {error}")
    sys.exit(1)

# Good: exception pattern (Pythonic)
def read_config(path: str) -> dict:
    """Reads configuration from a JSON file.

    Raises:
        FileNotFoundError: If the config file does not exist.
        json.JSONDecodeError: If the file contains invalid JSON.
    """
    with open(path) as f:
        return json.load(f)

# Bad: bare except -- catches KeyboardInterrupt, SystemExit, GeneratorExit
try:
    result = process(data)
except:
    result = None

# Bad: catching Exception is only slightly better
try:
    result = process(data)
except Exception:
    result = None

# Good: catch the specific exception you expect
try:
    result = process(data)
except ValueError:
    logger.warning("Invalid data format, using default")
    result = get_default()

# Good: catch multiple specific exceptions when they share a handler
try:
    result = process(data)
except (ValueError, TypeError) as e:
    logger.warning(f"Data error: {e}")
    result = get_default()

class AppError(Exception):
    """Base exception for all application errors."""

class DatabaseError(AppError):
    """Errors related to database operations."""

class ConnectionError(DatabaseError):
    """Failed to connect to the database."""

class QueryError(DatabaseError):
    """A database query failed."""

class ValidationError(AppError):
    """Input data failed validation."""

def get_user(user_id: int) -> User:
    try:
        return db.query(User).filter_by(id=user_id).one()
    except NoResultFound:
        raise ValidationError(f"User {user_id} not found") from None

# Manual resource management -- verbose and easy to forget
def process_file(path):
    f = open(path)
    try:
        data = f.read()
        return transform(data)
    finally:
        f.close()

# Context manager -- concise and correct by construction
def process_file(path):
    with open(path) as f:
        data = f.read()
        return transform(data)

from contextlib import contextmanager
import time

@contextmanager
def measure_time(label: str):
    """Measures and logs the time taken by a block of code."""
    start = time.perf_counter()
    yield
    elapsed = time.perf_counter() - start
    print(f"[{label}] {elapsed:.4f}s")

# Usage
with measure_time("database query"):
    results = db.execute("SELECT * FROM large_table")

@contextmanager
def database_transaction(session):
    """Provides a database transaction that commits on success, rolls back on failure."""
    try:
        yield session
        session.commit()
    except Exception:
        session.rollback()
        raise

# Usage
with database_transaction(session):
    session.add(new_record)
    session.add(another_record)
    # If anything raises here, the transaction is rolled back automatically

class ManagedConnection:
    def __init__(self, host: str, port: int):
        self.host = host
        self.port = port
        self._socket = None

    def __enter__(self):
        self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        self._socket.connect((self.host, self.port))
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self._socket.close()
        self._socket = None
        return False  # do not suppress exceptions

    def send(self, data: bytes) -> None:
        self._socket.sendall(data)

from contextlib import suppress, redirect_stdout, closing

# suppress replaces try/except pass for expected exceptions
with suppress(FileNotFoundError):
    os.remove("temp_file.txt")

# redirect_stdout captures print output
import io
buffer = io.StringIO()
with redirect_stdout(buffer):
    print("This goes to the buffer, not stdout")
output = buffer.getvalue()

# closing works with objects that have a close() method but no context manager
import urllib.request
with closing(urllib.request.urlopen("https://example.com")) as response:
    data = response.read()

from hypothesis import given, strategies as st, assume

# Strategy: generate arbitrary lists of integers
int_lists = st.lists(st.integers(min_value=-1000, max_value=1000))

@given(int_lists)
def test_sort_preserves_length(items):
    """Sorting should not change the number of elements."""
    assert len(sorted(items)) == len(items)

@given(int_lists)
def test_sort_preserves_elements(items):
    """Sorting should not add or remove elements."""
    assert sorted(sorted(items)) == sorted(items)

@given(st.lists(st.integers()))
def test_sort_is_idempotent(items):
    """Sorting an already-sorted list returns the same list."""
    assert sorted(sorted(items)) == sorted(items)

@given(st.lists(st.integers()))
def test_reverse_reverses_sort(items):
    """Reversing a sorted list gives descending order."""
    assert sorted(items, reverse=True) == list(reversed(sorted(items)))

# Use assume to filter generated inputs
@given(st.integers(), st.integers())
def test_division_properties(numerator, denominator):
    assume(denominator != 0)
    result = numerator / denominator
    assert result * denominator == pytest.approx(numerator)

# Custom strategies
from myproject.models import User

user_strategy = st.builds(
    User,
    name=st.text(min_size=1, max_size=100, alphabet=st.characters(whitelist_categories=('L', 'N', 's'))),
    email=st.emails(),
    age=st.integers(min_value=0, max_value=150),
)

@given(user_strategy)
def test_user_name_not_empty(user):
    assert len(user.name) > 0

@given(st.text())
def test_encode_decode_roundtrip(text):
    """Encoding then decoding should return the original text."""
    assert text.encode("utf-8").decode("utf-8") == text

def fetch_user(user_id: int, include_orders: bool = False) -> dict:
    """Fetches a user from the database by ID.

    Args:
        user_id: The unique identifier of the user. Must be a positive integer.
        include_orders: Whether to include the user's order history
            in the response. Defaults to False.

    Returns:
        A dictionary containing user data with keys 'id', 'name', 'email'.
        If include_orders is True, also includes 'orders' with a list of
        order dictionaries.

    Raises:
        ValueError: If user_id is not a positive integer.
        NotFoundError: If no user exists with the given ID.

    Examples:
        >>> fetch_user(42)
        {'id': 42, 'name': "Alice'', "email': "alice@example.com''}

        >>> fetch_user(42, include_orders=True)
        {"id': 42, 'name': "Alice'', "email': "alice@example.com'', "orders': [...]}
    """
    if user_id <= 0:
        raise ValueError("user_id must be a positive integer")
    ...

def calculate_moving_average(data, window_size):
    """Calculate the moving average of a data series.

    Parameters
    ----------
    data : array_like
        Input data series. Must be a 1-dimensional sequence of numeric values.
    window_size : int
        The number of data points to include in each average.
        Must be positive and less than or equal to the length of data.

    Returns
    -------
    numpy.ndarray
        An array containing the moving averages. The output has
        length ``len(data) - window_size + 1``.

    Raises
    ------
    ValueError
        If window_size is not positive or exceeds the data length.

    See Also
    --------
    exponential_moving_average : Weighted moving average with exponential decay.

    Notes
    -----
    Uses a convolution-based implementation for numerical stability.
    """
    ...

def parse_config(path):
    """Parse a configuration file and return a validated config object.

    :param path: Path to the configuration file.
    :type path: str
    :returns: A validated configuration object.
    :rtype: Config
    :raises ConfigError: If the configuration file is malformed.
    :raises FileNotFoundError: If the file does not exist.
    """
    ...

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "myapp"
version = "2.1.0"
description = "A well-structured Python application"
readme = "README.md"
license = "MIT"
requires-python = ">=3.11"
authors = [
    {name = "Jane Doe", email = "jane@example.com"},
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "License :: OSI Approved :: MIT License",
]
dependencies = [
    "httpx>=0.27",
    "pydantic>=2.0",
]

[project.scripts]
myapp = "myapp.__main__:main"

[project.entry-points."myapp.plugins"]
csv_export = "myapp.plugins.csv:CSVExporter"

[project.urls]
Homepage = "https://github.com/janedoe/myapp"
Documentation = "https://myapp.readthedocs.io"
Repository = "https://github.com/janedoe/myapp"

# Legacy setup.py -- do not use for new projects
from setuptools import setup, find_packages

setup(
    name="myapp",
    version="2.1.0",
    packages=find_packages(),
    install_requires=[
        "httpx>=0.27",
        "pydantic>=2.0",
    ],
)