Python Development Rules - uv & ruff

A comprehensive development standard for Python projects emphasizing modern tooling (uv, ruff), type safety, and meaningful documentation.

Core Principles

You are assisting with a Python project that follows strict development standards. All code must adhere to these mandatory rules.

Language & Formatting Standards

**Strict Requirements:**

1. **English Only**: All code, comments, docstrings, commit messages, and documentation must be in English

2. **Indentation**: Always use 2 spaces (not tabs, not 4 spaces)

3. **Naming**: Use full English words for all identifiers - no abbreviations

- ✅ `index`, `count`, `user_name`

- ❌ `idx`, `cnt`, `usrnm`

4. **Strings**: All user-facing strings and log messages must be in English

Mandatory Toolchain

**Package Management:**

- Install: `uv pip install requests`

- Requirements: `uv pip install -r requirements.txt`

- Never use `pip` directly

**Code Quality:**

Modern Python Practices (Required)

Apply these patterns to all code:

1. **Type Hints**: Every function signature must include type annotations

```python

def process_data(items: list[str], limit: int = 10) -> dict[str, int]:

...

```

2. **f-strings**: Use for all string formatting (no % or .format())

```python

message = f"Processing {count} items at {timestamp}"

```

3. **pathlib**: Use for all filesystem operations (no os.path)

```python

from pathlib import Path

config_file = Path("config") / "settings.json"

```

4. **dataclasses**: Use for simple data containers

```python

from dataclasses import dataclass

@dataclass

class User:

name: str

email: str

active: bool = True

```

Commenting Philosophy

**Primary Rule: Explain WHY, Not WHAT**

Comments should clarify intent, rationale, and business logic - not describe what the code obviously does.

**Guidelines:**

✅ **DO Write Comments For:**

❌ **DO NOT Write Comments For:**

❌ **STRICTLY PROHIBITED:**

**Examples:**

```python

❌ WRONG - Describes edit history

Changed timeout from 5s to 10s

TIMEOUT = 10

❌ WRONG - Useless comment for simple code

Defines a function that adds two numbers

def add(a: int, b: int) -> int:

return a + b

✅ CORRECT - Explains the "why" behind this magic number

The upstream gateway has a hard limit of 10 seconds

TIMEOUT = 10

✅ CORRECT - Explains complex logic with example

This regex matches comma-separated values,

ignoring commas inside double quotes.

e.g., "a,b,\"c,d\",e" -> ["a", "b", "\"c,d\"", "e"]

COMPLEX_REGEX = r',(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)'

✅ CORRECT - No comment needed, code is self-explanatory

def add(a: int, b: int) -> int:

return a + b

```

Testing Standards

**Test Organization:**

**Test Implementation:**

**Recommended Test Data Sources:**

**Test Structure Example:**

```python

def test_svg_parser():

# Arrange

svg_content = '<svg>...</svg>'

# Act

result = parse_svg(svg_content)

# Assert

assert result.width == 100

assert len(result.elements) == 3

```

Development Workflow

1. **Plan First**: For complex tasks, propose a step-by-step implementation plan before writing code

2. **Test Coverage**: Write `pytest` tests for all new functionality

3. **Atomic Commits**: Keep commits small and focused on single concerns

4. **Clean Solutions**: If implementation becomes messy, reset and re-implement cleanly

5. **Lint Before Commit**: Always run `ruff` before finalizing changes

Verification Checklist

Before considering any code complete, verify:

Common Violations to Avoid

❌ Using `pip` instead of `uv`

❌ Abbreviations like `idx`, `cnt`, `tmp`

❌ 4-space or tab indentation

❌ Missing type hints

❌ Using `os.path` instead of `pathlib`

❌ Comments describing edit history

❌ Comments for self-explanatory code

Integration Notes