AGENTS.md

1# Python Expert Guidelines
2 
3**A comprehensive guide for AI agents writing and reviewing Python code**, organized by priority and impact.
4 
5---
6 
7## Table of Contents
8 
9### Correctness — **CRITICAL**
101. [Avoid Mutable Default Arguments](#avoid-mutable-default-arguments)
112. [Proper Error Handling](#proper-error-handling)
12 
13### Type Safety — **HIGH**
143. [Use Type Hints](#use-type-hints)
154. [Use Dataclasses](#use-dataclasses)
16 
17### Performance — **HIGH**
185. [Use List Comprehensions](#use-list-comprehensions)
196. [Use Context Managers](#use-context-managers)
20 
21### Style — **MEDIUM**
227. [Follow PEP 8 Style Guide](#follow-pep-8-style-guide)
238. [Write Docstrings](#write-docstrings)
24 
25---
26 
27## Correctness
28 
29### Avoid Mutable Default Arguments
30 
31**Impact: CRITICAL** | **Category: correctness** | **Tags:** bugs, defaults, mutable, gotcha
32 
33Mutable default arguments (like lists or dicts) are shared across all calls to the function.
34 
35#### Why This Matters
36 
37Because the default value is evaluated only once at function definition time, subsequent calls will persist changes made to the default object, leading to extremely subtle and frustrating bugs.
38 
39#### ❌ Incorrect
40 
41```python
42def add_item(item, items=[]):  # BUG: [] is shared!
43    items.append(item)
44    return items
45 
46print(add_item("a"))  # ['a']
47print(add_item("b"))  # ['a', 'b'] - Unexpected!
48```
49 
50#### ✅ Correct
51 
52```python
53def add_item(item: str, items: list[str] | None = None) -> list[str]:
54    """Add an item to a list, creating a new list if none provided.
55    
56    Args:
57        item: The item to add
58        items: Optional existing list to add to
59        
60    Returns:
61        The list with the new item added
62    """
63    if items is None:
64        items = []
65    items.append(item)
66    return items
67```
68 
69[➡️ Full details: correctness-mutable-defaults.md](rules/correctness-mutable-defaults.md)
70 
71---
72 
73### Proper Error Handling
74 
75**Impact: CRITICAL** | **Category: correctness** | **Tags:** errors, exceptions, reliability
76 
77Always handle errors explicitly. Don't use bare except clauses or ignore errors silently.
78 
79#### ❌ Incorrect
80 
81```python
82try:
83    result = risky_operation()
84except:
85    pass  # Silent failure!
86```
87 
88#### ✅ Correct
89 
90```python
91try:
92    config = json.loads(config_file.read())
93except json.JSONDecodeError as e:
94    logger.error(f"Invalid JSON in config file: {e}")
95    config = get_default_config()
96except FileNotFoundError:
97    logger.warning("Config file not found, using defaults")
98    config = get_default_config()
99```
100 
101[➡️ Full details: correctness-error-handling.md](rules/correctness-error-handling.md)
102 
103---
104 
105## Type Safety
106 
107### Use Type Hints
108 
109**Impact: HIGH** | **Category: type-safety** | **Tags:** types, mypy, annotations, documentation
110 
111Type hints enable static analysis, improve IDE support, and serve as documentation.
112 
113#### Why This Matters
114 
115Python's dynamic nature can lead to runtime errors that are hard to catch. Type hints allow tools like `mypy` to verify code correctness before execution.
116 
117#### ❌ Incorrect
118 
119```python
120def get_user(id):
121    return users.get(id)
122```
123 
124#### ✅ Correct
125 
126```python
127from typing import Optional, Dict, Any
128 
129def get_user(user_id: int) -> Optional[Dict[str, Any]]:
130    """Fetch user by ID.
131    
132    Args:
133        user_id: The unique identifier for the user
134        
135    Returns:
136        User dictionary if found, None otherwise
137    """
138    return users.get(user_id)
139```
140 
141[➡️ Full details: type-hints.md](rules/type-hints.md)
142 
143---
144 
145### Use Dataclasses
146 
147**Impact: HIGH** | **Category: type-safety** | **Tags:** dataclasses, classes, data, boilerplate
148 
149Use the `@dataclass` decorator for classes that primarily store data.
150 
151#### Why This Matters
152 
153Dataclasses automatically generate `__init__`, `__repr__`, and `__eq__` methods, reducing boilerplate and ensuring consistent behavior for data containers.
154 
155#### ❌ Incorrect
156 
157```python
158class User:
159    def __init__(self, id, name, email):
160        self.id = id
161        self.name = name
162        self.email = email
163    
164    def __repr__(self):
165        return f"User(id={self.id}, name={self.name}, email={self.email})"
166    
167    def __eq__(self, other):
168        return self.id == other.id and self.name == other.name
169```
170 
171#### ✅ Correct
172 
173```python
174from dataclasses import dataclass
175 
176@dataclass
177class User:
178    id: int
179    name: str
180    email: str
181 
182# With additional configuration
183@dataclass(frozen=True)  # Immutable
184class Config:
185    api_key: str
186    timeout: int = 30
187```
188 
189[➡️ Full details: type-dataclasses.md](rules/type-dataclasses.md)
190 
191---
192 
193## Performance
194 
195### Use List Comprehensions
196 
197**Impact: HIGH** | **Category: performance** | **Tags:** comprehensions, pythonic, efficiency
198 
199Use list comprehensions for simple transformations and filtering.
200 
201#### Why This Matters
202 
203List comprehensions are more concise, readable to experienced Pythonistas, and generally faster than equivalent `for` loops because they are optimized in the CPython interpreter.
204 
205#### ❌ Incorrect
206 
207```python
208squares = []
209for x in range(10):
210    squares.append(x ** 2)
211 
212# Filtering with loop
213evens = []
214for x in range(20):
215    if x % 2 == 0:
216        evens.append(x)
217```
218 
219#### ✅ Correct
220 
221```python
222# Simple transformation
223squares = [x ** 2 for x in range(10)]
224 
225# With filtering
226evens = [x for x in range(20) if x % 2 == 0]
227 
228# Nested (use sparingly - break into functions if complex)
229matrix = [[i * j for j in range(3)] for i in range(3)]
230```
231 
232[➡️ Full details: performance-comprehensions.md](rules/performance-comprehensions.md)
233 
234---
235 
236### Use Context Managers
237 
238**Impact: HIGH** | **Category: performance** | **Tags:** context-managers, with, resources, cleanup
239 
240Always use context managers (`with` statements) for resource cleanup.
241 
242#### Why This Matters
243 
244Manual cleanup is error-prone. If an exception occurs before `close()` is called, the resource (file handle, database connection, lock) may remain open, leading to leaks and system instability.
245 
246#### ❌ Incorrect
247 
248```python
249f = open('file.txt')
250data = f.read()
251f.close()  # May never be called if exception occurs!
252```
253 
254#### ✅ Correct
255 
256```python
257with open('file.txt') as f:
258    data = f.read()
259# File is automatically closed, even if exception occurs
260 
261# Multiple resources
262with open('input.txt') as infile, open('output.txt', 'w') as outfile:
263    outfile.write(infile.read().upper())
264```
265 
266[➡️ Full details: performance-context-managers.md](rules/performance-context-managers.md)
267 
268---
269 
270## Style
271 
272### Follow PEP 8 Style Guide
273 
274**Impact: MEDIUM** | **Category: style** | **Tags:** pep8, python, style, conventions
275 
276Python's official style guide ensures readable, consistent code.
277 
278#### Why This Matters
279 
280Readability is a core Python philosophy. Consistent naming and formatting make the codebase maintainable and reduce friction for teams.
281 
282#### ❌ Incorrect
283 
284```python
285def CalculateTotal(itemPrice,qty):
286  return itemPrice*qty
287 
288class user_account:
289  pass
290 
291x=1+2
292```
293 
294#### ✅ Correct
295 
296```python
297def calculate_total(item_price: float, quantity: int) -> float:
298    """Calculate the total price for items."""
299    return item_price * quantity
300 
301 
302class UserAccount:
303    """Represents a user account in the system."""
304    pass
305 
306 
307x = 1 + 2
308```
309 
310[➡️ Full details: style-pep8.md](rules/style-pep8.md)
311 
312---
313 
314### Write Docstrings
315 
316**Impact: MEDIUM** | **Category: style** | **Tags:** documentation, docstrings, google-style
317 
318Write comprehensive docstrings for all public functions, classes, and modules.
319 
320#### Why This Matters
321 
322Good documentation makes code self-explanatory and enables IDEs to provide better autocomplete and hover information. It also serves as the primary reference for API users.
323 
324#### ❌ Incorrect
325 
326```python
327def process(data, config):
328    # processes the data
329    return result
330```
331 
332#### ✅ Correct
333 
334```python
335def process_user_data(
336    data: Dict[str, Any], 
337    config: ProcessConfig
338) -> ProcessResult:
339    """Process user data according to the provided configuration.
340    
341    Takes raw user data and applies transformations, validation,
342    and enrichment based on the configuration settings.
343    
344    Args:
345        data: Raw user data as a dictionary containing at minimum
346            'user_id' and 'email' keys.
347        config: Processing configuration specifying transformations
348            to apply and validation rules.
349            
350    Returns:
351        ProcessResult containing the transformed data and any
352        validation warnings encountered.
353        
354    Raises:
355        ValidationError: If required fields are missing from data.
356        ConfigError: If config contains invalid transformation rules.
357        
358    Example:
359        >>> config = ProcessConfig(normalize_email=True)
360        >>> result = process_user_data({'user_id': 1, 'email': 'TEST@Example.com'}, config)
361        >>> result.data['email']
362        'test@example.com'
363    """
364    ...
365```
366 
367[➡️ Full details: style-docstrings.md](rules/style-docstrings.md)
368 
369---
370 
371## Quick Reference
372 
373### Python Code Checklist
374 
375**Correctness (CRITICAL - address first)**
376- [ ] No mutable default arguments
377- [ ] Specific exception handling (no bare `except:`)
378- [ ] Edge cases handled
379- [ ] Input validation present
380 
381**Type Safety (HIGH)**
382- [ ] Type hints on all functions
383- [ ] Return types specified
384- [ ] Using dataclasses for data containers
385- [ ] Generic types where appropriate
386 
387**Performance (HIGH)**
388- [ ] List comprehensions over loops where readable
389- [ ] Context managers for all resources
390- [ ] Generators for large data
391- [ ] Built-in functions leveraged
392 
393**Style (MEDIUM)**
394- [ ] PEP 8 compliant
395- [ ] Docstrings on public functions
396- [ ] Meaningful variable names
397- [ ] 88-100 character line limit
398 
399---
400 
401## Severity Levels
402 
403| Level | Description | Examples | Action |
404|-------|-------------|----------|--------|
405| **CRITICAL** | Bugs, data corruption, security issues | Mutable defaults, bare except | Fix immediately |
406| **HIGH** | Correctness risks, maintainability issues | Missing types, resource leaks | Fix before merge |
407| **MEDIUM** | Code quality, readability | Style violations, missing docs | Fix or accept with TODO |
408| **LOW** | Minor improvements, preferences | Minor formatting | Optional |
409 
410---
411 
412## Code Review Output Format
413 
414When reviewing Python code, structure your output as:
415 
416```markdown
417## Summary
418[Brief overview of the code and main issues found]
419 
420## Critical Issues 🔴
421 
422### 1. [Issue Title]
423**File:** `path/to/file.py:line`
424**Issue:** [Description of the problem]
425**Impact:** [Why this matters]
426**Fix:**
427```python
428# Corrected code
429```
430 
431## High Priority 🟠
432 
433### 1. [Issue Title]
434[Continue pattern...]
435 
436## Medium Priority 🟡
437 
438[Continue pattern...]
439 
440## Recommendations
441- [General improvement suggestion]
442- [Best practice to adopt]
443 
444## Summary
445- 🔴 CRITICAL: X
446- 🟠 HIGH: X
447- 🟡 MEDIUM: X
448 
449**Recommendation:** [Overall assessment and next steps]
450```
451 
452---
453 
454## References
455 
456- Individual rule files in `rules/` directory
457- [PEP 8 - Style Guide for Python Code](https://peps.python.org/pep-0008/)
458- [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)
459- [PEP 484 - Type Hints](https://peps.python.org/pep-0484/)
460- [Python typing module documentation](https://docs.python.org/3/library/typing.html)
461 
462```