Initial commit

2025-11-30 09:01:33 +08:00
commit 5115beb98d
8 changed files with 3836 additions and 0 deletions
--- a/skills/skill/SKILL.md
+++ b/skills/skill/SKILL.md
@@ -0,0 +1,422 @@
+---
+name: uv-ruff-python-tools
+description: Modern Python development with uv (10-100x faster package manager) and ruff (extremely fast linter/formatter). Use when managing Python projects, dependencies, virtual environments, installing packages, linting code, or formatting Python files. Triggers on phrases like "uv install", "ruff check", "python package manager", "format python code", or working with pyproject.toml files.
+---
+
+# UV & Ruff: Modern Python Development Tools
+
+Supercharge your Python development with Astral's blazing-fast tooling suite - uv for package management and ruff for code quality.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- **Package Management**: Install, update, or manage Python dependencies 10-100x faster than pip
+- **Project Setup**: Initialize new Python projects with modern standards
+- **Python Versions**: Install and manage multiple Python versions
+- **Code Linting**: Check Python code for errors and style issues
+- **Code Formatting**: Auto-format Python code to consistent style
+- **Virtual Environments**: Create and manage isolated Python environments
+- **Migration**: Move from pip, conda, poetry, or pipx to modern tooling
+
+## Quick Start
+
+### Installing UV
+
+```bash
+# macOS/Linux - standalone installer
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows - PowerShell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# With Homebrew
+brew install uv
+
+# With pipx
+pipx install uv
+
+# Verify installation
+uv version
+```
+
+### Installing Ruff
+
+```bash
+# With uv (recommended)
+uv tool install ruff
+
+# With pip
+pip install ruff
+
+# With Homebrew
+brew install ruff
+
+# Verify installation
+ruff version
+```
+
+## Common Workflows
+
+### Project Management with UV
+
+```bash
+# Create a new project
+uv init my-project
+cd my-project
+
+# Add dependencies
+uv add requests pandas numpy
+
+# Add development dependencies
+uv add --dev pytest black ruff
+
+# Install all dependencies
+uv sync
+
+# Run a script in the project environment
+uv run python main.py
+
+# Run a tool (like pytest)
+uv run pytest
+
+# Update dependencies
+uv lock --upgrade
+uv sync
+```
+
+### Code Quality with Ruff
+
+```bash
+# Check for linting errors
+ruff check .
+
+# Auto-fix linting errors
+ruff check --fix .
+
+# Format code
+ruff format .
+
+# Check formatting without changes
+ruff format --check .
+
+# Watch mode (continuous linting)
+ruff check --watch
+
+# Lint and format in one command
+ruff check --fix . && ruff format .
+```
+
+### Python Version Management
+
+```bash
+# Install Python versions
+uv python install 3.11 3.12 3.13
+
+# List installed Python versions
+uv python list
+
+# Pin Python version for project
+uv python pin 3.12
+
+# Use specific Python version
+uv run --python 3.11 python script.py
+```
+
+## Key Features
+
+### UV Features
+
+**🚀 Speed**: 10-100x faster than pip for package installation
+- Parallel downloads and caching
+- Rust-powered dependency resolution
+- Global package cache for deduplication
+
+**📦 All-in-One Tool**: Replaces multiple tools
+- `pip` - Package installation
+- `pip-tools` - Dependency locking
+- `pipx` - Tool installation
+- `poetry` - Project management
+- `pyenv` - Python version management
+- `virtualenv` - Environment creation
+
+**🔒 Reproducible Environments**:
+- Universal lockfiles (`uv.lock`)
+- Platform-independent resolution
+- Version pinning
+
+### Ruff Features
+
+**⚡ Extreme Speed**: 10-100x faster than existing linters
+- Written in Rust for maximum performance
+- Processes entire codebases in milliseconds
+
+**🔧 Unified Tool**: Replaces multiple tools
+- `Flake8` - Linting
+- `Black` - Formatting
+- `isort` - Import sorting
+- `pyupgrade` - Modern Python syntax
+- `autoflake` - Unused code removal
+
+**📏 800+ Rules**: Comprehensive code quality
+- Pyflakes error detection
+- pycodestyle (PEP 8) compliance
+- flake8-bugbear best practices
+- Many popular Flake8 plugins built-in
+
+## Common Patterns
+
+### UV Patterns
+
+```bash
+# Quick tool execution (like npx or pipx)
+uvx ruff check .
+uvx black .
+uvx pytest
+
+# Build and publish packages
+uv build
+uv publish
+
+# Pip-compatible interface (drop-in replacement)
+uv pip install requests
+uv pip freeze > requirements.txt
+uv pip compile requirements.in
+uv pip sync requirements.txt
+
+# Create virtual environment
+uv venv
+source .venv/bin/activate  # Linux/macOS
+.venv\Scripts\activate     # Windows
+
+# Run scripts with inline dependencies
+uv add --script my_script.py requests
+uv run my_script.py
+```
+
+### Ruff Patterns
+
+```bash
+# Enable specific rule sets
+ruff check --select E,W,F,I .
+
+# Ignore specific rules
+ruff check --ignore E501 .
+
+# Show fixes that will be applied
+ruff check --diff .
+
+# Format with preview features
+ruff format --preview .
+
+# Check specific files
+ruff check src/main.py tests/test_main.py
+
+# Output formats
+ruff check --output-format json .
+ruff check --output-format github .
+```
+
+## Configuration
+
+### UV Configuration (pyproject.toml)
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+description = "My Python project"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.31.0",
+    "pandas>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.uv.sources]
+# Use specific package sources if needed
+```
+
+### Ruff Configuration (pyproject.toml)
+
+```toml
+[tool.ruff]
+# Set line length
+line-length = 88
+indent-width = 4
+target-version = "py311"
+
+# Exclude directories
+exclude = [
+    ".git",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+]
+
+[tool.ruff.lint]
+# Enable rule sets
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+]
+
+# Ignore specific rules
+ignore = [
+    "E501",  # line too long (handled by formatter)
+]
+
+# Allow auto-fix for all enabled rules
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # Allow unused imports
+"tests/*" = ["S101"]      # Allow assert statements
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+```
+
+## Integration with Development Tools
+
+### Pre-commit Hooks
+
+```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
+```
+
+### CI/CD (GitHub Actions)
+
+```yaml
+name: Lint and Test
+
+on: [push, pull_request]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Format check with ruff
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run pytest
+```
+
+## Detailed Documentation
+
+For comprehensive guides and advanced usage, see the reference files:
+
+- **references/uv-guide.md** - Complete uv documentation
+  - Project management workflows
+  - Python version management
+  - Package building and publishing
+  - Migration from other tools
+
+- **references/ruff-guide.md** - Complete ruff documentation
+  - All 800+ linting rules
+  - Formatting options
+  - Rule configuration
+  - Editor integration
+
+- **references/migration.md** - Migration guides
+  - From pip + virtualenv
+  - From conda
+  - From poetry
+  - From pipx
+
+- **references/workflows.md** - Advanced workflows
+  - Monorepo management
+  - Docker integration
+  - Production deployments
+
+## Resources
+
+**Official Documentation:**
+- [uv Documentation](https://docs.astral.sh/uv/)
+- [Ruff Documentation](https://docs.astral.sh/ruff/)
+- [Astral (Parent Company)](https://astral.sh)
+
+**GitHub Repositories:**
+- [astral-sh/uv](https://github.com/astral-sh/uv)
+- [astral-sh/ruff](https://github.com/astral-sh/ruff)
+
+**Community:**
+- [Ruff Discord](https://discord.gg/astral-sh)
+- [GitHub Discussions](https://github.com/astral-sh/uv/discussions)
+
+## Troubleshooting
+
+**UV Issues:**
+```bash
+# Clear cache
+uv cache clean
+
+# Reinstall Python
+rm -r "$(uv python dir)"
+uv python install 3.12
+
+# Reset lockfile
+rm uv.lock
+uv lock
+```
+
+**Ruff Issues:**
+```bash
+# Clear cache
+ruff clean
+
+# Show current settings
+ruff check --show-settings
+
+# List all available rules
+ruff rule --all
+
+# Explain a specific rule
+ruff rule E501
+```
+
+## Notes
+
+- UV and Ruff are both built by Astral and designed to work together seamlessly
+- UV automatically creates and manages virtual environments - no manual activation needed
+- Ruff can replace Black, isort, Flake8, and more with a single tool
+- Both tools are written in Rust for maximum performance
+- UV's lockfile format is becoming a Python standard (PEP 751 proposal)
+- Ruff is compatible with Black formatting by default