Python Sensei — Best Practices Enforcer

Version: 1.1.0 | Author: Shadows Company | License: MIT

WHEN TO TRIGGER

• - Writing new Python code
• Reviewing existing Python code
• User says "python review", "best practices", "clean up this python"
• Refactoring Python modules
• Setting up a new Python project

WHEN NOT TO TRIGGER

• - Quick scripts where quality doesn't matter
• User explicitly says "just make it work"
• Non-Python code

PREREQUISITES

Requires python or python3 on PATH for syntax checking (python -m py_compile) and test execution (python -m pytest).

Optional tools (auto-detected, recommendations adapt accordingly):

• - pytest — test execution (pip install pytest)
• mypy or pyright — static type checking
• ruff — fast linting and formatting (pip install ruff)

The skill checks which tools are available and tailors its recommendations to the user's installed toolchain.

CODE STANDARDS

1. Module Structure

CODEBLOCK0

Rules:

• - Max 500 lines per module — split if larger
• Imports grouped: stdlib → third-party → local (blank line between each group)
• Constants at top, ALL_CAPS naming
• One class per file for complex classes

2. Functions

CODEBLOCK1

Rules:

• - Type hints on all public functions (params + return)
• Keyword-only args after * for clarity
• INLINECODE7 return type when failure is normal (not exceptions)
• Docstrings on public functions only
• Max 30 lines per function — extract helpers if larger

3. Data Models

CODEBLOCK2

Rules:

• - @dataclass for simple models, Pydantic for validation-heavy models
• INLINECODE9 for states (JSON-serializable)
• Always include to_dict() for serialization
• Immutable by default (frozen=True when appropriate)

4. Error Handling

CODEBLOCK3

Rules:

• - Catch specific exceptions, never bare INLINECODE12
• Only validate at system boundaries (user input, external APIs)
• Trust internal code — do not add defensive checks everywhere
• Use logging module, not print() for errors

5. Async Patterns

CODEBLOCK4

Rules:

• - async with for resource management
• INLINECODE16 for parallel I/O
• INLINECODE17 to handle partial failures
• Never mix sync and async I/O in the same function

6. Testing

CODEBLOCK5

Rules:

• - Test file: INLINECODE18
• Test names describe the scenario: INLINECODE19
• One assertion per test (prefer)
• Use pytest.raises for expected exceptions
• Use fixtures for shared setup

7. Project Setup

CODEBLOCK6

INLINECODE21 over setup.py. Pin major versions in requirements.txt.

ANTI-PATTERNS TO FLAG

SECURITY CONSIDERATIONS

This skill reads and writes Python source files within the working directory. It does not access files outside the project scope.

• - Commands executed: python -m py_compile <file> for syntax checking, python -m pytest <test_file> for test execution. These run local project code — only use on trusted repositories or in sandboxed environments.
• Data read: Source files in the working directory only. No access to secrets, credentials, or system files.
• Network access: None required. The skill operates entirely offline.
• Credentials: None stored or accessed.
• Persistence: All modifications are to source files in the working directory only. No global config changes.
• Sandboxing: Recommended to run in a virtual environment (venv) to isolate dependencies.

OUTPUT FORMAT

Reviews and code output follow the standards defined above. Each review identifies specific anti-patterns with line references and provides corrected code blocks.

RULES

1. 1. Type hints everywhere — public functions must have full type annotations
2. 500 lines max — split large modules into focused sub-modules
3. Test every module — tests/test_{module}.py with descriptive test names
4. Async by default — use async for any I/O operation
5. pathlib over os.path — modern Python path handling
6. No print debugging — use logging module with appropriate levels