python

Python Skills

A comprehensive collection of guidance for Python software development, covering project configuration, dependency management, CLI tooling, and best practices across the modern Python ecosystem.

Overview

Python is one of the most widely-used programming languages, powering web backends, data science, machine learning, DevOps automation, CLI tools, and scripting. The Python ecosystem has undergone significant modernization in recent years with pyproject.toml replacing setup.py, type hints becoming standard, and new high-performance tooling like uv transforming the developer experience.

This skill tree provides structured guidance for navigating the Python ecosystem effectively.

Knowledge Map

python/
  project-system/       pyproject.toml, build backends, setuptools, hatch, flit, maturin
  package-management/   pip, uv, poetry, pdm, conda, pipx, virtual environments
  cli/                  argparse, click, typer, rich, textual
  packages/             Popular libraries and frameworks (Flask, FastAPI, Django, pytest, etc.)

Sub-Skill Categories

Category	Sub-Skill	What It Covers
Project System	project-system	pyproject.toml anatomy, build backends (setuptools, hatchling, flit-core, maturin), PEP 517/518/621/660, entry points, versioning, publishing
Package Management	package-management	pip, uv, poetry, pdm, conda, pipx, virtual environments, lockfiles, private indexes
CLI Development	cli	argparse, click, typer, rich, textual, output formatting, testing CLI apps
Packages	packages	Popular Python libraries and frameworks for web, data, testing, and more

Choosing Guide

I need to...	Use this sub-skill
Set up a new Python project with pyproject.toml	project-system
Choose between setuptools, hatch, flit, or poetry for building	project-system
Configure entry points or console scripts	project-system
Publish a package to PyPI	project-system
Install dependencies or manage a lockfile	package-management
Choose between pip, uv, poetry, pdm, or conda	package-management
Set up virtual environments	package-management
Configure private package indexes	package-management
Build a command-line application	cli
Add rich terminal output (colors, tables, progress bars)	cli
Build a terminal UI (TUI)	cli
Choose between argparse, click, and typer	cli

Python Version Landscape

Version	Status	Key Features
3.9	Security fixes	Dict union operators (|, |=), str.removeprefix()/removesuffix(), type hinting generics in standard collections
3.10	Security fixes	Structural pattern matching (match/case), parenthesized context managers, TypeAlias, better error messages
3.11	Maintained	Exception groups and except*, tomllib in stdlib, significant performance improvements (10-60% faster), TaskGroup for asyncio
3.12	Maintained	Type parameter syntax (type X = ...), f-string improvements, per-interpreter GIL (subinterpreters), pathlib improvements
3.13	Latest stable	Free-threaded mode (experimental, no GIL), JIT compiler (experimental), improved typing module, better REPL
3.14+	In development	Deferred evaluation of annotations (PEP 649), further JIT/free-threading improvements

Recommendation: Target Python 3.11+ for new projects. Use 3.12+ if you need the new type parameter syntax. Use 3.13 to experiment with free-threaded mode.

Core Language Features Quick Reference

Type Hints (PEP 484, 526, 604, 612, 695)

# Basic type annotations
def greet(name: str) -> str:
    return f"Hello, {name}"

# Generic collections (3.9+ -- no need for typing.List, typing.Dict)
def process(items: list[int]) -> dict[str, int]:
    return {str(i): i for i in items}

# Union types (3.10+ -- use | instead of Union)
def parse(value: str | int) -> str:
    return str(value)

# Optional is shorthand for X | None
def find(key: str) -> str | None:
    ...

# TypeVar and generics (3.12+ type parameter syntax)
type Comparable = int | float | str

def maximum[T: Comparable](a: T, b: T) -> T:
    return a if a >= b else b

# TypedDict for structured dictionaries
from typing import TypedDict

class UserConfig(TypedDict):
    name: str
    age: int
    email: str | None

Async/Await (PEP 492)

import asyncio

async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

# TaskGroup (3.11+) -- structured concurrency
async def fetch_all(urls: list[str]) -> list[dict]:
    results = []
    async with asyncio.TaskGroup() as tg:
        for url in urls:
            tg.create_task(fetch_data(url))
    return results

# Async generators
async def stream_lines(path: str):
    async with aiofiles.open(path) as f:
        async for line in f:
            yield line.strip()

Dataclasses (PEP 557)

from dataclasses import dataclass, field

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

# Frozen (immutable) dataclass
@dataclass(frozen=True)
class Point:
    x: float
    y: float

# Slots for memory efficiency (3.10+)
@dataclass(slots=True)
class Measurement:
    timestamp: float
    value: float
    unit: str

Pattern Matching (PEP 634, 3.10+)

def handle_command(command: dict) -> str:
    match command:
        case {"action": "quit"}:
            return "Goodbye"
        case {"action": "greet", "name": str(name)}:
            return f"Hello, {name}"
        case {"action": "move", "x": int(x), "y": int(y)} if x > 0:
            return f"Moving right to ({x}, {y})"
        case _:
            return "Unknown command"

Exception Groups (PEP 654, 3.11+)

# Raising multiple exceptions
def validate(data: dict) -> None:
    errors = []
    if "name" not in data:
        errors.append(ValueError("Missing name"))
    if "age" not in data:
        errors.append(ValueError("Missing age"))
    if errors:
        raise ExceptionGroup("Validation failed", errors)

# Handling exception groups
try:
    validate({})
except* ValueError as eg:
    for exc in eg.exceptions:
        print(f"Validation error: {exc}")
except* TypeError as eg:
    for exc in eg.exceptions:
        print(f"Type error: {exc}")

Context Managers

from contextlib import contextmanager, asynccontextmanager

@contextmanager
def managed_resource(name: str):
    print(f"Acquiring {name}")
    try:
        yield name
    finally:
        print(f"Releasing {name}")

# Parenthesized context managers (3.10+)
with (
    open("input.txt") as fin,
    open("output.txt", "w") as fout,
):
    fout.write(fin.read())

Best Practices

Always Use Virtual Environments

Never install project dependencies into the system Python. Use venv, uv venv, or let your package manager (poetry, pdm) handle environment creation.

# Standard library
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

# Using uv (faster)
uv venv
source .venv/bin/activate

Adopt Type Annotations

Use type hints throughout your codebase. They improve readability, enable IDE support, and catch bugs early with mypy or pyright.

# Type checking with mypy
pip install mypy
mypy src/

# Type checking with pyright (faster, used by Pylance in VS Code)
pip install pyright
pyright src/

Format and Lint with Ruff

Ruff is an extremely fast Python linter and formatter written in Rust. It replaces flake8, isort, black, and many other tools.

# Install
pip install ruff

# Lint
ruff check src/

# Format (replaces black)
ruff format src/

# Fix auto-fixable issues
ruff check --fix src/

Minimal ruff configuration in pyproject.toml:

[tool.ruff]
target-version = "py311"
line-length = 88

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort
    "UP",   # pyupgrade
    "B",    # flake8-bugbear
    "SIM",  # flake8-simplify
    "TCH",  # flake8-type-checking
]

[tool.ruff.lint.isort]
known-first-party = ["mypackage"]

Use pyproject.toml for All Configuration

Consolidate tool configuration in pyproject.toml instead of scattering it across setup.cfg, tox.ini, .flake8, etc.

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q"

[tool.mypy]
python_version = "3.11"
strict = true

[tool.coverage.run]
source = ["src"]
branch = true

Write Tests with pytest

Use pytest as your test runner. It is the de facto standard in the Python ecosystem.

pip install pytest pytest-cov

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

Use __all__ for Public API Control

Define __all__ in __init__.py files to make your public API explicit:

# src/mypackage/__init__.py
__all__ = ["Client", "Config", "process_data"]

from .client import Client
from .config import Config
from .processing import process_data