Shadows Python Sensei

Python best practices enforcer — clean code, proper patterns, performance, testing, type hints. Use when writing or reviewing Python code.

Security Scan

Instruction-only Python code-review helper that asks only for python on PATH and gives best-practice guidance — its requirements and instructions are consistent with its stated purpose.

Purpose & Capability

Name/description (Python best-practices enforcer) match the skill content. Declared requirement of python/python3 is appropriate for syntax checks and test execution; no unrelated binaries, credentials, or config paths are requested.

Instruction Scope

SKILL.md contains runtime guidance for linting, type-checking, testing, and coding standards. It references running python -m py_compile and pytest and optionally using tools like mypy/ruff/pyright, which is coherent for a code-review tool. The instructions do not direct the agent to read unrelated files, harvest credentials, or transmit data to unexpected external endpoints. They do state the skill will detect available tools on PATH — that is reasonable and scoped to the task.

Install Mechanism

There is no install spec and no code files; the skill is instruction-only. The SKILL.md may recommend installing optional tools via pip, but the skill does not include an automatic download or extract step. No suspicious external URLs or archives are used by the skill itself.

Credentials

Requires only presence of python/python3 on PATH. No environment variables, credentials, or config paths are requested. Optional tool recommendations (pytest, mypy, ruff) are standard for the stated purpose.

Persistence & Privilege

always is false and the skill does not request elevated or persistent privileges. disable-model-invocation is false (normal default) — nothing else in the package amplifies that capability.

Assessment

This is an instruction-only skill that looks coherent for Python code review. Before using it, be aware it may suggest running commands (e.g., python -m py_compile, pytest) or installing optional tools via pip — grant permission before running installs. The skill references an external homepage in metadata; if you plan to follow links or fetch recommended third-party tools, verify those sources yourself. Otherwise the skill does not request credentials or system access beyond having Python on PATH.

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

"""Module docstring — one line describing purpose."""

# Standard library imports
import os
from pathlib import Path

# Third-party imports
import httpx
from pydantic import BaseModel

# Local imports
from .config import Settings

# Constants
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30

# Module code...

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

async def fetch_user(user_id: str, *, include_profile: bool = False) -> User | None:
    """Fetch a user by ID.

    Args:
        user_id: The unique user identifier.
        include_profile: Whether to include full profile data.

    Returns:
        User object if found, None otherwise.

    Raises:
        ConnectionError: If the API is unreachable.
    """

Rules:

• Type hints on all public functions (params + return)
• Keyword-only args after * for clarity
• None 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

from dataclasses import dataclass, field
from enum import StrEnum

class Status(StrEnum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    PENDING = "pending"

@dataclass
class User:
    id: str
    name: str
    status: Status = Status.ACTIVE
    tags: list[str] = field(default_factory=list)

    def to_dict(self) -> dict:
        return {
            "id": self.id,
            "name": self.name,
            "status": self.status.value,
            "tags": self.tags,
        }

Rules:

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

4. Error Handling

# GOOD: Specific exceptions, minimal try blocks
try:
    response = await client.get(url)
    response.raise_for_status()
except httpx.TimeoutException:
    logger.warning("Request timed out: %s", url)
    return None
except httpx.HTTPStatusError as e:
    logger.error("HTTP %d: %s", e.response.status_code, url)
    raise

# BAD: Catching everything
try:
    do_everything()
except Exception:
    pass  # Never do this

Rules:

• Catch specific exceptions, never bare except:
• 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

import asyncio
import httpx

async def fetch_all(urls: list[str]) -> list[dict]:
    async with httpx.AsyncClient() as client:
        tasks = [client.get(url) for url in urls]
        responses = await asyncio.gather(*tasks, return_exceptions=True)
        return [r.json() for r in responses if not isinstance(r, Exception)]

Rules:

• async with for resource management
• asyncio.gather() for parallel I/O
• return_exceptions=True to handle partial failures
• Never mix sync and async I/O in the same function

6. Testing

import pytest

class TestUserService:
    def test_create_user_with_valid_data(self):
        user = create_user(name="Alice", email="[e-mail]")
        assert user.name == "Alice"
        assert user.status == Status.ACTIVE

    def test_create_user_rejects_empty_name(self):
        with pytest.raises(ValueError, match="name cannot be empty"):
            create_user(name="", email="[e-mail]")

    @pytest.mark.asyncio
    async def test_fetch_user_returns_none_for_missing(self):
        result = await fetch_user("nonexistent-id")
        assert result is None

Rules:

• Test file: tests/test_{module}.py
• Test names describe the scenario: test_[action]_[condition]_[expected]
• One assertion per test (prefer)
• Use pytest.raises for expected exceptions
• Use fixtures for shared setup

7. Project Setup

project/
  src/
    project_name/
      __init__.py
      main.py
      config.py
      models.py
  tests/
    test_main.py
    test_models.py
  pyproject.toml
  requirements.txt
  .gitignore

pyproject.toml over setup.py. Pin major versions in requirements.txt.

---

ANTI-PATTERNS TO FLAG

Anti-Pattern	Fix
import *	Explicit imports
Mutable default args	field(default_factory=list)
Global mutable state	Dependency injection
Nested try/except	Extract and flatten
String concatenation for SQL	Parameterized queries
type() checks	isinstance()
os.path	pathlib.Path
requests (sync)	httpx (async-ready)

---

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. 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

---

Published by Shadows Company — "We work in the shadows to serve the Light."