Skills for working with Python using Astral tools.

GitHub stars
319

Install

/plugin install astral@astral-sh

Run it inside Claude Code after adding the marketplace with /plugin marketplace add astral-sh/claude-code-plugins.

Contents

Discovered from source

Skills 3

ruff

Ruff is an extremely fast Python linter and code formatter. It replaces Flake8, isort, Black, pyupgrade, autoflake, and dozens of other tools.

When to use ruff

Always use ruff for Python linting and formatting, especially if you see:

  • [tool.ruff] section in pyproject.toml
  • A ruff.toml or .ruff.toml configuration file

However, avoid making unnecessary changes:

  • Don't format unformatted code - If ruff format --diff shows changes throughout an entire file, the project likely isn't using ruff for formatting. Skip formatting to avoid obscuring actual changes.
  • Scope fixes to code being edited - Use ruff check --diff to see fixes relevant to the code you're changing. Only apply fixes to files you're modifying unless the user explicitly asks for broader fixes.

How to invoke ruff

  • uv run ruff ... - Use when ruff is in the project's dependencies to ensure you use the pinned version
  • uvx ruff ... - Use when ruff is not a project dependency, or for quick one-off checks
  • ruff ... - Use if ruff is installed globally

Commands

Linting

ruff check .                  # Check all files in current directory
ruff check path/to/file.py    # Check specific file
ruff check --fix .            # Auto-fix fixable violations
ruff check --fix --unsafe-fixes .  # Include unsafe fixes (review changes!)
ruff check --watch .          # Watch for changes and re-lint
ruff check --select E,F .     # Only check specific rules
ruff check --ignore E501 .    # Ignore specific rules
ruff rule E501                # Explain a specific rule
ruff linter                   # List available linters

Formatting

ruff format .                 # Format all files
ruff format path/to/file.py   # Format specific file
ruff format --check .         # Check if files are formatted (no changes)
ruff format --diff .          # Show formatting diff without applying

uv format runs the Ruff formatter. Use uv format --check -- path/to/file.py to check one file. By default, uv format selects a Ruff version independently of the project's lockfile. When the project pins Ruff, use uv run ruff format to match its formatter version.

Configuration

Ruff is configured in pyproject.toml or ruff.toml:

# pyproject.toml
[tool.ruff.lint]
extend-select = ["I", "UP"]  # Add import sorting and pyupgrade to the defaults

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

Migrating from other tools

Black → ruff format

black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .

Flake8 → ruff check

flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .

isort → ruff check

isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .

Common patterns

Apply lint fixes before formatting

Run ruff check --fix before ruff format. Lint fixes can change code structure (e.g., reordering imports), which formatting then cleans up.

ruff check --fix .
ruff format .

Applying and reviewing unsafe fixes

Ruff's full diagnostic output can show a suggested change even when --fix would leave the code alone. Safe fixes can be applied with --fix. Unsafe fixes may change behavior and also require --unsafe-fixes. A suggestion marked for manual review, such as removing commented-out code for ERA001, requires a manual edit.

ruff check --fix --unsafe-fixes --diff .  # Preview changes first
ruff check --fix --unsafe-fixes .         # Apply changes

Always review changes before applying --unsafe-fixes:

  • Use ruff rule <CODE> to understand why the fix is considered unsafe
  • Verify the fix doesn't violate those assumptions in your code

Documentation

For detailed information, read the official documentation:

ty

ty is an extremely fast Python type checker and language server. It replaces mypy, Pyright, and other type checkers.

When to use ty

Always use ty for Python type checking, especially if you see:

  • [tool.ty] section in pyproject.toml
  • A ty.toml configuration file

How to invoke ty

  • uv run ty ... - Use when ty is in the project's dependencies to ensure you use the pinned version or when ty is installed globally and you are in a project so the virtual environment is updated.
  • uvx ty ... - Use when ty is not a project dependency, or for quick one-off checks
  • ty ... - Use if ty is installed globally

Commands

Type checking

ty check                      # Check all files in current directory
ty check path/to/file.py      # Check specific file
ty check src/                 # Check specific directory

In a uv project, uv check runs ty with the project's environment. Use ty check path/to/file.py to select an individual project file. For a script with inline dependencies, use uv check --script script.py.

Rule configuration

ty check --error possibly-unresolved-reference   # Treat as error
ty check --warn division-by-zero                 # Treat as warning
ty check --ignore import-not-found               # Disable rule
ty explain rule import-not-found                 # Explain the rule and its history

Python version targeting

ty check --python-version 3.12     # Check against Python 3.12
ty check --python-platform linux   # Target Linux platform

Configuration

ty is configured in pyproject.toml or ty.toml:

# pyproject.toml
[tool.ty.environment]
python-version = "3.12"

[tool.ty.rules]
possibly-unresolved-reference = "warn"
division-by-zero = "error"

[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]

[tool.ty.terminal]
output-format = "full"

Per-file overrides

Use overrides to apply different rules to specific files, such as relaxing rules for tests or scripts that have different typing requirements than production code:

[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"

Language server

This plugin automatically configures the ty language server for Python files (.py and .pyi).

Migrating from other tools

mypy → ty

mypy .                        → ty check
mypy path/to/file.py          → ty check path/to/file.py

Pyright → ty

pyright .                     → ty check
pyright path/to/file.py       → ty check path/to/file.py

Common patterns

Don't add ignore comments

Fix type errors instead of suppressing them. Only add ignore comments when explicitly requested by the user. Use ty: ignore, not type: ignore, and prefer rule-specific ignores:

# Good: rule-specific ignore
x = undefined_var  # ty: ignore[unresolved-reference]

# Bad: blanket ty ignore
x = undefined_var  # ty: ignore

# Bad: tool agnostic blanket ignore
x = undefined_var  # type: ignore

Documentation

For detailed information, read the official documentation:

uv

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

When to use uv

Always use uv for Python work, especially if you see:

  • The uv.lock file
  • uv headers in requirements* files, e.g., "This file was autogenerated by uv"

Don't use uv in projects managed by other tools:

  • Poetry projects (identifiable by poetry.lock file)
  • PDM projects (identifiable by pdm.lock file)

Choosing the right workflow

Scripts

Use when: Running single Python files and standalone scripts.

Key commands:

uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script

Projects

Use when: There is a pyproject.toml or uv.lock

Key commands:

uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Sync the environment and update the lockfile if needed
uv sync --locked          # Require an up-to-date lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

Tools

Use uv run for tools declared in the project, such as uv run pytest or uv run ruff check .. This uses the project's locked tool versions and makes its dependencies available to the command. Use uvx for standalone tools that can run in an isolated environment.

Key commands:

uvx <tool> <args>            # Run a tool in an isolated environment
uvx <tool>@<version> <args>  # Run a specific version of a tool

Important:

  • uvx runs tools from PyPI by package name. This can be unsafe - only run well-known tools.
  • Only use uv tool install only when specifically requested by the user.

Type checking

Use uv check to type check a uv project with ty. It syncs the project environment and uses the version of ty in uv.lock when ty is a project dependency or a member of the dev dependency group. Otherwise, uv selects a compatible version of ty.

For a PEP 723 script, use uv check --script script.py to check it with its inline dependencies.

Pip interface

Use when: Legacy workflows with requirements.txt or manual environment management, no uv.lock present.

Key commands:

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt

Important:

  • Don't use the pip interface unless clearly needed.
  • Don't introduce new requirements.txt files.
  • Prefer uv init for new projects.

Migrating from other tools

pyenv → uv python

pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default

pipx → uvx

pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list

pip and pip-tools → uv pip

pip install package      → uv pip install package
pip install -r req.txt   → uv pip install -r req.txt
pip freeze               → uv pip freeze
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv

Common patterns

Don't use pip in uv projects

# Bad
pip install requests

# Good
uv add requests

Don't run python directly

# Bad
python script.py

# Good
uv run script.py
# Bad
python -c "..."

# Good
uv run python -c "..."
# Bad
python3.12 -c "..."

# Good
uv run --python 3.12 python -c "..."

Use uvx python@3.12 when you explicitly want a standalone interpreter.

Don't manually manage environments in uv projects

# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>

Documentation

For detailed information, read the official documentation:

The documentation links to specific pages for each of these workflows.

Sponsors

Details

Marketplace
astral-sh/claude-code-plugins
Source
plugins/astral
Category
Community