What is smith-python?

This Claude skill optimizes Python development workflows by enforcing modern industry standards and best practices. It integrates essential tools like uv, ruff, and pytest to ensure high-quality code through strict type hinting, absolute import organization, and robust testing patterns, making it ideal for building scalable and maintainable Python applications.

When should I use smith-python?

smith-python is useful in the following scenarios: • Streamlining Python project initialization and dependency management using high-performance tools like uv or Poetry. • Enforcing consistent code quality and formatting across teams by automating ruff linting and absolute import rules. • Implementing standardized, function-based unit testing suites with pytest to ensure reliable and bug-free code execution. • Managing complex environment configurations and type-safe application settings using Pydantic and structured logging.

name	smith-python
description	Python development with uv, pytest, ruff, and type hints. Use when writing Python code, running tests, managing Python packages, or working with virtual environments. Covers import organization, type hints, pytest patterns, and environment variables.

Python Development Standards

Load if: Python code, pytest, virtual env
Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md

CRITICAL (Primacy Zone)

NEVER use relative imports (from .module import)
NEVER use inline imports within functions
NEVER use unittest-style TestCase classes
NEVER use pytest class-based tests (class TestFoo:)
NEVER execute pytest without virtual env runner (missing .env vars)
NEVER execute directly: .venv/bin/python -m pytest
NEVER mix package managers in same project
NEVER use %-style formatting in log messages (use extra= parameter for structured logging)

ALWAYS use absolute imports (from package.module import)
ALWAYS use type hints for all function signatures
ALWAYS use function-based tests: def test_should_<action>_when_<condition>():
ALWAYS use virtual env runner: poetry run or uv run
ALWAYS use structured logging with extra= parameter for all log data

Import Organization

stdlib: import os, sys
third-party: import pytest
local: from package.module import

Type Hints

from typing import Optional, List

def process_docs(docs: List[str], max_count: Optional[int] = None) -> bool:
    pass

Testing with Pytest

# Function-based tests (required pattern)
def test_should_parse_pdf_when_valid_file_provided():
    result = parse_pdf("valid.pdf")
    assert result.success == True

# OK: Helper classes for test data (not test cases)
class TestDataBuilder:
    @staticmethod
    def create_valid_input() -> dict:
        return {"key": "value"}

Environment Variables

import os
from pydantic_settings import BaseSettings

# Simple access
api_key = os.getenv("API_KEY", "default")

# Pydantic settings (preferred)
class Settings(BaseSettings):
    api_key: str
    timeout: int = 30
    class Config:
        env_file = ".env"

# CRITICAL: Set BEFORE importing library
os.environ["LIBRARY_CONFIG"] = "value"
import library  # Now sees config

Common Patterns

Error handling: Catch specific exceptions, log, re-raise
Logging: logger = logging.getLogger(__name__)
Dataclasses: Use @dataclass(frozen=True) for immutable config

Claude Code LSP (Experimental)

LSP plugins exist but are currently broken (race condition in initialization):

pyright-lsp@claude-plugins-official

When fixed, LSP provides: goToDefinition, findReferences, hover, documentSymbol, getDiagnostics

Workaround: Use Serena MCP for language server features (find_symbol, find_referencing_symbols)

@smith-principles/SKILL.md - Core principles
@smith-standards/SKILL.md - Universal coding standards
@smith-tests/SKILL.md - Testing standards (pytest patterns)
@smith-dev/SKILL.md - Development workflow
@smith-serena/SKILL.md - Serena MCP for language server features

ACTION (Recency Zone)

Before commit (Poetry):

poetry run ruff check --fix
poetry run ruff format
poetry run pytest

Before commit (uv):

uv run ruff check --fix
uv run ruff format
uv run pytest

Package management:

Poetry: poetry install, poetry add <pkg>, poetry remove <pkg>
uv: uv sync, uv add <pkg>, uv remove <pkg>

smith-python

When & Why to Use This Skill

Use Cases