bitranox_template_py_lib

A scaffold for backward-compatible (Python 3.10+) libraries that ship a registered CLI command, with a rich-click entry point, strict typing, and a full test-and-release pipeline already wired.

Why a template

Starting a new Python library feels like it should be about the library. It almost never is. The first day goes on the scaffolding nobody brags about: which linter, which type checker, how the version number stays in step across three files, how a tag becomes a PyPI release, which Python versions you have quietly promised to keep working. None of that is the thing you set out to build, and all of it has to be right before the thing you set out to build can ship.

The tax on that work is invisible, which is exactly why people underprice it. A blank directory looks free. It is not. It is a stack of small decisions you will make in a hurry, slightly wrong, and then copy by hand into the next project, where you will make them slightly wrong again. A blank page is not a fresh start so much as a bill you have agreed to pay later.

A template is the boring answer that settles the bill up front. You inherit a working set of defaults, tests green across five Python versions and three operating systems, strict typing, a lint/type/test/release pipeline behind a single make command, a CLI that already runs, so the only decisions left are the ones that are actually about your library. The point is not that these are the only good choices. The point is that they are already made and already wired together, so you get to disagree with one on purpose rather than rediscover all of them by accident.

So clone it, delete the parts you do not want, and spend day one on the problem you actually care about. That is the whole trick: make the sensible path the lazy one.

Quickstart

1. Start a new library from this template

The first thing you do is copy the template into a new directory named for your package, rename it to that package, and reset the git history to one fresh commit. The directory name drives the rename, so name it for your library first.

# copy the template into a new dir named for your package
git clone --depth 1 https://github.com/bitranox/bitranox_template_py_lib.git lib_wombat
cd lib_wombat
git remote remove origin      # detach from the template so nothing ever pushes back to it
git branch -m master main     # new repos use main, not master

# rename the project to your package (rename-project, run via uvx)
./rename_dry.sh               # preview: rename-project --dry-run. Confirm every detected
                              #   name and path reads "lib_wombat" before applying.
./rename.sh                   # apply: rename-project --yes. Takes NO argument - the new name
                              #   comes from the directory, so `./rename.sh lib_wombat` is wrong.

# squash the template history into a single fresh commit
./reset_git_history.sh        # with the remote removed above, this rewrites local history only

Now create your own empty GitHub repo, add it as origin, and push main. Removing the template remote first matters: reset_git_history.sh force-pushes to the first remote it finds, and right after a clone that would be the template itself.

See docs/development.md for the full develop-test-release flow (bmk).

2. Try the CLI and API

To see what you get, install the template's own package from PyPI (uv recommended, plain pip works too):

uv pip install bitranox_template_py_lib

Run the CLI:

bitranox_template_py_lib hello     # -> Hello World
bitranox_template_py_lib info      # print resolved package metadata
bitranox_template_py_lib --help

Or run it without installing:

uvx bitranox_template_py_lib hello
python -m bitranox_template_py_lib hello

Use it as a library:

import bitranox_template_py_lib as lib

lib.emit_greeting()  # writes "Hello World" to stdout
lib.print_info()  # print the package metadata block

See docs/usage.md for the full command and API reference.

Documentation

• Installation
• Usage
• Development
• Module Reference
• Contributing
• Changelog
• Our stance on AI
• AI transparency
• License