cli-jaw 0.1.6 → 0.1.8

package/skills_ref/modern-python/skills/modern-python/references/pep723-scripts.md

@@ -1,259 +0,0 @@
-# PEP 723: Inline Script Metadata
-
-PEP 723 allows embedding dependency metadata directly in Python scripts, eliminating the need for separate `requirements.txt` or `pyproject.toml` files for simple scripts.
-
-## When to Use PEP 723
-
-**Use for:**
-- Single-file scripts with external dependencies
-- Quick automation scripts
-- Utility scripts shared between projects
-- Scripts that need to be self-contained
-
-**Don't use for:**
-- Multi-file projects (use `pyproject.toml`)
-- Reusable packages/libraries
-- Projects requiring complex configuration
-
-## Basic Syntax
-
-The metadata block uses TOML format embedded in a special comment:
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = [
-#     "requests",
-#     "rich",
-# ]
-# ///
-
-import requests
-from rich import print
-
-response = requests.get("https://api.example.com/data")
-print(response.json())
-```
-
-## Running Scripts
-
-```bash
-# With uv (recommended)
-uv run script.py
-
-# Script handles its own dependencies automatically
-./script.py  # If shebang is set
-```
-
-## Metadata Fields
-
-### Required Python Version
-
-```python
-# /// script
-# requires-python = ">=3.11"
-# ///
-```
-
-### Dependencies
-
-```python
-# /// script
-# dependencies = [
-#     "requests",
-#     "click",
-#     "rich",
-# ]
-# ///
-```
-
-### Private Package Index
-
-```python
-# /// script
-# dependencies = ["httpx"]
-#
-# [tool.uv]
-# extra-index-url = ["https://pypi.company.com/simple/"]
-# ///
-```
-
-## Complete Example
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = [
-#     "httpx",
-#     "rich",
-#     "typer",
-# ]
-# ///
-
-"""Fetch and display API data with nice formatting."""
-
-import httpx
-import typer
-from rich.console import Console
-from rich.table import Table
-
-console = Console()
-app = typer.Typer()
-
-
-@app.command()
-def fetch(url: str, format: str = "table"):
-    """Fetch data from URL and display it."""
-    with httpx.Client() as client:
-        response = client.get(url)
-        response.raise_for_status()
-        data = response.json()
-
-    if format == "table" and isinstance(data, list):
-        table = Table()
-        if data:
-            for key in data[0].keys():
-                table.add_column(key)
-            for item in data:
-                table.add_row(*[str(v) for v in item.values()])
-        console.print(table)
-    else:
-        console.print_json(data=data)
-
-
-if __name__ == "__main__":
-    app()
-```
-
-## Creating Scripts with uv
-
-```bash
-# Create new script with metadata
-uv init --script myscript.py
-
-# Add dependency to existing script
-uv add --script myscript.py requests
-
-# Remove dependency from script
-uv remove --script myscript.py requests
-```
-
-## Shebang Options
-
-### Basic (requires uv in PATH)
-
-```python
-#!/usr/bin/env -S uv run --script
-```
-
-### With specific Python version
-
-```python
-#!/usr/bin/env -S uv run --python 3.12 --script
-```
-
-### Quiet mode (suppress uv output)
-
-```python
-#!/usr/bin/env -S uv run --quiet --script
-```
-
-## Examples by Use Case
-
-### Data Processing Script
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["pandas", "openpyxl"]
-# ///
-
-import pandas as pd
-import sys
-
-df = pd.read_excel(sys.argv[1])
-print(df.describe())
-```
-
-### Web Scraping Script
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["httpx", "beautifulsoup4", "lxml"]
-# ///
-
-import httpx
-from bs4 import BeautifulSoup
-
-response = httpx.get("https://example.com")
-soup = BeautifulSoup(response.text, "lxml")
-print(soup.title.string)
-```
-
-### CLI Tool Script
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["typer", "rich"]
-# ///
-
-import typer
-from rich import print
-
-app = typer.Typer()
-
-@app.command()
-def greet(name: str):
-    print(f"[green]Hello, {name}![/green]")
-
-if __name__ == "__main__":
-    app()
-```
-
-### Async Script
-
-```python
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["httpx"]
-# ///
-
-import asyncio
-import httpx
-
-async def main():
-    async with httpx.AsyncClient() as client:
-        urls = ["https://api1.example.com", "https://api2.example.com"]
-        tasks = [client.get(url) for url in urls]
-        responses = await asyncio.gather(*tasks)
-        for r in responses:
-            print(r.status_code)
-
-asyncio.run(main())
-```
-
-## Best Practices
-
-1. **Always specify `requires-python`** - Ensures compatibility
-2. **Pin major versions for Python** - Use `>=3.11` not `==3.11`
-3. **Omit version constraints for dependencies** - Use `uv add --script` to add dependencies; let uv select versions
-4. **Keep scripts focused** - One script, one purpose
-5. **Add docstring** - Document what the script does
-6. **Use type hints** - Improves readability and catches errors
-
-## Limitations
-
-- No support for dependency groups
-- No support for editable installs
-- No support for local dependencies (use relative imports)
-- No lockfile (versions may vary between runs)
-
-For projects needing these features, use a full `pyproject.toml` setup instead.

package/skills_ref/modern-python/skills/modern-python/references/prek.md

@@ -1,211 +0,0 @@
-# prek: Fast Pre-commit Hooks
-
-[prek](https://github.com/j178/prek) is a fast, Rust-native drop-in replacement for pre-commit. It uses the same `.pre-commit-config.yaml` format and is fully compatible with existing configurations.
-
-## Why prek over pre-commit?
-
-| Feature | prek | pre-commit |
-|---------|------|------------|
-| Speed | ~7x faster hook installation | Slower |
-| Dependencies | Single binary, no runtime needed | Requires Python |
-| Disk usage | Shared toolchains between hooks | Isolated environments |
-| Parallelism | Parallel repo cloning and hook execution | Sequential |
-| Python management | Uses uv automatically | Manual Python setup |
-| Monorepo support | Built-in workspace mode | Not supported |
-
-**Already using prek:** CPython, Apache Airflow, FastAPI, Ruff, Home Assistant, and [many more](https://github.com/j178/prek#who-is-using-prek).
-
-## Installation
-
-See [security-setup.md](./security-setup.md#tool-installation) for installation options.
-
-## Quick Start
-
-### For Existing pre-commit Users
-
-prek is fully compatible with `.pre-commit-config.yaml`. Just replace commands:
-
-```bash
-# Instead of: pre-commit install
-prek install
-
-# Instead of: pre-commit run --all-files
-prek run --all-files
-
-# Instead of: pre-commit autoupdate
-prek auto-update
-```
-
-### New Setup
-
-1. Create `.pre-commit-config.yaml`:
-
-```yaml
-repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: <latest>  # https://github.com/astral-sh/ruff-pre-commit/releases
-    hooks:
-      - id: ruff
-        args: [--fix]
-      - id: ruff-format
-```
-
-2. Install and run:
-
-```bash
-# Install git hooks
-prek install
-
-# Run manually on all files
-prek run --all-files
-
-# Run specific hook
-prek run ruff
-```
-
-## Configuration
-
-For a complete, copy-paste-ready configuration, see [templates/pre-commit-config.yaml](../templates/pre-commit-config.yaml).
-
-### Recommended `.pre-commit-config.yaml`
-
-> **Note:** Versions shown as `<latest>` are placeholders. Always check the linked releases for current stable versions before use.
-
-```yaml
-# See https://pre-commit.com for more information
-default_language_version:
-  python: python3.12
-
-repos:
-  # Ruff - linting and formatting
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: <latest>  # https://github.com/astral-sh/ruff-pre-commit/releases
-    hooks:
-      - id: ruff
-        args: [--fix]
-      - id: ruff-format
-
-  # General file checks (prek builtin - faster, no external deps)
-  - repo: builtin
-    hooks:
-      - id: trailing-whitespace
-      - id: end-of-file-fixer
-      - id: check-yaml
-      - id: check-merge-conflict
-
-  # Security hooks - see security-setup.md for detailed guidance
-  # Shell script linting
-  - repo: https://github.com/koalaman/shellcheck-precommit
-    rev: <latest>  # https://github.com/koalaman/shellcheck-precommit/tags
-    hooks:
-      - id: shellcheck
-        args: [--severity=error]
-
-  # Secret detection
-  - repo: https://github.com/Yelp/detect-secrets
-    rev: <latest>  # https://github.com/Yelp/detect-secrets/releases
-    hooks:
-      - id: detect-secrets
-        args: [--baseline, .secrets.baseline]
-
-  # GitHub Actions linting
-  - repo: https://github.com/rhysd/actionlint
-    rev: <latest>  # https://github.com/rhysd/actionlint/releases
-    hooks:
-      - id: actionlint
-
-  # GitHub Actions security audit
-  - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: <latest>  # https://github.com/zizmorcore/zizmor-pre-commit/releases
-    hooks:
-      - id: zizmor
-        args: [--persona=regular, --min-severity=medium, --min-confidence=medium]
-```
-
-See [security-setup.md](./security-setup.md) for detailed guidance on each security hook.
-
-### Using Built-in Hooks
-
-prek includes Rust-native implementations of common hooks for extra speed:
-
-```yaml
-repos:
-  - repo: builtin
-    hooks:
-      - id: trailing-whitespace
-      - id: end-of-file-fixer
-      - id: check-yaml
-      - id: check-json
-      - id: check-toml
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `prek install` | Install git hooks |
-| `prek uninstall` | Remove git hooks |
-| `prek run` | Run hooks on staged files |
-| `prek run --all-files` | Run on all files |
-| `prek run --last-commit` | Run on last commit's files |
-| `prek run HOOK [HOOK...]` | Run specific hook(s) |
-| `prek run -d src/` | Run on files in directory |
-| `prek auto-update` | Update hook versions |
-| `prek list` | List configured hooks |
-| `prek clean` | Remove cached environments |
-
-## CI Configuration
-
-### GitHub Actions
-
-```yaml
-name: Pre-commit
-on: [push, pull_request]
-
-jobs:
-  prek:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@<sha>  # <latest> https://github.com/actions/checkout/releases
-      - uses: j178/prek-action@<sha>  # <latest> https://github.com/j178/prek-action/releases
-```
-
-Or manually:
-
-```yaml
-- name: Install prek
-  run: uv tool install prek
-
-- name: Run hooks
-  run: prek run --all-files
-```
-
-## Makefile Integration
-
-```makefile
-.PHONY: hooks hooks-install
-
-hooks:
-	prek run --all-files
-
-hooks-install:
-	prek install
-```
-
-## Migration from pre-commit
-
-1. Install prek: `uv tool install prek`
-2. Remove pre-commit: `pip uninstall pre-commit` or `uv tool uninstall pre-commit`
-3. Re-install hooks: `prek install`
-4. (Optional) Clean old environments: `rm -rf ~/.cache/pre-commit`
-
-Your existing `.pre-commit-config.yaml` works unchanged.
-
-## Best Practices
-
-1. **Use `prek run --all-files` in CI** - Ensures all files are checked, not just changed ones
-2. **Pin hook versions** - Use specific `rev` values, not branches
-3. **Use `--cooldown-days` for auto-update** - Mitigates supply chain attacks: `prek auto-update --cooldown-days 7`
-4. **Prefer built-in hooks** - Use `repo: builtin` for common checks (faster, offline)
-5. **Run hooks before commit** - `prek install` sets this up automatically
-6. **Initialize detect-secrets baseline** - Run `detect-secrets scan > .secrets.baseline` before first commit

package/skills_ref/modern-python/skills/modern-python/references/pyproject.md

@@ -1,254 +0,0 @@
-# pyproject.toml Configuration Reference
-
-Complete reference for configuring `pyproject.toml` for modern Python projects.
-
-**Important**: Always use `uv add` and `uv remove` to manage dependencies. Do not edit the `dependencies` or `dependency-groups` sections directly.
-
-## Complete Example
-
-```toml
-[project]
-name = "myproject"
-version = "0.1.0"
-description = "A modern Python project"
-readme = "README.md"
-license = "MIT"
-requires-python = ">=3.11"
-authors = [
-    { name = "Your Name", email = "you@example.com" }
-]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-]
-dependencies = [
-    "requests",
-    "rich",
-]
-
-[project.optional-dependencies]
-# Use for optional features users can install
-cli = ["typer"]
-
-[project.scripts]
-myproject = "myproject.cli:main"
-
-[project.urls]
-Homepage = "https://github.com/org/myproject"
-Documentation = "https://myproject.readthedocs.io"
-Repository = "https://github.com/org/myproject"
-
-[build-system]
-requires = ["uv_build>=0.9,<1"]  # Use latest 0.x; check https://pypi.org/project/uv-build/
-build-backend = "uv_build"
-
-[dependency-groups]
-dev = ["ruff", "ty"]
-test = ["pytest", "pytest-cov", "hypothesis"]
-docs = ["sphinx", "myst-parser"]
-
-[tool.uv]
-default-groups = ["dev", "test"]
-
-[tool.ruff]
-line-length = 100
-target-version = "py311"
-src = ["src"]
-
-[tool.ruff.lint]
-select = ["ALL"]
-ignore = [
-    "D",        # pydocstyle (enable selectively)
-    "COM812",   # trailing comma (conflicts with formatter)
-    "ISC001",   # implicit string concat (conflicts with formatter)
-]
-
-[tool.ruff.lint.per-file-ignores]
-"tests/**/*.py" = [
-    "S101",     # assert allowed in tests
-    "PLR2004",  # magic values allowed in tests
-    "ANN",      # annotations optional in tests
-]
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
-docstring-code-format = true
-
-[tool.pytest]
-testpaths = ["tests"]
-pythonpath = ["src"]
-addopts = [
-    "--cov=myproject",
-    "--cov-report=term-missing",
-    "--cov-fail-under=80",
-]
-
-[tool.coverage.run]
-branch = true
-source = ["src/myproject"]
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "if TYPE_CHECKING:",
-    "if __name__ == .__main__.:",
-]
-```
-
-## Section Reference
-
-### [project]
-
-Core project metadata following PEP 621.
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Package name (lowercase, hyphens) |
-| `version` | Yes | Semantic version |
-| `description` | No | One-line description |
-| `readme` | No | Path to README file |
-| `license` | No | SPDX license identifier |
-| `requires-python` | Recommended | Python version constraint |
-| `authors` | No | List of author dicts |
-| `dependencies` | No | Runtime dependencies |
-
-### [project.optional-dependencies]
-
-**Rarely needed.** Only use for optional *runtime* features that end users install:
-
-```toml
-[project.optional-dependencies]
-# User installs with: uv add myproject[postgres]
-postgres = ["psycopg2"]
-```
-
-**Do NOT use for dev tools**—use `[dependency-groups]` instead.
-
-### [project.scripts]
-
-Console entry points:
-
-```toml
-[project.scripts]
-myproject = "myproject.cli:main"
-myproject-serve = "myproject.server:run"
-```
-
-### [build-system]
-
-Build backend configuration. Use `uv_build` for most projects:
-
-```toml
-[build-system]
-requires = ["uv_build>=0.9,<1"]  # Use latest 0.x; check https://pypi.org/project/uv-build/
-build-backend = "uv_build"
-```
-
-`uv_build` is simpler and sufficient for most use cases. Use static versioning in `[project] version` rather than VCS-aware dynamic versioning.
-
-For flat layout (no `src/` directory), configure the module root:
-
-```toml
-[tool.uv.build-backend]
-module-root = ""
-```
-
-> **Note:** These tools evolve rapidly. Prefer `>=X.Y,<X+1` constraints to automatically get newer releases within the same major version.
-
-### [dependency-groups]
-
-Development dependencies (PEP 735). Unlike optional-dependencies, these are NOT installed by users:
-
-```toml
-[dependency-groups]
-dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
-lint = ["ruff", "ty"]
-test = ["pytest", "pytest-cov"]
-audit = ["pip-audit"]
-docs = ["sphinx", "myst-parser"]
-```
-
-Install with: `uv sync --group dev --group test`
-
-### [tool.uv]
-
-uv-specific configuration:
-
-```toml
-[tool.uv]
-# Default groups to install with `uv sync`
-default-groups = ["dev", "test"]
-
-# Python version management
-python-preference = "managed"
-```
-
-## Version Specifiers
-
-| Specifier | Meaning |
-|-----------|---------|
-| `>=1.0` | At least version 1.0 |
-| `>=1.0,<2.0` | Version 1.x only |
-| `~=1.4` | Compatible release (>=1.4, <2.0) |
-| `==1.4.*` | Any 1.4.x version |
-
-## uv.lock Handling
-
-| Project Type | uv.lock in Git? | Why |
-|--------------|-----------------|-----|
-| Application | ✅ Commit | Reproducible deploys |
-| Library | ❌ .gitignore | Users resolve their own deps |
-
-## Common Patterns
-
-### Library Package
-
-```toml
-[project]
-dependencies = []  # Minimal runtime deps
-
-[project.optional-dependencies]
-# Optional runtime features (user installs with mylib[async])
-async = ["httpx"]
-
-[dependency-groups]
-dev = ["ruff", "ty"]
-test = ["pytest", "pytest-cov"]
-```
-
-### Application Package
-
-```toml
-[project]
-dependencies = [
-    "fastapi",
-    "uvicorn",
-    "sqlalchemy",
-]
-
-[project.scripts]
-myapp = "myapp.main:run"
-
-[dependency-groups]
-dev = ["ruff", "ty", "pytest"]
-```
-
-### CLI Tool
-
-```toml
-[project]
-dependencies = [
-    "typer",
-    "rich",
-]
-
-[project.scripts]
-mytool = "mytool.cli:app"
-
-[dependency-groups]
-dev = ["ruff", "ty", "pytest"]
-```