home / skills / julianobarbosa / claude-code-skills / writing-python-skill

writing-python-skill skill

safe

This skill helps you write idiomatic Python 3.14+ by prioritizing stdlib, type hints, and explicit errors across code, tools, and scripts.

npx playbooks add skill julianobarbosa/claude-code-skills --skill writing-python-skill

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.1 KB

---
name: writing-python
description: Idiomatic Python 3.14+ development. Use when writing Python code, CLI tools, scripts, or services. Emphasizes stdlib, type hints, uv/ruff toolchain, and minimal dependencies.
allowed-tools: Read, Bash, Grep, Glob
---

# Python Development (3.14+)

## Core Principles

- **Stdlib first**: External deps only when justified
- **Type hints everywhere**: All functions, all parameters
- **Explicit over implicit**: Clear is better than clever
- **Fail fast**: Raise early with informative errors

## Toolchain

```bash
uv           # Package management (not pip/poetry)
ruff         # Lint + format (not flake8/black)
pytest       # Testing
mypy         # Type checking
```

## Quick Patterns

### Type Hints

```python
def process_users(users: list[User], limit: int | None = None) -> list[Result]:
    ...

async def fetch_data(url: str, timeout: float = 30.0) -> dict[str, Any]:
    ...
```

### Dataclasses

```python
from dataclasses import dataclass, field

@dataclass
class Config:
    host: str
    port: int = 8080
    tags: list[str] = field(default_factory=list)
```

### Pattern Matching

```python
match event:
    case {"type": "click", "x": x, "y": y}:
        handle_click(x, y)
    case {"type": "key", "code": code}:
        handle_key(code)
    case _:
        raise ValueError(f"Unknown event: {event}")
```

## Python 3.14 Features

- **Deferred annotations**: No more `from __future__ import annotations`
- **Template strings (t"")**: `t"Hello {name}"` returns Template object
- **except without parens**: `except ValueError, TypeError:`
- **concurrent.interpreters**: True parallelism via subinterpreters
- **compression.zstd**: Zstandard in stdlib
- **Free-threaded build**: No GIL (opt-in)

## References

- [PATTERNS.md](PATTERNS.md) - Code patterns and style
- [CLI.md](CLI.md) - CLI application patterns
- [TESTING.md](TESTING.md) - Testing with pytest

## Tooling

```bash
uv sync                    # Install deps
ruff check --fix .         # Lint and autofix
ruff format .              # Format
pytest -v                  # Test
mypy .                     # Type check
```

Overview

This skill teaches idiomatic Python 3.14+ development for building scripts, CLI tools, services, and libraries. It emphasizes the standard library first, pervasive type hints, clear explicit code, and a fail-fast approach. The recommended toolchain (uv, ruff, mypy, pytest) focuses on minimal dependencies and fast feedback.

How this skill works

The skill provides practical patterns and conventions: typed function signatures, dataclasses with sensible defaults, structural pattern matching, and new Python 3.14 features like deferred annotations and template strings. It prescribes a workflow: manage packages with uv, enforce style and linting with ruff, run tests with pytest, and validate types with mypy. Examples show concrete code shapes you can reuse immediately.

When to use it

Writing new Python 3.14+ projects (CLIs, services, libraries).
Refactoring code to use stdlib-first dependencies and clearer types.
Implementing well-typed async logic and network I/O.
Creating small utilities or scripts that should stay lightweight and maintainable.
Setting up a consistent local dev toolchain for linting, testing, and type checking.

Best practices

Prefer stdlib modules before adding external dependencies; justify any third-party package.
Annotate every function and parameter with precise type hints; use | for unions and built-in generics.
Favor explicit, readable code; raise clear errors early to fail fast.
Use dataclasses with default_factory for mutable defaults and pattern matching for concise control flow.
Run ruff for formatting and lint fixes, mypy for static types, and pytest for tests as part of your local workflow.

Example use cases

Build a CLI that parses args with argparse, uses dataclasses for config, and dispatches with match/case.
Implement an async HTTP client that returns typed dicts and is covered by pytest async tests.
Create a small background worker using concurrent.interpreters for parallelism where appropriate.
Refactor a legacy module by adding type hints, replacing ad-hoc deps with stdlib alternatives, and enforcing ruff and mypy checks.
Package a compact utility with uv for dependency resolution and a ruff-configured pre-commit step.

FAQ

Why use uv instead of pip or poetry?

uv focuses on lightweight, reproducible dependency management suitable for small projects; use it when you want minimal tooling and deterministic installs.

Do I always need third-party libraries?

No. Prefer stdlib first. Add external packages only when they provide clear, necessary functionality not available in the standard library.