Python Code Quality & Idioms

Refactors Python code into clean, idiomatic ("Pythonic") architecture. Enforces context managers (with), dataclasses, explicit exceptions, and generator pipelines.

1. Purpose

Eliminate non-idiomatic patterns in Python (e.g. C-style index loops, raw dictionary passing, catching bare Exception).

2. When to Use

Use this skill when:

• Replacing raw dictionaries with @dataclass or Pydantic models.
• Ensuring resource management uses with context managers.
• Replacing index-based loops (for i in range(len(arr))) with enumerate() or zip().

3. When Not to Use

• Do not use for running tests; use py-testing.
• Do not use to fix syntax errors; use py-lint-and-typecheck.

4. Required Inputs

• target_file: Path to the Python file to inspect or refactor.

5. Missing-Input Behavior

1. If target_file is missing: ask for target file.
2. Never introduce backwards-incompatible API breaks without user confirmation.

6. Procedure

Follow these numbered actions:

1. Action 1: Audit for Anti-Patterns
   • Check for bare except:, range(len()), and manual file close without with.
2. Action 2: Convert Raw Dicts to Dataclasses
   • Use @dataclass(frozen=True) for immutable value objects.
3. Action 3: Use Context Managers
   • Wrap file I/O, database sessions, and locks in with blocks.
4. Action 4: Define Domain Exceptions
   • Inherit from a custom base exception (class DomainError(Exception): pass).
5. Action 5: Verify Tests
   • Run pytest to confirm 100% behavior preservation.

7. Decision Rules

• If managing files or sockets: always use with open(...) as f:.
• Never use mutable default arguments like def func(items=[]); use items: list | None = None.

8. Output Format

Emit the report using this template:

### Python Code Quality Report: [File]

- **File Modified**: `[path]`
- **Patterns Applied**: [e.g. Dataclass, Context Manager]
- **Test Status**: PASS

#### Refactoring Details
- [Pattern 1 applied with explanation]
- [Pattern 2 applied with explanation]

9. Verification Checklist

• No bare except: statements.
• Mutable default arguments eliminated.
• Context managers used for I/O.
• Existing pytest suite passes.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• Changing dictionary structures breaks external JSON consumers.

12. Examples

Example 1: Successful Execution

Input:

File: src/export.py
Anti-pattern: f = open("data.csv"); f.write(...); f.close()

Output:

### Python Code Quality Report: src/export.py

- **File Modified**: `src/export.py`
- **Patterns Applied**: Context Manager
- **Test Status**: PASS

#### Refactoring Details
- Replaced manual `open()` / `close()` with `with open("data.csv", "w", encoding="utf-8") as f:`.
- Guarantees file handle cleanup even if an exception is raised.

Example 2: Ambiguous or Missing Input

Input:

Clean Python.

Output:

### Python Code Quality Report: Halted - No Target File

- **Status**: Halted

Please specify the Python file to inspect.

Example 3: Expected Final Output

Output:

### Python Code Quality Report: src/models.py

- **File Modified**: `src/models.py`
- **Patterns Applied**: Immutable Dataclass
- **Test Status**: PASS

#### Refactoring Details
- Converted untyped user tuple into `@dataclass(frozen=True) class User`.