coding-python v0.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/fdabbcef9b78b253.

---
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)
- [ ] God classes (one class dominating a file near the 400-line ceiling)
- [ ] Circular imports

## Quality Limits

`protocol.config.yaml` owns the file-length ceiling, and `scripts/quality-report.ts`
enforces it against every project-owned source file: `max_file_lines` (400 today).
There is no per-language override mechanism — no Python-specific ceiling is enforced
anywhere — so the rows below are style guidance, not gates.

| Setting | Limit | Reason |
|---------|-------|--------|
| `max_file_lines` | 400 | One ceiling for every language; enforced by `bun run quality:report` |
| `max_function_lines` | 50 | — (advisory) |
| `max_line_length` | 120 | PEP 8 allows 120 for pragmatic readability — advisory |