Skip to content

chore: replace [tool.setuptools] script-files with stackvox install-helper#18

Merged
StuBehan merged 1 commit into
mainfrom
chore/replace-script-files
Apr 30, 2026
Merged

chore: replace [tool.setuptools] script-files with stackvox install-helper#18
StuBehan merged 1 commit into
mainfrom
chore/replace-script-files

Conversation

@StuBehan
Copy link
Copy Markdown
Collaborator

Summary

Drops the deprecated `[tool.setuptools] script-files` mechanism. The bash helper now ships as package data and is copied onto PATH explicitly via a new `stackvox install-helper` subcommand.

Why

`script-files` is setuptools-specific, marked as discouraged in the setuptools docs, has no PEP 621 equivalent, and doesn't round-trip through hatchling / uv. Removing it now unblocks any future build-backend migration and removes a future deprecation warning.

The naive replacement — wrap the bash helper in a Python entry point — would have added ~150–300ms of interpreter startup to every `stackvox-say` call, defeating the whole reason the helper exists (~13ms IPC round-trip from shell hooks). So instead the install step becomes explicit, opt-in, and the helper stays pure bash.

Install flow

pipx install stackvox       # `stackvox` CLI on PATH
stackvox install-helper     # copies bash helper to ~/.local/bin (opt-in)
stackvox-say "fast"         # ~13ms IPC, same as before

`--prefix DIR` overrides the destination. When the chosen prefix isn't on PATH the command prints a hint with the absolute path so users aren't left guessing why `stackvox-say` "doesn't work after install".

Changes

  • Removed: `[tool.setuptools] script-files = ["bin/stackvox-say"]` and the `bin/` directory.
  • Added: `stackvox/data/stackvox-say` (the same bash file, now as package data) and `stackvox/data/stackvox-say` to `[tool.setuptools.package-data]`.
  • Added: `stackvox install-helper [--prefix DIR]` subcommand. Lives in `cli.py`, uses `importlib.resources.files` to locate the helper from the wheel.
  • Added: `install-helper` to bash completion (with `--prefix DIR` directory completion).
  • Tests: `TestCmdInstallHelper` — copy + exec bit, missing-prefix-dir creation, on-/off-PATH branches.
  • Docs: README install section explains the optional helper step. Skip-if-you-don't-need-shell-hooks language so users don't think it's mandatory.

Verification

  • `python -m build` produces a wheel containing `stackvox/data/stackvox-say` (verified via `unzip -l`) — no `/scripts/` entry, which is what `script-files` would have produced.
  • `stackvox install-helper --prefix /tmp/test-bin` smoke-tested locally: file copies, exec bit set, off-PATH warning fires.
  • 73 tests passing locally; ruff + mypy clean.

Test plan

  • CI passes (lint, format, mypy, tests 3.10–3.13 Ubuntu, test-macos py3.12, PR-title, commit lint).
  • On a fresh venv: `pip install dist/stackvox-*.whl && stackvox install-helper --prefix /tmp/test` produces an executable `stackvox-say`.
  • CHANGELOG entry will be release-please-generated under "Chores" on the next release PR.

Migration note for users on 0.2.x

After upgrading to 0.3.0, the previously-installed `stackvox-say` (placed by setuptools' `script-files` into the venv's `bin/` dir) is no longer refreshed automatically. New installs need to run `stackvox install-helper` once. We'll call this out explicitly in the release notes.

…elper

`script-files` is setuptools-specific, has no PEP 621 equivalent, and
doesn't round-trip through hatchling/uv if we ever migrate build
backends. The setuptools docs already mark it as discouraged.

This drops it. The bash helper now ships as package data
(`stackvox/data/stackvox-say`) and a new `stackvox install-helper`
subcommand copies it onto PATH:

    pipx install stackvox
    stackvox install-helper          # copies bash helper to ~/.local/bin
    stackvox-say "now use the fast helper"

`--prefix DIR` overrides the destination; if the chosen prefix isn't
on PATH the command emits a hint pointing at the absolute path. The
step is opt-in — users who only need the Python `stackvox say` client
can skip it.

Trade-off: one extra command after install. Reward: the helper keeps
its bash-only, ~13ms-IPC latency (a Python entry point would have
added ~150ms of interpreter startup, defeating the design).

 - tests/test_cli.py: TestCmdInstallHelper covers the copy, the
   exec-bit, prefix creation, and the on-/off-PATH branches.
 - README install section explains the opt-in helper step.
 - bin/ directory removed; helper now lives at stackvox/data/stackvox-say.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@StuBehan StuBehan merged commit d837f26 into main Apr 30, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant