Python Project Development Guide

Enforce strict development standards for Python projects with modern tooling, comprehensive type safety, and clean code practices.

Core Development Rules

1. Language & Formatting Standards

**All content must be in English:**

Code identifiers (variables, functions, classes)

Comments and documentation

User-facing strings

Log messages

Commit messages

**Indentation:**

Always use 2 spaces (not tabs)

Configure editor to insert spaces when Tab is pressed

**Naming Conventions:**

Use full English words for all identifiers

No abbreviations (e.g., `index` not `idx`, `count` not `cnt`)

Follow PEP 8 naming conventions:

- `snake_case` for functions and variables

- `PascalCase` for classes

- `UPPER_SNAKE_CASE` for constants

2. Required Toolchain

**Package Management:**

Use `uv` exclusively (modern Python package manager)

Install packages: `uv pip install package-name`

Manage dependencies through uv's tooling

Never use pip directly

**Code Quality:**

All code MUST comply with `ruff` standards

Format all code before completing any task

Run `ruff check` before committing

Configure ruff in `pyproject.toml` or `ruff.toml`

3. Modern Python Best Practices

**Type Hints (Mandatory):**

```python

Correct: All parameters and return types annotated

def process_data(input_file: pathlib.Path, max_items: int) -> list[str]:

return []

Wrong: Missing type hints

def process_data(input_file, max_items):

return []

```

**String Formatting:**

Use f-strings exclusively for all string formatting

No `%` formatting or `.format()` method

```python

Correct

name = "Alice"

age = 30

message = f"Hello {name}, you are {age} years old"

Wrong

message = "Hello %s, you are %d years old" % (name, age)

message = "Hello {}, you are {} years old".format(name, age)

```

**Filesystem Operations:**

Use `pathlib` for all path operations

Never use `os.path` module

```python

Correct

from pathlib import Path

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

if config_path.exists():

content = config_path.read_text()

Wrong

import os

config_path = os.path.join("config", "settings.json")

if os.path.exists(config_path):

with open(config_path) as f:

content = f.read()

```

**Data Classes:**

Use `dataclasses` for simple data-holding classes

```python

from dataclasses import dataclass

@dataclass

class User:

username: str

email: str

age: int

```

4. Commenting Philosophy

Comments should explain **WHY** the code exists, not **WHAT** it does. For complex logic, explain the "what" with examples.

**Core Principles:**

Explain rationale behind non-obvious decisions

Clarify complex algorithms that aren't self-explanatory

Provide examples for edge cases

Use plain English (no markdown formatting in comments)

**Strictly Prohibited:**

DO NOT describe modification process or edit history

DO NOT comment simple, self-explanatory code

DO NOT use numbered lists or complex formatting

**Examples:**

```python

❌ WRONG: Describes edit history

Changed timeout from 5s to 10s

TIMEOUT = 10

❌ WRONG: Useless comment for obvious code

Defines a function that adds two numbers

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

return a + b

✅ CORRECT: Explains the business reason

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: Self-explanatory code needs no comment

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

return a + b

```

5. Development Workflow

**Planning:**

For complex tasks, propose a step-by-step plan BEFORE coding

Break down large features into atomic tasks

Discuss approach if multiple solutions exist

**Testing:**

Write `pytest` tests for all new functionality

Aim for high code coverage

Test edge cases and error conditions

**Commits:**

Keep commits small and focused on one change

If implementation becomes messy, reset and re-implement cleanly

Write clear commit messages in English

6. Testing Standards

**Test Organization:**

Place all tests in `tests/` directory

Name test files `test_*.py`

Name test functions `test_<description>()`

Group related tests in `TestClassName` classes

**Test Implementation:**

```python

tests/test_parser.py

from pathlib import Path

def test_svg_parser_basic():

"""Test basic SVG parsing functionality."""

svg_content = '<svg><circle r="10"/></svg>'

result = parse_svg(svg_content)

assert result.shapes[0].radius == 10

class TestAdvancedFeatures:

def test_nested_groups(self):

"""Test parsing of nested SVG groups."""

# Test implementation

pass

```

**Running Tests:**

Run all tests: `uv run pytest`

Run specific file: `uv run pytest tests/test_specific.py`

Run with coverage: `uv run pytest --cov`

**Test Data Sources:**

Use standard, well-documented SVG examples:

W3C SVG Test Suite: https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/

W3Schools SVG Examples: https://www.w3schools.com/graphics/svg_examples.asp

MDN SVG Basic Shapes: https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Basic_Shapes

**Assertions:**

Use Python's built-in `assert` statement

No custom assertion libraries

Write clear assertion messages for complex checks

Implementation Checklist

When working on this project:

1. ✅ Verify all code uses English for identifiers, comments, and strings

2. ✅ Confirm 2-space indentation throughout

3. ✅ Add type hints to all function signatures

4. ✅ Use f-strings for all string formatting

5. ✅ Use `pathlib` for all filesystem operations

6. ✅ Format code with `ruff` before committing

7. ✅ Write tests in `tests/` directory using pytest conventions

8. ✅ Run `uv run pytest` to verify tests pass

9. ✅ Write comments that explain "why", not "what"

10. ✅ Keep commits atomic and focused

Common Pitfalls to Avoid

Using `pip` instead of `uv` for package management

Missing type hints on function signatures

Using `os.path` instead of `pathlib`

Writing comments that describe edit history

Creating large, unfocused commits

Skipping tests for new functionality

Using abbreviations in variable names

Python Project Development Guide

Python Project Development Guide

Core Development Rules

1. Language & Formatting Standards

2. Required Toolchain

3. Modern Python Best Practices

Correct: All parameters and return types annotated

Wrong: Missing type hints

Correct

Wrong

Correct

Wrong

4. Commenting Philosophy

❌ WRONG: Describes edit history

Changed timeout from 5s to 10s

❌ WRONG: Useless comment for obvious code

Defines a function that adds two numbers

✅ CORRECT: Explains the business reason

The upstream gateway has a hard limit of 10 seconds

✅ 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"]

✅ CORRECT: Self-explanatory code needs no comment

5. Development Workflow

6. Testing Standards

tests/test_parser.py

Implementation Checklist

Common Pitfalls to Avoid

Reviews (0)