mirror of
https://github.com/trailofbits/skills.git
synced 2026-09-14 14:28:48 +08:00
Dan Guido
c199e0cc7d
* Narrow the modern-python shims to the commands uv run replaces Closes #207. The shims sit on PATH, so they intercept every subprocess any tool spawns, not just what Claude types. Two of the intercepted invocations were not package management at all, and blocking them broke real tooling. `uv pip` now passes through when it carries --project, --directory or --target. Those say a tool is building an environment it owns, where `uv add` is not the available advice: prek installs every hook with `uv pip install --project / --directory <cache>`, so the refusal made `git commit` fail in any repo whose hooks need a Python environment. A bare `uv pip install requests` is still refused. `python -c`, `python -m <module>` and `python -` now reach the real interpreter. None of them resolves a script against a project's dependencies, which is what `uv run` exists to do, and `uv run python3 -` is not a drop-in replacement inside a pipeline. `python -m pip` stays intercepted, as do bare `python` and `python script.py`. Passing anything through is new for the python shim, which previously ended every branch in exit 1, so it gains the same skip-my-own-dir PATH walk the uv shim already had. That walk now uses parameter expansion rather than basename, because the one case where it must report failure is a PATH holding nothing but the shim, where shelling out to coreutils fails first with a confusing error. Verified by A/B on the two symptoms #207 reports, running each suite against the old shim and the new one: - zeroize-audit's rust-regression smoke test: FAILED at line 72 before, "Rust regression smoke checks passed." after. - prek hook installation from a cold cache: refused before, "check json Passed" after. bats goes from 19 cases to 38. Five python cases inverted rather than being deleted: the ones asserting that -c and -m are refused now assert they run. AGENTS.md's note on `make shell-suites` is corrected rather than removed — the #207 interceptions are gone, but the target still fails because variant-analysis invokes `python3 <script>.py`, which the shim intercepts by design. That one belongs to variant-analysis. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Decide on the mode selector, not on argument position Two gaps in the narrowing, both from review. `uv pip install --help` documents `-t, --target <TARGET>`, so the short form has to be exempt alongside the long one. Without it the same tool-managed install was allowed or refused depending on spelling. The python shim read only $1 to find the mode selector, so `python -u -c 'code'` was refused while `python -c 'code'` ran, even though they are the same invocation. It now steps over interpreter flags to find the selector, giving `-W`, `-X` and `--check-hash-based-pycs` the two slots they take. `-u -m pip` is still refused, and so is `-u script.py`: a script path is what `uv run` replaces regardless of what precedes it. bats 38 -> 43. Both #207 regressions re-verified after the restructure: zeroize-audit's smoke test passes and prek installs hooks from a cold cache. Not fixed here, deliberately: `uv --no-progress pip install requests` still slips past the refusal, because the subcommand check reads $1 as well. Parsing that correctly means knowing which uv global flags take a value, and getting it wrong would refuse a command that works today. The failure mode is a missed nudge rather than a breakage — the real uv runs and behaves correctly — so it does not belong in a change whose purpose is to refuse less. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# Modern Python
|
|
|
|
Modern Python tooling and best practices using uv, ruff, ty, and pytest. Based on patterns from [trailofbits/cookiecutter-python](https://github.com/trailofbits/cookiecutter-python).
|
|
|
|
**Author:** William Tan
|
|
|
|
## When to Use
|
|
|
|
- Setting up a new Python project with modern, fast tooling
|
|
- Replacing pip/virtualenv with uv for faster dependency management
|
|
- Replacing flake8/black/isort with ruff for unified linting and formatting
|
|
- Replacing mypy with ty for faster type checking
|
|
- Adding pre-commit hooks and security scanning to an existing project
|
|
|
|
## What It Covers
|
|
|
|
**Core Tools:**
|
|
- **uv** - Package/dependency management (replaces pip, virtualenv, pip-tools, pipx, pyenv)
|
|
- **ruff** - Linting and formatting (replaces flake8, black, isort, pyupgrade)
|
|
- **ty** - Type checking (replaces mypy, pyright)
|
|
- **pytest** - Testing with coverage enforcement
|
|
- **prek** - Pre-commit hooks (replaces pre-commit)
|
|
|
|
**Security Tools:**
|
|
- **shellcheck** - Shell script linting
|
|
- **detect-secrets** - Secret detection in commits
|
|
- **actionlint** - GitHub Actions syntax validation
|
|
- **zizmor** - GitHub Actions security audit
|
|
- **pip-audit** - Dependency vulnerability scanning
|
|
- **Dependabot** - Automated dependency updates with supply chain protection
|
|
|
|
**Standards:**
|
|
- **pyproject.toml** - Single configuration file with dependency groups (PEP 735)
|
|
- **PEP 723** - Inline script metadata for single-file scripts
|
|
- **src/ layout** - Standard package structure
|
|
- **Python 3.11+** - Minimum version requirement
|
|
|
|
## Hook: Legacy Command Interception
|
|
|
|
This plugin includes a `SessionStart` hook that prepends PATH shims for `python`, `pip`, `pipx`, and `uv`. When Claude runs a bare `python`, `pip`, or `pipx` command, the shell resolves to the shim, which prints an error with the correct `uv` alternative and exits non-zero. The suggested alternative always uses the exact command name `python` (never `python3`) so it also works outside a project; see the header comment in [`hooks/shims/python`](hooks/shims/python) for the full rationale.
|
|
|
|
The shims sit on PATH, so they see every subprocess a tool spawns, not only what Claude types. That is why the intercepted set is narrow: it covers the invocations `uv run` and `uv add` genuinely replace, and passes the rest through to the real binary. `python -c`, `python -m <module>` and `python -` read a program from the command line, an installed module, or stdin, so none of them resolves a script against a project's dependencies; `uv pip` carrying `--project`, `--directory` or `--target` is a tool building an environment it owns. Redirecting those broke real tooling, including `prek` hook installation and any script piping into `python3 -` ([#207](https://github.com/trailofbits/skills/issues/207)).
|
|
|
|
| Intercepted Command | Suggested Alternative |
|
|
|---------------------|----------------------|
|
|
| `python ...` | `uv run python ...` |
|
|
| `python -m pip` | `uv add`/`uv remove` |
|
|
| `pip install pkg` | `uv add pkg` or `uv run --with pkg` |
|
|
| `pip uninstall pkg` | `uv remove pkg` |
|
|
| `pip freeze` | `uv export` |
|
|
| `uv pip ...` | `uv add`/`uv remove`/`uv sync` |
|
|
| *(passed through)* | `python -c`, `python -m <module>`, `python -`, and `uv pip` with `--project`, `--directory` or `--target` |
|
|
| `pipx install <pkg>` | `uv tool install <pkg>` |
|
|
| `pipx run <pkg>` | `uvx <pkg>` |
|
|
| `pipx uninstall <pkg>` | `uv tool uninstall <pkg>` |
|
|
| `pipx upgrade <pkg>` | `uv tool upgrade <pkg>` |
|
|
| `pipx upgrade-all` | `uv tool upgrade --all` |
|
|
| `pipx ensurepath` | `uv tool update-shell` |
|
|
| `pipx inject <pkg> <dep>` | `uv tool install --with <dep> <pkg>` |
|
|
| `pipx list` | `uv tool list` |
|
|
|
|
Commands like `grep python`, `which python`, and `cat python.txt` work normally because `python` is a shell argument, not the command being invoked.
|
|
|
|
## Installation
|
|
|
|
```
|
|
/plugin install trailofbits/skills/plugins/modern-python
|
|
```
|