# Python Gen Tarball

> Use whenever the user changes any source under `packages/proto-python-gen/` (Python source, `setup.sh`, `requirements.txt`, `bin/`) or edits `scripts/pip-config.sh` (which gets bundled). The Python proto generator ships as a versioned tarball that Hermit consumes; if source changes but the tarball isn't rebuilt and committed, downstream consumers silently use the stale generator.

- Skill: `block/python-gen-tarball` (Agent Skill)
- Install (CLI): `npx skillmds@latest add block/python-gen-tarball`
- Raw SKILL.md: https://api.skillmd.com/api/skills/block/python-gen-tarball/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: block (https://skillmd.com/u/block)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/block/python-gen-tarball

---


# python-gen-tarball

The tarball is the distribution unit. Local edits run against the venv, so
tests pass — but Hermit-bootstrapped environments and CI extract the
committed `proto-python-gen-<version>.tar.gz` and keep using the old code
until it's rebuilt. This is a quiet failure mode that's easy to miss.

## What to do

1. Decide whether to bump `version` in `packages/proto-python-gen/justfile`:
   - Behavior change or new feature → bump.
   - Pure refactor → optional. Ask if unclear.
2. Build:
   ```
   cd packages/proto-python-gen && just package
   ```
   Produces `proto-python-gen-<version>.tar.gz`.
3. Stage the tarball alongside the source change. A source-only commit will
   fail to bootstrap fresh environments.
4. If the version was bumped, search for hard-coded references and update:
   ```
   rg "proto-python-gen-[0-9]" -g '!*.tar.gz'
   ```

## What to avoid

- `just gen` does not rebuild this tarball. Only `just package` inside
  `packages/proto-python-gen/` does.