PaperclipOrg
Claude Agent Skill · by 0xbigboss

Python Best Practices

The python-best-practices skill guides developers in writing type-safe, maintainable Python code by applying immutable data structures, discriminated unions, an

Install
Terminal · npx
$npx skills add https://github.com/0xbigboss/claude-code --skill python-best-practices
Works with Paperclip

How Python Best Practices fits into a Paperclip company.

Python Best Practices drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md121 lines
Expand
---name: python-best-practicesdescription: Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).--- # Python Best Practices Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only. ## Make Illegal States Unrepresentable Use Python's type system to prevent invalid states at type-check time. **Frozen dataclasses for immutable domain models:**```pythonfrom dataclasses import dataclassfrom datetime import datetime @dataclass(frozen=True)class User:    id: str    email: str    name: str    created_at: datetime # Frozen dataclasses are immutable — no accidental mutation``` **Discriminated unions with Literal:**```pythonfrom dataclasses import dataclassfrom typing import Literal @dataclassclass Success:    status: Literal["success"] = "success"    data: str @dataclassclass Failure:    status: Literal["error"] = "error"    error: Exception RequestState = Success | Failure def handle_state(state: RequestState) -> None:    match state:        case Success(data=data):            render(data)        case Failure(error=err):            show_error(err)``` **NewType for domain primitives:**```pythonfrom typing import NewType UserId = NewType("UserId", str)OrderId = NewType("OrderId", str) def get_user(user_id: UserId) -> User:    # Type checker prevents passing OrderId here    ...``` **Protocol for structural typing:**```pythonfrom typing import Protocol class Readable(Protocol):    def read(self, n: int = -1) -> bytes: ... def process_input(source: Readable) -> bytes:    # Accepts any object with a read() method — no inheritance required    return source.read()``` ## Python-Specific Error Handling Chain exceptions with `from err` to preserve the original traceback:```pythontry:    data = json.loads(raw)except json.JSONDecodeError as err:    raise ValueError(f"invalid JSON payload: {err}") from err``` ## Structured Logging Use a module-level logger with `%s` formatting (deferred string interpolation):```pythonimport logging logger = logging.getLogger("myapp.widgets") def create_widget(name: str) -> Widget:    logger.debug("creating widget: %s", name)    widget = Widget(name=name)    logger.debug("created widget id=%s", widget.id)    return widget``` ## Optional: ty For fast type checking, consider [ty](https://docs.astral.sh/ty/) from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright. ```bashuvx ty check          # run directly, no install neededuvx ty check src/     # check specific path``` ```toml# pyproject.toml[tool.ty]python-version = "3.12"``` When to choose:- `ty` — fastest, good for CI and large codebases (early stage, rapidly evolving)- `pyright` — most complete type inference, VS Code integration- `mypy` — mature, extensive plugin ecosystem