qcp-cli 0.1.5__tar.gz

qcp_cli-0.1.5/.agents/skills/python-code-style/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: python-code-style
+description: Python code style, linting, formatting, naming conventions, and documentation standards. Use when writing new code, reviewing style, configuring linters, writing docstrings, or establishing project standards.
+---
+
+# Python Code Style & Documentation
+
+Consistent code style and clear documentation make codebases maintainable and collaborative. This skill covers modern Python tooling, naming conventions, and documentation standards.
+
+## When to Use This Skill
+
+- Setting up linting and formatting for a new project
+- Writing or reviewing docstrings
+- Establishing team coding standards
+- Configuring ruff, mypy, or pyright
+- Reviewing code for style consistency
+- Creating project documentation
+
+## Core Concepts
+
+### 1. Automated Formatting
+
+Let tools handle formatting debates. Configure once, enforce automatically.
+
+### 2. Consistent Naming
+
+Follow PEP 8 conventions with meaningful, descriptive names.
+
+### 3. Documentation as Code
+
+Docstrings should be maintained alongside the code they describe.
+
+### 4. Type Annotations
+
+Modern Python code should include type hints for all public APIs.
+
+## Quick Start
+
+```bash
+# Install modern tooling
+pip install ruff mypy
+
+# Configure in pyproject.toml
+[tool.ruff]
+line-length = 120
+target-version = "py312"  # Adjust based on your project's minimum Python version
+
+[tool.mypy]
+strict = true
+```
+
+## Fundamental Patterns
+
+### Pattern 1: Modern Python Tooling
+
+Use `ruff` as an all-in-one linter and formatter. It replaces flake8, isort, and black with a single fast tool.
+
+```toml
+# pyproject.toml
+[tool.ruff]
+line-length = 120
+target-version = "py312"  # Adjust based on your project's minimum Python version
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+]
+ignore = ["E501"]  # Line length handled by formatter
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+```
+
+Run with:
+
+```bash
+ruff check --fix .  # Lint and auto-fix
+ruff format .       # Format code
+```
+
+### Pattern 2: Type Checking Configuration
+
+Configure strict type checking for production code.
+
+```toml
+# pyproject.toml
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+```
+
+Alternative: Use `pyright` for faster checking.
+
+```toml
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+```
+
+### Pattern 3: Naming Conventions
+
+Follow PEP 8 with emphasis on clarity over brevity.
+
+**Files and Modules:**
+
+```python
+# Good: Descriptive snake_case
+user_repository.py
+order_processing.py
+http_client.py
+
+# Avoid: Abbreviations
+usr_repo.py
+ord_proc.py
+http_cli.py
+```
+
+**Classes and Functions:**
+
+```python
+# Classes: PascalCase
+class UserRepository:
+    pass
+
+class HTTPClientFactory:  # Acronyms stay uppercase
+    pass
+
+# Functions and variables: snake_case
+def get_user_by_email(email: str) -> User | None:
+    retry_count = 3
+    max_connections = 100
+```
+
+**Constants:**
+
+```python
+# Module-level constants: SCREAMING_SNAKE_CASE
+MAX_RETRY_ATTEMPTS = 3
+DEFAULT_TIMEOUT_SECONDS = 30
+API_BASE_URL = "https://api.example.com"
+```
+
+### Pattern 4: Import Organization
+
+Group imports in a consistent order: standard library, third-party, local.
+
+```python
+# Standard library
+import os
+from collections.abc import Callable
+from typing import Any
+
+# Third-party packages
+import httpx
+from pydantic import BaseModel
+from sqlalchemy import Column
+
+# Local imports
+from myproject.models import User
+from myproject.services import UserService
+```
+
+Use absolute imports exclusively:
+
+```python
+# Preferred
+from myproject.utils import retry_decorator
+
+# Avoid relative imports
+from ..utils import retry_decorator
+```
+
+## Advanced Patterns
+
+### Pattern 5: Google-Style Docstrings
+
+Write docstrings for all public classes, methods, and functions.
+
+**Simple Function:**
+
+```python
+def get_user(user_id: str) -> User:
+    """Retrieve a user by their unique identifier."""
+    ...
+```
+
+**Complex Function:**
+
+```python
+def process_batch(
+    items: list[Item],
+    max_workers: int = 4,
+    on_progress: Callable[[int, int], None] | None = None,
+) -> BatchResult:
+    """Process items concurrently using a worker pool.
+
+    Processes each item in the batch using the configured number of
+    workers. Progress can be monitored via the optional callback.
+
+    Args:
+        items: The items to process. Must not be empty.
+        max_workers: Maximum concurrent workers. Defaults to 4.
+        on_progress: Optional callback receiving (completed, total) counts.
+
+    Returns:
+        BatchResult containing succeeded items and any failures with
+        their associated exceptions.
+
+    Raises:
+        ValueError: If items is empty.
+        ProcessingError: If the batch cannot be processed.
+
+    Example:
+        >>> result = process_batch(items, max_workers=8)
+        >>> print(f"Processed {len(result.succeeded)} items")
+    """
+    ...
+```
+
+**Class Docstring:**
+
+```python
+class UserService:
+    """Service for managing user operations.
+
+    Provides methods for creating, retrieving, updating, and
+    deleting users with proper validation and error handling.
+
+    Attributes:
+        repository: The data access layer for user persistence.
+        logger: Logger instance for operation tracking.
+
+    Example:
+        >>> service = UserService(repository, logger)
+        >>> user = service.create_user(CreateUserInput(...))
+    """
+
+    def __init__(self, repository: UserRepository, logger: Logger) -> None:
+        """Initialize the user service.
+
+        Args:
+            repository: Data access layer for users.
+            logger: Logger for tracking operations.
+        """
+        self.repository = repository
+        self.logger = logger
+```
+
+### Pattern 6: Line Length and Formatting
+
+Set line length to 120 characters for modern displays while maintaining readability.
+
+```python
+# Good: Readable line breaks
+def create_user(
+    email: str,
+    name: str,
+    role: UserRole = UserRole.MEMBER,
+    notify: bool = True,
+) -> User:
+    ...
+
+# Good: Chain method calls clearly
+result = (
+    db.query(User)
+    .filter(User.active == True)
+    .order_by(User.created_at.desc())
+    .limit(10)
+    .all()
+)
+
+# Good: Format long strings
+error_message = (
+    f"Failed to process user {user_id}: "
+    f"received status {response.status_code} "
+    f"with body {response.text[:100]}"
+)
+```
+
+### Pattern 7: Project Documentation
+
+**README Structure:**
+
+```markdown
+# Project Name
+
+Brief description of what the project does.
+
+## Installation
+
+\`\`\`bash
+pip install myproject
+\`\`\`
+
+## Quick Start
+
+\`\`\`python
+from myproject import Client
+
+client = Client(api_key="...")
+result = client.process(data)
+\`\`\`
+
+## Configuration
+
+Document environment variables and configuration options.
+
+## Development
+
+\`\`\`bash
+pip install -e ".[dev]"
+pytest
+\`\`\`
+```
+
+**CHANGELOG Format (Keep a Changelog):**
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Modified behavior of Y
+
+### Fixed
+- Bug in Z
+```
+
+## Best Practices Summary
+
+1. **Use ruff** - Single tool for linting and formatting
+2. **Enable strict mypy** - Catch type errors before runtime
+3. **120 character lines** - Modern standard for readability
+4. **Descriptive names** - Clarity over brevity
+5. **Absolute imports** - More maintainable than relative
+6. **Google-style docstrings** - Consistent, readable documentation
+7. **Document public APIs** - Every public function needs a docstring
+8. **Keep docs updated** - Treat documentation as code
+9. **Automate in CI** - Run linters on every commit
+10. **Target Python 3.10+** - For new projects, Python 3.12+ is recommended for modern language features

qcp_cli-0.1.5/.agents/skills/uv-package-manager/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: uv-package-manager
+description: Master the uv package manager for fast Python dependency management, virtual environments, and modern Python project workflows. Use when setting up Python projects, managing dependencies, or optimizing Python development workflows with uv.
+---
+
+# UV Package Manager
+
+Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.
+
+## When to Use This Skill
+
+- Setting up new Python projects quickly
+- Managing Python dependencies faster than pip
+- Creating and managing virtual environments
+- Installing Python interpreters
+- Resolving dependency conflicts efficiently
+- Migrating from pip/pip-tools/poetry
+- Speeding up CI/CD pipelines
+- Managing monorepo Python projects
+- Working with lockfiles for reproducible builds
+- Optimizing Docker builds with Python dependencies
+
+## Core Concepts
+
+### 1. What is uv?
+
+- **Ultra-fast package installer**: 10-100x faster than pip
+- **Written in Rust**: Leverages Rust's performance
+- **Drop-in pip replacement**: Compatible with pip workflows
+- **Virtual environment manager**: Create and manage venvs
+- **Python installer**: Download and manage Python versions
+- **Resolver**: Advanced dependency resolution
+- **Lockfile support**: Reproducible installations
+
+### 2. Key Features
+
+- Blazing fast installation speeds
+- Disk space efficient with global cache
+- Compatible with pip, pip-tools, poetry
+- Comprehensive dependency resolution
+- Cross-platform support (Linux, macOS, Windows)
+- No Python required for installation
+- Built-in virtual environment support
+
+### 3. UV vs Traditional Tools
+
+- **vs pip**: 10-100x faster, better resolver
+- **vs pip-tools**: Faster, simpler, better UX
+- **vs poetry**: Faster, less opinionated, lighter
+- **vs conda**: Faster, Python-focused
+
+## Installation
+
+### Quick Install
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Using pip (if you already have Python)
+pip install uv
+
+# Using Homebrew (macOS)
+brew install uv
+
+# Using cargo (if you have Rust)
+cargo install --git https://github.com/astral-sh/uv uv
+```
+
+### Verify Installation
+
+```bash
+uv --version
+# uv 0.x.x
+```
+
+## Quick Start
+
+### Create a New Project
+
+```bash
+# Create new project with virtual environment
+uv init my-project
+cd my-project
+
+# Or create in current directory
+uv init .
+
+# Initialize creates:
+# - .python-version (Python version)
+# - pyproject.toml (project config)
+# - README.md
+# - .gitignore
+```
+
+### Install Dependencies
+
+```bash
+# Install packages (creates venv if needed)
+uv add requests pandas
+
+# Install dev dependencies
+uv add --dev pytest black ruff
+
+# Install from requirements.txt
+uv pip install -r requirements.txt
+
+# Install from pyproject.toml
+uv sync
+```
+
+## Virtual Environment Management
+
+### Pattern 1: Creating Virtual Environments
+
+```bash
+# Create virtual environment with uv
+uv venv
+
+# Create with specific Python version
+uv venv --python 3.12
+
+# Create with custom name
+uv venv my-env
+
+# Create with system site packages
+uv venv --system-site-packages
+
+# Specify location
+uv venv /path/to/venv
+```
+
+### Pattern 2: Activating Virtual Environments
+
+```bash
+# Linux/macOS
+source .venv/bin/activate
+
+# Windows (Command Prompt)
+.venv\Scripts\activate.bat
+
+# Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+
+# Or use uv run (no activation needed)
+uv run python script.py
+uv run pytest
+```
+
+### Pattern 3: Using uv run
+
+```bash
+# Run Python script (auto-activates venv)
+uv run python app.py
+
+# Run installed CLI tool
+uv run black .
+uv run pytest
+
+# Run with specific Python version
+uv run --python 3.11 python script.py
+
+# Pass arguments
+uv run python script.py --arg value
+```
+
+## Package Management
+
+### Pattern 4: Adding Dependencies
+
+```bash
+# Add package (adds to pyproject.toml)
+uv add requests
+
+# Add with version constraint
+uv add "django>=4.0,<5.0"
+
+# Add multiple packages
+uv add numpy pandas matplotlib
+
+# Add dev dependency
+uv add --dev pytest pytest-cov
+
+# Add optional dependency group
+uv add --optional docs sphinx
+
+# Add from git
+uv add git+https://github.com/user/repo.git
+
+# Add from git with specific ref
+uv add git+https://github.com/user/repo.git@v1.0.0
+
+# Add from local path
+uv add ./local-package
+
+# Add editable local package
+uv add -e ./local-package
+```
+
+### Pattern 5: Removing Dependencies
+
+```bash
+# Remove package
+uv remove requests
+
+# Remove dev dependency
+uv remove --dev pytest
+
+# Remove multiple packages
+uv remove numpy pandas matplotlib
+```
+
+### Pattern 6: Upgrading Dependencies
+
+```bash
+# Upgrade specific package
+uv add --upgrade requests
+
+# Upgrade all packages
+uv sync --upgrade
+
+# Upgrade package to latest
+uv add --upgrade requests
+
+# Show what would be upgraded
+uv tree --outdated
+```
+
+### Pattern 7: Locking Dependencies
+
+```bash
+# Generate uv.lock file
+uv lock
+
+# Update lock file
+uv lock --upgrade
+
+# Lock without installing
+uv lock --no-install
+
+# Lock specific package
+uv lock --upgrade-package requests
+```
+
+## Python Version Management
+
+### Pattern 8: Installing Python Versions
+
+```bash
+# Install Python version
+uv python install 3.12
+
+# Install multiple versions
+uv python install 3.11 3.12 3.13
+
+# Install latest version
+uv python install
+
+# List installed versions
+uv python list
+
+# Find available versions
+uv python list --all-versions
+```
+
+### Pattern 9: Setting Python Version
+
+```bash
+# Set Python version for project
+uv python pin 3.12
+
+# This creates/updates .python-version file
+
+# Use specific Python version for command
+uv --python 3.11 run python script.py
+
+# Create venv with specific version
+uv venv --python 3.12
+```
+
+## Project Configuration
+
+### Pattern 10: pyproject.toml with uv
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+description = "My awesome project"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.0.0",
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme>=1.3.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    # Additional dev dependencies managed by uv
+]
+
+[tool.uv.sources]
+# Custom package sources
+my-package = { git = "https://github.com/user/repo.git" }
+```
+
+### Pattern 11: Using uv with Existing Projects
+
+```bash
+# Migrate from requirements.txt
+uv add -r requirements.txt
+
+# Migrate from poetry
+# Already have pyproject.toml, just use:
+uv sync
+
+# Export to requirements.txt
+uv pip freeze > requirements.txt
+
+# Export with hashes
+uv pip freeze --require-hashes > requirements.txt
+```
+
+For advanced workflows including Docker integration, lockfile management, performance optimization, tool comparison, common workflows, tool integration, troubleshooting, best practices, migration guides, and command reference, see [references/advanced-patterns.md](references/advanced-patterns.md)