<!-- skill: Modern Python Packaging | version: 1.0.0 | description: Ship modern Python with uv, ruff, hatch builds, lockfiles and pre-commit | category: Python & Data -->
## Instructions
- Use `uv` as the single tool: `uv init`, `uv add`, `uv sync`, `uv run` — commit `uv.lock`, never hand-edit it.
- Standard layout: `src/<pkg>/` + `tests/` + `pyproject.toml` (hatchling); `requires-python = '>=3.10'`, version in one place.
- Lint+format with ruff only: `ruff check` + `ruff format`; configure line-length 100, target-version, select `E,F,I,UP,B`.
- Typecheck the public surface with `mypy` or `pyright` in strict-ish mode; keep `py.typed` marker in the package.
- Pre-commit gates: ruff, ruff-format, end-of-file/trailing-whitespace, `check-uv-lock` — run on every commit via hooks.
- Pin for apps (`uv.lock` committed), range for libraries (`dependencies = ['requests>=2.31']`); extras for optional deps.
- Build wheels cleanly: `uv build` (hatchling backend); verify with `twine check dist/*` and test-install in a fresh venv.
- Publish safely: TestPyPI first (`uv publish --index testpypi`), tag `vX.Y.Z`, GitHub Release with changelog, then PyPI.
- Manage Python versions with `uv python pin 3.12` + `.python-version` file; CI matrix tests 3.10–3.13.
- Document the dev loop in README: `uv sync`, `uv run pytest`, `uv run ruff check`, `uv build` — four commands max.
- Complement python-packaging skill: basics there, this file is the modern uv+ruff+hatch+lockfile production path.
- Never commit `.venv/`, `dist/`, `*.egg-info`, or secrets; ship `LICENSE`, `README.md`, `CHANGELOG.md` in every release.

## Examples
- CLI tool → `uv init --package`, `uv add click rich`, ruff clean, `uv build` wheel, TestPyPI then PyPI publish.
- Library → src layout, versioned API, extras `[pandas]`, mypy typed, pre-commit gates, changelog per release.
- Team app → pinned `uv.lock`, `.python-version`, CI runs sync+test+lint, Docker copies lockfile for repro builds.

## Workflows
1. Init: `uv init --package myapp && uv python pin 3.12 && uv add <deps>`.
2. Configure `pyproject.toml`: hatchling build, ruff rules, pytest/mypy sections, scripts entry points.
3. Install hooks: `pre-commit install`, verify `uv run pre-commit run --all-files` is green.
4. Develop: `uv sync` → code → `uv run pytest -q` → `uv run ruff check . && uv run ruff format --check .`.
5. Release: bump version, `uv build`, TestPyPI smoke install, tag, GitHub Release, `uv publish`.

## Templates
```toml
# pyproject.toml — hatchling + ruff + pytest + mypy in one file
[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = ["click>=8.1", "rich>=13.0"]
[project.scripts]
myapp = "myapp.cli:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]
[tool.ruff]
line-length = 100
target-version = "py310"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]
[tool.pytest.ini_options]
testpaths = ["tests"]
```
```yaml
# .pre-commit-config.yaml — ruff + hygiene gates on every commit
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: end-of-file-fixer
      - id: trailing-whitespace
      - id: check-yaml
```

## Tools
- Core: install `uv` (curl installer), `pip install pre-commit twine build`.
- Daily: `uv sync`, `uv add/remove`, `uv run <cmd>`, `uv build`, `uv publish`.
- SARAH Run executes `uv sync && uv run pytest -q && uv run ruff check .`.

## Advanced
- Lockfile strategy: `uv lock --upgrade-package requests` for surgical bumps; `uv sync --frozen` in CI for repro.
- Hatch versioning: `hatch-vcs` for tag-derived versions, or static `version=`; never both, never hardcoded in two places.
- Monorepo: `uv workspace` members share one lockfile; `[tool.uv.sources]` maps local path deps.
- Docker: `COPY pyproject.toml uv.lock .` → `uv sync --frozen --no-dev` before copying `src/` for layer caching.
- Publishing: trusted-publisher (OIDC) over API tokens; `uv publish --index pypi`, attestations on for supply chain.
- Troubleshooting: resolver conflict → `uv lock --refresh`; stale venv → `rm -rf .venv && uv sync`; ruff vs black fights → ruff only.

## Documentation
- uv guide: https://docs.astral.sh/uv/
- Ruff: https://docs.astral.sh/ruff/
- Hatch: https://hatch.pypa.io/