python-best-practices

Type-first Python development using dataclasses, discriminated unions, NewType, and Protocol to make illegal states unrepresentable.

0xbigboss/claude-code|Updated Apr 8, 2026

Works with

Claude CodeCursorClineWindsurfCodexGoose

What it does

Define data models and function signatures before implementation; use frozen dataclasses, Literal-based discriminated unions, and NewType for domain primitives to prevent invalid states at type-check time
Leverage Protocol for structural typing, TypedDict for external data shapes, and exhaustive pattern matching with match statements to catch incomplete lo

Repository

0xbigboss/claude-code

Last updated

Apr 8, 2026

Installation Guide

Select your AI agent

How to use python-best-practices on Cursor

AI-first code editor with Composer

Prerequisites

Before installing skills in Cursor, ensure your development environment meets these requirements:

›Cursor installed and configured on your machine
›Node.js 16+ with npm — verify with node --version
›Active project directory where you want to add python-best-practices

Run the install command

Execute the skills CLI command in your project's root directory to begin installation:

$npx skills add https://github.com/0xbigboss/claude-code --skill python-best-practices

Fetches python-best-practices from 0xbigboss/claude-code and configures it for Cursor.

Select Cursor when prompted

The CLI shows a list of agents. Use arrow keys and space to select Cursor:

◆ Which agents do you want to install to?

│

│ ── Universal (.agents/skills) ────────────────

│ · Cline · Codex · Goose · Windsurf

│ ●Cursor(selected)

│ · Cursor · Aider · Continue

Verify installation

Confirm successful installation by checking the skill directory location:

.cursor/skills/python-best-practices

Restart Cursor to activate python-best-practices. Access via /python-best-practices in your agent's command palette.

⚠

Security Notice

We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.

›View source on GitHub ›Skills CLI docs ›About Cursor ›What are agent skills?

Documentation

List & Monetize Your Skill

Submit your Claude Code skill and start earning

Get started →

Use Cases

Task Automation & Efficiency

Automate repetitive workflows and reduce manual effort

Example

Generate reports, summarize documents, draft communications

✓

Save 3-5 hours per week on routine tasks

Knowledge Enhancement

Learn new skills, understand complex topics, get expert guidance

Example

Explain concepts, provide examples, suggest learning resources

✓

Accelerate learning and skill development by 2x

Quality Improvement

Enhance output quality through reviews, suggestions, and refinements

Example

Review drafts, suggest improvements, catch errors

✓

Improve work quality by 30-40% with less effort

Make Illegal States Unrepresentable

Use Python's type system to prevent invalid states at type-check time.

Frozen dataclasses for immutable domain models:

from dataclasses import dataclass from 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:

from dataclasses import dataclass from typing import Literal @dataclass class Success: status: Literal["success"] = "success" data: str @dataclass class 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:

from 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:

from 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()

Structured Logging

Use a module-level logger with %s formatting (deferred string interpolation):

import 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 from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright.

uvx ty check # run directly, no install needed uvx ty check src/ # check specific path

# 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

python-best-practices

What it does

Category

Repository

Last updated

Installation Guide

How to use python-best-practices on Cursor

Prerequisites

Run the install command

Select Cursor when prompted

Verify installation

Security Notice

Documentation

List & Monetize Your Skill

Use Cases

Task Automation & Efficiency

Knowledge Enhancement

Quality Improvement

Install Skill

Python Best Practices

Make Illegal States Unrepresentable

Python-Specific Error Handling

Structured Logging

Optional: ty

Implementation Guide

Best Practices

When to Use This

Learning Path

Related Skills

python-expert-best-practices-code-review

typescript-best-practices

nestjs-best-practices

react-vite-best-practices

svelte5-best-practices

angular-best-practices-primeng

Reviews

Discussion