karanmrn/karanagentskills/modern-python-toolchain

Modern Python Toolchain

A guide for setting up Python projects with modern, fast tooling: uv (package/project manager), ruff (linter/formatter), and pyright (type checker).

Installing uv

uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# Homebrew (macOS)
brew install uv

After installation, restart your shell or run source $HOME/.local/bin/env (the installer prints the exact command).

For detailed information: https://docs.astral.sh/uv/

uv basics

Python version

Pin a single Python minor version. The recommended default is 3.12 (broadest ecosystem support — PyTorch, CUDA images, downstream libraries). Python 3.14 is the latest stable; prefer it for new projects unless you depend on packages that haven't added 3.14 support yet.

# pyproject.toml
requires-python = "==3.12.*"

Install Python via uv (no system Python needed):

uv python install 3.12

Creating a new project

uv init                       # Create new project with pyproject.toml
uv init -p 3.12               # Specify Python version

Common commands

uv add requests               # Add dependency
uv add --dev ruff "pyright[nodejs]"  # Add dev dependencies
uv remove requests            # Remove dependency
uv sync                       # Install from lockfile
uv run COMMAND                # Run command in project environment
uv run script.py              # Run a script
uv run python -c "..."        # Run Python one-liner
uvx TOOL ARGS                 # Run a tool without installing it

Rules

• Never use `pip` in uv projects — always uv add for packages.
• Never run `python script.py` directly — always uv run script.py to ensure the correct environment. For one-liners use uv run python -c "...".
• Don't manually manage environments with python -m venv or source .venv/bin/activate — uv handles this automatically.
• uvx runs tools from PyPI by package name without installing them permanently.

Project types

For library projects (uv init --lib) or packaged apps (uv init --package), uv_build is used as the default build backend automatically:

[build-system]
# auto-generated by uv init; version bound tracks your installed uv (here: 0.11.28)
requires = ["uv_build>=0.11.28,<0.12.0"]
build-backend = "uv_build"

For application projects with an entry point:

[project.scripts]
myapp = "myapp.__main__:main"

If the project does not use src layout, just run uv run main.py.

ruff

Ruff is an extremely fast Python linter and code formatter. It replaces Flake8, isort, Black, pyupgrade, autoflake, and more.

For detailed information: https://docs.astral.sh/ruff/

When to use

Always use ruff for Python linting and formatting. Prefer uv run ruff when ruff is a dev dependency; otherwise fall back to uvx ruff.

Configuration

Add to pyproject.toml:

[tool.ruff.lint]
extend-select = [
    "UP",  # pyupgrade
    "I",   # isort
]

Do not enable the full E category or other formatter-conflicting rules (E1xx, E501, W191, Q, COM); ruff format owns layout.

Post-edit workflow

After modifying Python code, run both:

uv run ruff check --fix path/to/changed_file.py
uv run ruff format path/to/changed_file.py

Use --diff to preview changes without applying.

pyright

Pyright is a fast type checker for Python. Only use it when the project lists it as a dev dependency or explicitly uses type checking.

Install with the nodejs extra so Node.js is bundled automatically (no system node required):

uv add --dev "pyright[nodejs]"

Run type checking:

uv run pyright path/to/changed_file.py    # check specific files
uv run pyright src/                        # check all code

Usually only check the files you modified. For broad changes (base classes, shared types), check the full tree.

Coding style

Type annotations

Use modern Python 3.12+ syntax:

# Good — builtin generics, union syntax
def fetch(url: str, timeout: float = 30.0) -> list[dict[str, str | None]]:
    ...
# Bad — legacy typing imports
from typing import List, Dict, Optional
def fetch(url: str, timeout: float = 30.0) -> List[Dict[str, Optional[str]]]:
    ...

Always annotate function parameters. Local variables can rely on inference unless the type is ambiguous:

items: list[tuple[str, int]] = []    # annotate — empty literal
config: dict[str, Any] = {}          # annotate — empty literal
result = some_api()                  # inference is fine

pydantic v2

Use the modern class-based API:

• model_config = ConfigDict(...) at class body level, not class Config.
• RootModel with root: SomeType for single-root schemas.

typer (CLI)

Recommended for CLI entry points over argparse:

import typer
from typing import Annotated
cli = typer.Typer(add_completion=False)
@cli.command()
def main(name: Annotated[str, typer.Argument(help="Your name")]) -> None:
    typer.echo(f"Hello {name}")
if __name__ == "__main__":
    cli()