fastship

Local-first release CLI tools: ship_bump, ship_pypi, ship_release_gh

View the Project on GitHub AnswerDotAI/fastship

fastship

Tiny, local-first release tools for modern Python projects.

fastship gives you the same workflow feel as the nbdev nbdev-bump-version, release-pypi, and release-gh commands — but for plain (non-notebook) Python projects.

Install

pip install fastship

Quick start

Create a new project:

ship-new my-project
cd my-project
pip install -e .[dev]

This creates a complete project with pyproject.toml, __version__, LICENSE, README, and everything wired for fastship.

Commands

ship-bump

Bump a version part (0=major, 1=minor, 2=patch). For Rust projects (a Cargo.toml next to pyproject.toml) it bumps [package].version in Cargo.toml and runs maturin develop; otherwise it rewrites __version__ in your package __init__.py:

ship-bump --part 2
ship-bump --part 1
ship-bump --part 0

Decrement instead:

ship-bump --part 2 --unbump

ship-pypi

Build + upload to PyPI:

ship-pypi

Upload to a named repository in ~/.pypirc (e.g. testpypi):

ship-pypi --repository testpypi

Quiet mode:

ship-pypi --quiet

PyO3 / maturin projects

Fastship can also handle the repeated local tooling for PyO3 projects that use maturin and need Rust CLI binaries bundled into wheel scripts.

Create a new PyO3 project:

ship-rs-new my-project
cd my-project
pip install -e .[dev]
ship-rs-test

Use Cargo.toml as the version source:

[project]
name = "my_project"
dynamic = ["version"]

Commands:

ship-rs-new my-project  # create a new maturin/PyO3 project
ship-rs-init            # configure an existing maturin/PyO3 project
ship-rs-build            # maturin build --release -o dist
ship-rs-test             # build/install wheel, pytest -q
ship-bump                # bump Cargo.toml version, then refresh the local editable install
ship-rs-release          # tag v<version> and push branch + tags

ship-rs-init must be run from an existing maturin project with Cargo.toml. It sets [project].dynamic = ["version"], removes [project].version, and exposes __version__ from CARGO_PKG_VERSION when it finds the PyO3 module.

Generated CI runs the tests, then builds wheels with maturin-action across an OS matrix (manylinux: auto on Linux) and publishes to GitHub Releases and PyPI on v* tags. Any CLI tools are Python console scripts declared in [project.scripts]; there are no native Rust binaries to build.

ship-pr

Create a PR from uncommitted or unpushed work, merge it immediately, and clean up:

ship-pr "Add new feature"
ship-pr "Fix bug" --label bug
ship-pr "Breaking change" --label breaking

This command:

  1. Creates a new branch from your current work
  2. Commits any uncommitted changes (using the title as commit message)
  3. Pushes to origin and creates a PR
  4. Adds the specified label (default: enhancement)
  5. Squash-merges the PR
  6. Deletes the remote branch and resets local to updated main

You must be on the default branch (usually main) with no unpulled changes.

ship-changelog

Generate or update CHANGELOG.md from closed GitHub issues since your last release:

ship-changelog

This is useful when you want to edit the changelog separately (e.g., in an editor or Claude Code) before releasing. If you already have a CHANGELOG.md, it must include <!-- do not remove --> near the top so fastship knows where to insert the next release notes.

ship-gh

This is an interactive helper:

  1. Creates/updates CHANGELOG.md from closed GitHub issues since your last GitHub release
  2. Opens your $EDITOR (defaults to nano) so you can edit the changelog
  3. Prompts you to confirm
  4. Runs git commit -am release, git push
  5. Creates a GitHub release tagged with your current __version__
ship-gh

If you’ve already prepared the changelog (e.g., via ship-changelog), skip the changelog step:

ship-gh --no_changelog

This still opens CHANGELOG.md in your editor for final review before the release is created.

GitHub token setup

ship-gh looks for a token in this order:

  1. FASTSHIP_TOKEN
  2. a ./token file in your repo root
  3. GITHUB_TOKEN

The token must have permission to create releases (typically repo scope for classic PATs, or appropriate fine-grained permissions).

ship-release

Full release workflow assuming changelog is ready:

ship-changelog      # generate changelog, edit as needed
ship-release        # release to GitHub + PyPI, bump version, push

This runs:

  1. ship-gh --no_changelog (open CHANGELOG.md for final review, commit if needed, push, create GitHub release)
  2. ship-pypi (upload to PyPI)
  3. ship-bump (bump patch version)
  4. Commit and push the version bump

Notes

Existing projects

To add fastship to an existing project:

1) Put your version in __init__.py

In your package’s main __init__.py:

__version__ = "0.0.1"

2) Configure pyproject.toml

[project]
name = "my-project"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = { attr = "my_project.__version__" }

Keep __version__ = "x.y.z" as a simple literal (don’t compute it). ship-bump will rewrite this line near the top of the file to keep builds happy.

3) Optional: specify branch

Fastship infers your package name from [project].name (changing - to _). To override the release branch:

[tool.fastship]
branch = "main"  # defaults to current git branch