Cline rules

1---
2description: Python coding standards and best practices for mtg-utils
3author: Simone Gasbarroni
4version: 1.0
5tags: ["coding-standards", "python", "style-guide"]
6---
7 
8# Coding Standards
9 
10## Python Style Guidelines
11 
12This document outlines the coding standards for the mtg-utils project. Following these guidelines ensures consistent, maintainable code across the project.
13 
14---
15 
16## Style Requirements
17 
18### Code Style
19 
20- **PEP 8 compliance** is required for all Python code
21- **Line length**: Maximum 120 characters (configured in `ruff`)
22- **Indentation**: 4 spaces per indentation level
23- **String quotes**: Use double quotes `"` for consistency
24 
25### Naming Conventions
26 
27| Type | Convention | Example |
28|------|-----------|---------|
29| Functions/Methods | snake_case | `check_missing_cards` |
30| Classes | PascalCase | `CardLibrary` |
31| Variables | snake_case | `deck_list` |
32| Constants | UPPER_SNAKE_CASE | `MAX_DECK_SIZE` |
33| Modules | snake_case | `moxfield_api.py` |
34 
35### Imports
36 
37Imports should be organized in the following order:
38 
391. Standard library imports
402. Third-party imports (e.g., click, rich, requests)
413. Local project imports
42 
43```python
44# Standard library
45import os
46import json
47 
48# Third-party
49import click
50from rich.console import Console
51 
52# Local project
53from mtg_utils.utils.console import console
54```
55 
56---
57 
58## Type Hints
59 
60Type hints are **required** for all function signatures:
61 
62```python
63# ✅ GOOD
64def check_missing_cards(deck_file: str, binder_cards: list[str]) -> list[str]:
65    pass
66 
67# ❌ BAD
68def check_missing_cards(deck_file, binder_cards):
69    pass
70```
71 
72### Type Hint Rules
73 
74- Always specify parameter types
75- Always specify return type (use `-> None` for functions that don't return)
76- Use `list[str]`, `dict[str, Any]`, etc. for generic types
77- Use `Optional[T]` for nullable types
78 
79---
80 
81## Docstrings
82 
83All public functions, classes, and modules should have docstrings:
84 
85```python
86def check_missing_cards(deck_file: str, binder_cards: list[str]) -> list[str]:
87    """
88    Check which cards are missing from the binder collection.
89 
90    Args:
91        deck_file: Path to the decklist file
92        binder_cards: List of cards in the binder collection
93 
94    Returns:
95        List of card names that are missing
96    """
97    pass
98```
99 
100---
101 
102## Error Handling
103 
104- Use specific exception types when possible
105- Provide meaningful error messages
106- Handle file I/O errors gracefully
107 
108```python
109# ✅ GOOD
110def read_deck_list(path: str) -> list[str]:
111    try:
112        with open(path, 'r') as f:
113            return [line.strip() for line in f if line.strip()]
114    except FileNotFoundError:
115        console.print(f"[bold red]Error:[/bold red] Deck file not found: {path}")
116        raise
117 
118# ❌ BAD
119def read_deck_list(path: str) -> list[str]:
120    with open(path, 'r') as f:
121        return f.readlines()
122```
123 
124---
125 
126## Console Output
127 
128Use the `rich` library for formatted console output:
129 
130```python
131from rich.console import Console
132from rich.table import Table
133from mtg_utils.utils.console import console
134 
135# Use console.print() instead of print()
136console.print("[bold green]Success![/bold green]")
137 
138# Use rich formatting for tables and panels
139table = Table(title="Deck Comparison")
140table.add_column("Card", style="cyan")
141table.add_column("Count", style="magenta")
142```
143 
144---
145 
146## Configuration
147 
148Configuration is loaded from `config.json` using Pydantic models:
149 
150```python
151from mtg_utils.utils.config import Config, DeckConfig
152 
153# Load configuration
154config = Config.from_file("config.json")
155 
156# Access configuration
157for name, deck in config.decks.items():
158    console.print(f"Deck: {name}")
159```
160 
161---
162 
163## File I/O
164 
165- Use `with open()` for all file operations
166- Prefer text mode for card files
167- Handle encoding explicitly (UTF-8)
168 
169```python
170# ✅ GOOD
171def write_card_list(path: str, cards: list[str]) -> None:
172    with open(path, 'w', encoding='utf-8') as f:
173        f.write('\n'.join(sorted(cards)))
174 
175# ❌ BAD
176open('file.txt', 'w').write(cards)
177 
178```