home / skills / git-fg / thecattoolkit / managing-python

managing-python skill

safe

/plugins/sys-builder/skills/managing-python

This skill helps you manage Python environments, dependencies, and linting with uv and ruff, ensuring consistent projects and quality.

npx playbooks add skill git-fg/thecattoolkit --skill managing-python

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

Files (5)

SKILL.md

4.4 KB

---
name: managing-python
description: "Manages Python environments, dependencies, and tools using uv and ruff. PROACTIVELY Use when setting up Python projects, adding dependencies, managing virtual environments, or enforcing code quality standards. MUST Use `uv` for all operations."
user-invocable: false
allowed-tools: [Bash, Read, Write, Edit]
---

# UV & Ruff: Modern Python Development



## Quick Decision Tree

```
Need to install/manage Python packages?
  → uv add <package>          # Add dependency
  → uv sync                   # Install from lockfile
  → uv run <command>          # Run in project env

Need to lint or format Python code?
  → ruff check .              # Lint
  → ruff check --fix .        # Lint + auto-fix
  → ruff format .             # Format

Need to manage Python versions?
  → uv python install 3.12    # Install Python
  → uv python pin 3.12        # Pin for project

Need to run a CLI tool once?
  → uvx <tool>                # e.g., uvx black .
```

## Installation

```bash
# UV (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# UV (Windows PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Ruff (via uv - recommended)
uv tool install ruff

# Verify
uv version && ruff version
```

## Essential Commands

### UV Project Management

```bash
# Initialize project
uv init my-project && cd my-project

# Dependencies
uv add requests pandas           # Production deps
uv add --dev pytest ruff         # Dev deps
uv remove requests               # Remove dep
uv lock --upgrade                # Update lockfile

# Run commands (no activation needed)
uv run python main.py
uv run pytest
uv run ruff check .

# Python versions
uv python install 3.11 3.12
uv python pin 3.12
uv run --python 3.11 python script.py
```

### Ruff Linting & Formatting

```bash
# Lint
ruff check .                     # Check errors
ruff check --fix .               # Auto-fix
ruff check --diff .              # Preview fixes
ruff check --watch               # Continuous mode

# Format
ruff format .                    # Format files
ruff format --check .            # Check only
ruff format --diff .             # Preview changes

# Combined workflow
ruff check --fix . && ruff format .
```

## Configuration

### pyproject.toml (Minimal)

```toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
]

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

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "UP"]
ignore = ["E501"]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]
"tests/*" = ["S101"]
```

### Pre-commit Hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.12.8
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
```

## Rule Sets Quick Reference

| Code | Name | Purpose |
|:-----|:-----|:--------|
| E/W | pycodestyle | PEP 8 style |
| F | Pyflakes | Logic errors |
| I | isort | Import sorting |
| B | flake8-bugbear | Common bugs |
| UP | pyupgrade | Modern syntax |
| S | flake8-bandit | Security |
| T20 | flake8-print | Print statements |

**Recommended starter set:** `select = ["E", "W", "F", "I", "B", "UP"]`

## Suppress Errors

```python
import os  # noqa: F401           # Ignore specific rule
import sys  # noqa                # Ignore all rules
# ruff: noqa: E501               # File-level ignore
```

## CI/CD Snippet (GitHub Actions)

```yaml
- name: Install uv
  run: curl -LsSf https://astral.sh/uv/install.sh | sh

- name: Install and lint
  run: |
    uv sync --frozen
    uv run ruff check .
    uv run ruff format --check .
    uv run pytest
```

## Troubleshooting

```bash
# Clear caches
uv cache clean
ruff clean

# Debug configuration
ruff check --show-settings .

# Reinstall Python
rm -r "$(uv python dir)" && uv python install 3.12

# Reset lockfile
rm uv.lock && uv lock
```

## Detailed References

Load these for comprehensive guidance:

| Reference | Content |
|:----------|:--------|
| `references/uv-guide.md` | Complete uv documentation: projects, Python versions, building, publishing |
| `references/ruff-guide.md` | All 800+ rules, formatting options, editor integration |
| `references/migration.md` | Migrating from pip, conda, poetry, Flake8, Black, isort |
| `references/workflows.md` | Monorepos, Docker, CI/CD, production deployments |

Overview

This skill manages Python environments, dependencies, and developer tooling using uv and ruff. It proactively helps set up projects, add or remove packages, pin Python versions, and enforce linting and formatting rules for consistent code quality. Use uv for every environment and package operation and ruff for linting/formatting.

How this skill works

The skill runs uv commands to initialize projects, install or remove dependencies, sync lockfiles, and manage Python versions and virtual environments. For code quality it runs ruff to check, auto-fix, and format code, and can integrate those checks into CI or pre-commit hooks. All operations are executed via uv (uv add, uv run, uv python, uv lock, uv sync, uvx) and ruff commands are run inside the uv-managed environment.

When to use it

Bootstrapping a new Python project and creating a reproducible environment with uv init and uv lock.
Adding, upgrading, or removing dependencies with uv add, uv remove, and uv lock --upgrade.
Installing or pinning a Python interpreter for the project with uv python install / pin.
Running tests or tools without activating a virtualenv using uv run or uvx for one-off CLIs.
Enforcing linting and formatting consistently using ruff check, ruff format, or ruff check --fix.
Integrating checks into CI pipelines or pre-commit with uv run ruff and uv sync.

Best practices

Always use uv add / uv remove and uv lock to keep uv.lock authoritative and reproducible.
Pin the project Python version (uv python pin) to avoid local interpreter drift.
Run uv sync --frozen in CI to install exactly what the lockfile specifies.
Use ruff check --fix and ruff format . together to both lint and normalize style automatically.
Install ruff via uv tool install ruff so linting runs inside the same uv-managed environment.
Add a pre-commit hook or GitHub Actions step that runs uv run ruff and uv run ruff format --check.

Example use cases

Create a new project and add runtime + dev dependencies: uv init my-project && uv add requests && uv add --dev pytest ruff.
Upgrade a dependency safely: uv add --upgrade package && uv lock --upgrade && uv sync.
Ensure CI uses the exact environment: uv sync --frozen && uv run ruff check . && uv run pytest.
Fix style and lint errors across the repo: uv run ruff check --fix . && uv run ruff format .
Install multiple Python versions for testing: uv python install 3.11 3.12 and pin the desired one for CI.

FAQ

Do I need to activate a virtualenv to run tools?

No. Use uv run <command> or uvx <tool> so commands and tools run inside the uv-managed environment without manual activation.

How do I ensure CI matches local installs?

Run uv sync --frozen in CI to install exactly what's in the lockfile, then run uv run ruff and uv run pytest for checks.