python

What this skill does

# Python

## Core Posture

Use uv as the default workflow for Python projects, standalone scripts, dependency management, quality checks, and package release. Prefer the repository's existing configuration and documented commands over introducing new tooling.

## Mode Selection

- Choose project mode when the work has a `pyproject.toml`, shared package code, or lockfile.
- Treat a brand-new repository created with `uv init` as project mode.
- Choose standalone-script mode when the work is a single file, stdin snippet, or ad hoc invocation that should not become a full project.
- Treat a script inside a project as project mode when it imports local package code.
- Use `--no-project` only when a script must ignore the surrounding project.

## Project Workflow

1. Inspect `pyproject.toml`, lockfiles, repository docs, and existing test/tooling choices before changing dependencies or commands.
2. For a brand-new project, run `uv init <name>`, then install the default dev toolchain with `uv add --dev ruff ty pytest pytest-cov`.
3. Use pytest as the default test framework for new projects: function-based `tests/test_*.py` files with plain `assert`.
4. Add dependencies with `uv add`; remove them with `uv remove`; reconcile external dependency changes with `uv sync`.
5. Run project Python, tests, and tools through `uv run` unless the repository provides a documented wrapper command; for pytest, default to an explicit `tests` target when the project does not document another test location.
6. Run the repository quality gate before finalizing dependency or code changes.

## Standalone Script Workflow

1. Decide whether the script should use project dependencies, one-off `--with` dependencies, or inline metadata.
2. Use plain `uv run script.py` when no extra dependencies are needed.
3. Use `uv run --with ... script.py` for disposable per-invocation dependencies.
4. Use `uv init --script` and `uv add --script` when dependencies should live with the script.
5. Put `--no-project` before the script name, and never use it for a script that imports local package code.
6. Use `uv run --python <version>` or `requires-python` in metadata when the script needs a specific Python version.
7. Read `references/scripts.md` for stdin, heredoc, shebang, alternate indexes, Windows `.pyw`, locking, and reproducibility details.

## Non-Negotiable Rules

- Manage dependencies with `uv add`, `uv remove`, and `uv sync`; do not use `pip install` to mutate a project environment.
- Run Python, pytest, scripts, and Python tools with `uv run` unless a repository command wraps them; when no project-specific pytest target is documented, include `tests` explicitly (for example, `uv run pytest tests`) rather than bare `uv run pytest`.
- Follow existing repository choices; do not migrate test frameworks, hook runners, or tool configuration unless asked.
- For a brand-new project, immediately add `ruff`, `ty`, `pytest`, and `pytest-cov`; do not start with `unittest`, `unittest.TestCase`, or class-based `Test*` suites.
- Do not create a `pyproject.toml` only to run a one-file script.
- Treat `uv run --with` as disposable; use inline metadata when the script should be shared or reused.
- Build release artifacts with `uv build --no-sources` so local `[tool.uv.sources]` overrides do not leak into release output.
- Test installs from the built wheel or published artifact, not only from the source checkout.

## Quality Gate Priority

Use this order before finalizing code, dependency, or packaging changes:

1. The repository's documented aggregate gate.
2. `prek run -a` when the repo uses prek.
3. The documented `pre-commit` command when the repo uses pre-commit and provides no prek path.
4. Individual `uv run ...` commands only when no aggregate gate exists or when narrowing failures.

Do not introduce or switch hook runners only for verification. Read `references/quality.md` for command details, coverage, CI examples, and fallback checks.

## Release Workflow

1. Run the repository quality gate.
2. Build artifacts in `dist/` with `uv build --no-sources`.
3. Inspect wheel and sdist contents.
4. Test install from the built wheel or published artifact in a fresh uv-managed invocation.
5. Read `references/packaging.md` for publish commands, Test PyPI flow, and artifact inspection details.

## Common Mistakes

- Treating a one-file script as project work when inline metadata or `--no-project` would be smaller and clearer.
- Using `--no-project` for a script that imports local package code.
- Keeping reusable script dependencies only in `uv run --with ...` shell history instead of the script metadata.
- Starting a brand-new project with `unittest` or without the default dev toolchain.
- Running tools outside uv.
- Publishing before verifying artifacts.

## References

- `references/quality.md` - Full commands, CI examples, coverage, prek, and pre-commit fallback usage.
- `references/packaging.md` - Build, inspect, and publish details.
- `references/scripts.md` - Standalone script patterns, inline metadata, locking, and special cases.