v0.1.0 to v0.1.0

---

name: coding-python

version: 0.1.0

description: Python naming conventions, type hints, import patterns, and quality overrides for ECHO Protocol.

---

# Python Coding Standards

<!-- Load this when protocol.config.yaml has language: "python" -->

## Naming Conventions

| Element | Convention | Example |

|---------|-----------|---------|

| Classes | PascalCase | `UserProfile`, `GameState` |

| Functions | snake_case | `calculate_distance`, `spawn_unit` |

| Variables | snake_case | `player_count`, `is_valid` |

| Constants | UPPER_SNAKE_CASE | `MAX_PLAYERS`, `TILE_SIZE` |

| Modules | snake_case | `player_manager.py` |

| Packages | snake_case (no hyphens) | `game_engine/` |

| Private | leading underscore | `_internal_method` |

| Dunder | double underscore | `__init__`, `__repr__` |

| Type aliases | PascalCase | `PlayerId = str` |

| Enums | PascalCase (class) | `class TileType(Enum)` |

## Patterns

### Type Hints

- Use type hints on all public functions

- Use `from __future__ import annotations` for forward refs

- Prefer `list[int]` over `List[int]` (3.9+)

- Use `Optional[X]` or `X | None` for nullable

- Use Protocol for structural typing

### Error Handling

- Define custom exception hierarchy

- Use specific exceptions, never bare `except:`

- Use context managers for resource cleanup

- Log exceptions with traceback at catch points

### Imports

- Group: stdlib → third-party → local

- One blank line between groups

- Prefer absolute imports

- Use `__all__` to control public API

## File Structure

```text

src/

├── __init__.py

├── __main__.py # Entry point

├── config.py # Configuration

├── exceptions.py # Custom exceptions

├── types.py # Type aliases and protocols

├── [module]/

│ ├── __init__.py

│ ├── models.py # Data classes / Pydantic models

│ ├── service.py # Business logic

│ └── tests/

│ ├── __init__.py

│ └── test_[module].py

```

## Anti-Patterns to Flag

- [ ] Bare `except:` without specific exception

- [ ] Mutable default arguments (`def f(x=[])`)

- [ ] `type: ignore` without justification

- [ ] Wildcard imports (`from x import *`)

- [ ] Global mutable state

- [ ] `print()` in production code (use `logging`)

- [ ] Magic numbers (extract to constants)

- [ ] Circular imports