commit 341ec3330956124546a17521bac224f7f33734b3 Author: Zhongwei Li Date: Sun Nov 30 08:52:22 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..b5ae7ae --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "uv-python-manager", + "description": "Standardize Python development using UV - a fast, unified package and project manager", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Rob Anderson", + "email": "zhongweili@tubi.tv" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a7af009 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# uv-python-manager + +Standardize Python development using UV - a fast, unified package and project manager diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b54fabe --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:robanderson/claude-my-skills:uv-python-manager", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "f70717742d82347e6f4f641ad1e138978b6dcf9f", + "treeHash": "5c77b36f68e977e66c6b9a1ef13a37ec71de0ff28f790603522838b397c962a0", + "generatedAt": "2025-11-28T10:28:00.081673Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "uv-python-manager", + "description": "Standardize Python development using UV - a fast, unified package and project manager", + "version": null + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "1ea1b9a37a02360b0f5da76b13f5e2c699a3463a0d75958d5b0aa7d88eb6b064" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d426b0325080107cf82db50d3e56be3800d6afd17071505fb48bd9703cdb5fb1" + }, + { + "path": "skills/uv-python-manager/SKILL.md", + "sha256": "a78a69cfe2a0fbded705d96faf5bafaa1d09f7dd4e79019b5564b85b16422a04" + } + ], + "dirSha256": "5c77b36f68e977e66c6b9a1ef13a37ec71de0ff28f790603522838b397c962a0" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/uv-python-manager/SKILL.md b/skills/uv-python-manager/SKILL.md new file mode 100644 index 0000000..6ee2ca2 --- /dev/null +++ b/skills/uv-python-manager/SKILL.md @@ -0,0 +1,530 @@ +--- +name: uv-python-manager +description: Standardize Python development using UV - a fast, unified package and project manager. Use when creating Python projects, managing dependencies, setting up virtual environments, installing Python versions, or optimizing Python workflows. Replaces pip, virtualenv, pyenv, poetry, and pipx with a single 10-100x faster tool. +--- + +# uv-python-manager + +UV is the modern standard for Python package and project management in 2025, delivering 10-100x speed improvements while unifying pip, virtualenv, pyenv, poetry, and pipx into a single Rust-based tool. + +## When to Use This Skill + +Use this skill when: +- Creating new Python projects +- Managing dependencies and lockfiles +- Setting up virtual environments +- Installing or switching Python versions +- Building or publishing packages +- Optimizing CI/CD pipelines +- Migrating from pip, poetry, or other tools +- Creating portable Python scripts +- Working with Docker containers + +## Core Principles + +1. **Project-first workflow**: Use `uv init` and `uv add` instead of manual configuration +2. **Lock file discipline**: Always commit `uv.lock` for reproducibility +3. **Universal execution**: Use `uv run` instead of manual environment activation +4. **Version pinning**: Use `.python-version` for team consistency +5. **Fast by default**: Leverage caching and parallel operations (8-100x faster than pip) + +## Quick Start + +### Installing UV + +```bash +# macOS/Linux +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Windows PowerShell +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" + +# Update UV +uv self update +``` + +### Creating a New Project + +```bash +# Initialize project (creates pyproject.toml, .python-version, .gitignore) +uv init my-project +cd my-project + +# Add dependencies +uv add requests fastapi pandas + +# Add development dependencies +uv add --dev pytest ruff mypy + +# Add to custom groups +uv add --group docs sphinx +uv add --group test pytest-cov + +# Run code (auto-syncs environment) +uv run python main.py +uv run pytest +``` + +## Essential Commands Reference + +### Project Lifecycle +```bash +uv init [name] # Create new project with structure +uv add # Add dependency (updates pyproject.toml + uv.lock) +uv add --dev # Add development dependency +uv add --group # Add to custom dependency group +uv remove # Remove dependency +uv sync # Install/sync all dependencies +uv sync --frozen # Sync without updating lock (CI mode) +uv sync --no-dev # Production install (exclude dev deps) +uv run # Run command in project environment +uv build # Build distribution packages +uv publish # Publish to PyPI +``` + +### Python Version Management +```bash +uv python install 3.12 # Install Python version +uv python install 3.11 3.12 # Install multiple versions +uv python list # List installed Python versions +uv python pin 3.12 # Pin project to Python version +uv python find # Show active Python version +``` + +### Virtual Environments +```bash +uv venv # Create virtual environment (.venv/) +uv venv --python 3.12 # Create with specific Python version +uv venv my-env # Create with custom name +``` + +### Lock File Management +```bash +uv lock # Update lockfile from pyproject.toml +uv lock --upgrade # Upgrade all dependencies +uv lock --upgrade-package # Upgrade specific package +uv lock --check # Verify lock is current (CI check) +uv export --format requirements-txt > requirements.txt # Export format +``` + +### Tool Management (replaces pipx) +```bash +uvx # Run tool temporarily (no install) +uvx ruff check . # Example: run ruff once +uv tool install # Install tool globally +uv tool list # List installed tools +uv tool uninstall # Remove global tool +``` + +### Maintenance +```bash +uv cache clean # Clean cache +uv cache dir # Show cache location +uv self update # Update UV itself +``` + +## Project Structure Best Practices + +### Standard Layout +``` +project/ +├── .git/ +├── .gitignore # Auto-generated by uv init +├── .python-version # Python version pin (COMMIT THIS) +├── README.md # Setup instructions +├── pyproject.toml # Project configuration (COMMIT THIS) +├── uv.lock # Universal lockfile (COMMIT THIS) +├── .venv/ # Virtual environment (DO NOT COMMIT) +├── src/ +│ └── package/ +│ ├── __init__.py +│ └── main.py +└── tests/ + └── test_main.py +``` + +### pyproject.toml Structure +```toml +[project] +name = "my-app" +version = "0.1.0" +description = "Application description" +readme = "README.md" +requires-python = ">=3.11" +dependencies = [ + "requests>=2.31.0,<3.0.0", # Range with upper bound + "pandas>=2.0.0", # Minimum version + "fastapi[standard]>=0.115.0", # With extras +] + +[project.optional-dependencies] +plotting = ["matplotlib>=3.7.0", "seaborn>=0.12.0"] +database = ["sqlalchemy>=2.0.0", "psycopg2-binary>=2.9.0"] + +[dependency-groups] +dev = ["pytest>=8.0.0", "ruff>=0.3.0", "mypy>=1.8.0"] +test = ["pytest-cov>=4.1.0", "pytest-asyncio>=0.23.0"] +docs = ["sphinx>=7.0.0", "sphinx-rtd-theme>=2.0.0"] +``` + +## Key Workflows + +### Dependency Management + +**Adding dependencies:** +```bash +# Single package +uv add requests + +# Multiple packages +uv add requests pandas numpy + +# With version constraints +uv add "fastapi>=0.115.0,<1.0.0" + +# With extras +uv add "fastapi[standard]" + +# Development dependencies +uv add --dev pytest ruff mypy + +# Optional dependency groups +uv add --optional plotting matplotlib seaborn +``` + +**Managing versions:** +```bash +# Upgrade all dependencies +uv lock --upgrade + +# Upgrade specific package +uv lock --upgrade-package requests + +# Pin to latest compatible versions +uv add requests --upgrade +``` + +### Running Code + +**Always use `uv run` instead of activating environments:** +```bash +# Run Python scripts +uv run python script.py +uv run python -m mymodule + +# Run installed tools +uv run pytest +uv run ruff check . +uv run mypy src/ + +# Run with specific Python version +uv run --python 3.12 python script.py + +# Pass arguments +uv run pytest tests/ -v --cov +``` + +**Why `uv run` is better:** +- Auto-syncs environment before running +- Works cross-platform without activation scripts +- Ensures reproducibility +- Handles environment discovery automatically + +### Inline Script Dependencies (PEP 723) + +Create portable single-file scripts: + +```python +#!/usr/bin/env -S uv run +# /// script +# requires-python = ">=3.11" +# dependencies = [ +# "requests", +# "rich", +# ] +# /// + +import requests +from rich import print + +response = requests.get("https://api.github.com") +print(response.json()) +``` + +Run with: `uv run script.py` (automatically installs dependencies) + +### Python Version Management + +**Project-level pinning:** +```bash +# Pin Python version for project +uv python pin 3.12 + +# This creates .python-version file +# Always commit this file to git + +# UV will automatically use this version +uv run python --version +``` + +**Installing Python versions:** +```bash +# Install specific version +uv python install 3.12 + +# Install multiple versions +uv python install 3.11 3.12 3.13 + +# List available versions +uv python list --all-versions + +# List installed versions +uv python list +``` + +### CI/CD Integration + +**GitHub Actions example:** +```yaml +name: CI +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up UV + uses: astral-sh/setup-uv@v6 + with: + version: "0.9.5" # Pin UV version + enable-cache: true + + - name: Set up Python + run: uv python install + + - name: Install dependencies + run: uv sync --frozen # Use --frozen in CI + + - name: Check lock file is current + run: uv lock --check + + - name: Run tests + run: uv run pytest + + - name: Run linting + run: uv run ruff check . +``` + +**Docker optimization:** +```dockerfile +FROM python:3.12-slim + +# Install UV +COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv + +# Set working directory +WORKDIR /app + +# Copy dependency files +COPY pyproject.toml uv.lock ./ + +# Install dependencies with caching +RUN --mount=type=cache,target=/root/.cache/uv \ + uv sync --frozen --no-dev + +# Copy application code +COPY . . + +# Compile bytecode for faster startup +ENV UV_COMPILE_BYTECODE=1 + +# Run application +CMD ["uv", "run", "python", "-m", "myapp"] +``` + +**Multi-stage Docker build:** +```dockerfile +# Stage 1: Build +FROM python:3.12-slim AS builder +COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv +WORKDIR /app +COPY pyproject.toml uv.lock ./ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv sync --frozen --no-dev --no-editable + +# Stage 2: Runtime +FROM python:3.12-slim +WORKDIR /app +COPY --from=builder /app/.venv /app/.venv +COPY . . +ENV PATH="/app/.venv/bin:$PATH" +ENV UV_COMPILE_BYTECODE=1 +CMD ["python", "-m", "myapp"] +``` + +## Migration from Existing Tools + +### From pip/pip-tools +```bash +# Automated migration +uvx migrate-to-uv + +# Or manual migration: +# 1. Create UV project +uv init + +# 2. Import from requirements.txt +uv add -r requirements.txt +uv add --dev -r requirements-dev.txt + +# 3. Commit new files +git add pyproject.toml uv.lock .python-version +git rm requirements.txt requirements-dev.txt +``` + +### From Poetry +```bash +# Automated migration +uvx migrate-to-uv + +# UV reads pyproject.toml directly +# Just start using UV commands: +uv sync # Replaces: poetry install +uv add pkg # Replaces: poetry add pkg +uv run cmd # Replaces: poetry run cmd +``` + +### From virtualenv/venv +```bash +# Old workflow: +# python -m venv .venv +# source .venv/bin/activate # or .venv\Scripts\activate on Windows +# pip install -r requirements.txt + +# New workflow: +uv init +uv add -r requirements.txt +uv run python script.py # No activation needed +``` + +## Troubleshooting + +### Common Issues + +**Lock file out of sync:** +```bash +# Error: "lock file is out of date" +uv lock # Regenerate lock file +``` + +**Python version not found:** +```bash +# Error: "Python 3.12 not found" +uv python install 3.12 +``` + +**Dependency conflicts:** +```bash +# Check resolution +uv lock --verbose + +# Try upgrading +uv lock --upgrade + +# Check specific package +uv lock --upgrade-package problematic-package +``` + +**Cache issues:** +```bash +# Clean cache if corrupted +uv cache clean + +# Show cache location +uv cache dir +``` + +**Import resolution issues:** +```bash +# Ensure environment is synced +uv sync + +# Force reinstall +uv sync --reinstall +``` + +## Best Practices Checklist + +- ✅ Always commit `uv.lock` and `.python-version` to version control +- ✅ Use `uv sync --frozen` in CI/CD pipelines +- ✅ Add `.venv/` to `.gitignore` and `.dockerignore` +- ✅ Pin UV version in CI for consistency +- ✅ Use `uv run` instead of manual environment activation +- ✅ Specify `requires-python` range in `pyproject.toml` +- ✅ Use dependency groups for dev tools, not optional-dependencies +- ✅ Test with `--resolution lowest` for libraries +- ✅ Enable bytecode compilation in Docker: `UV_COMPILE_BYTECODE=1` +- ✅ Use cache mounts in Docker for faster builds +- ✅ Run `uv lock --check` in CI to catch outdated lockfiles +- ✅ Leverage inline script dependencies (PEP 723) for portable tools +- ✅ Document UV setup in README for team onboarding + +## Performance Impact + +UV achieves dramatic speed improvements: +- **8-10x faster** than pip without caching +- **80-115x faster** with warm cache +- **Virtual environment creation:** 100ms vs 8 seconds (python -m venv) +- **Complex dependency resolution:** seconds vs minutes +- **CI/CD impact:** 30-65% faster builds + +This speed enables new workflows like re-syncing environments on every command invocation without performance penalties. + +## Advanced Topics + +For more specialized use cases, see: +- [WORKSPACE.md](WORKSPACE.md) - Monorepo and multi-project setups +- [PUBLISHING.md](PUBLISHING.md) - Building and publishing packages +- [SCRIPTS.md](SCRIPTS.md) - Advanced script management patterns + +## Key Differences from Other Tools + +### vs pip +- **Speed:** 8-100x faster +- **Lock files:** Built-in universal lockfiles +- **Python management:** Can install Python versions +- **Unified:** Replaces pip + pip-tools + virtualenv + +### vs Poetry +- **Speed:** Significantly faster resolution and installation +- **Lock files:** Universal (cross-platform in one file) +- **Simpler:** Less configuration required +- **Compatible:** Reads Poetry's pyproject.toml + +### vs Conda +- **Scope:** Python-only (doesn't handle system dependencies) +- **Speed:** Much faster for Python packages +- **Compatibility:** Standard PyPI ecosystem +- **Not a replacement:** Use Conda when you need non-Python dependencies + +## Support and Resources + +- **Documentation:** https://docs.astral.sh/uv/ +- **GitHub:** https://github.com/astral-sh/uv +- **Discord:** Join Astral's community +- **Changelog:** https://github.com/astral-sh/uv/releases + +## Summary + +UV standardizes Python development by unifying package management, environment management, Python version management, and script execution into a single fast tool. The key workflow is: + +1. `uv init` to create projects +2. `uv add` to manage dependencies +3. `uv run` to execute code +4. `uv sync --frozen` in CI/CD +5. Commit `uv.lock` and `.python-version` + +This provides consistent, fast, reproducible Python workflows across all platforms. +