new-public-python-library

New public Python library (from the bitranox template)

Overview

Do not hand-build a new public Python library. Clone the template bitranox_template_py_lib (https://github.com/bitranox/bitranox_template_py_lib), rename it to your package, and you inherit a working layout, strict typing, a CLI, and a full CI/test/release pipeline. This skill is the scaffold-install-use sequence plus the pitfalls that a from-memory guess gets wrong.

When to use

• Starting any new public bitranox Python library (a reusable package, optionally with a registered CLI command).
• Installing or using a library that was built from this template.

Not for: an application/service (use the app template), or a one-off script.

1. Scaffold the repo

The rename is driven by the directory name, so name the new directory for your package first. Copy the template, detach the template remote, rename, then reset the history.

# 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 pushes back to it
git branch -m master main        # NEW repos use main, never master
git config core.fileMode false   # softdev mount: manage exec bits explicitly

./rename_dry.sh    # PREVIEW: rename-project --dry-run. Confirm the detected name/paths
                   # read "lib_wombat" everywhere before applying.
./rename.sh        # APPLY: rename-project --yes. Takes NO argument - the new name comes
                   # from the directory, so `./rename.sh lib_wombat` does nothing.
./reset_git_history.sh   # squash the template history into one fresh commit

rename.sh / rename_dry.sh run rename-project from git+https://github.com/bitranox/rename_project.git via uvx. reset_git_history.sh force-pushes to the first remote it finds, so detach the template origin first (above) or it rewrites the template's own history; with no remote it rewrites local history only. Add your own empty repo as origin and push main afterwards.

2. Install

uv venv && source .venv/bin/activate     # Windows: .venv\Scripts\Activate.ps1
uv pip install -e ".[dev]"               # editable, with the dev toolchain

For installing a FINISHED library (as a user): uv pip install <name>, or uv tool install <name> for the CLI, or uvx <name> to run without installing.

3. Use the result

The template ships a rich-click CLI (two console commands plus python -m <pkg>) and a small library API. Replace the placeholder behaviors with your own.

<pkg> info      # print resolved package metadata
<pkg> hello     # placeholder success path
<pkg> --help

import <pkg> as lib
lib.emit_greeting()     # placeholder; swap for your real API

4. Develop and release (bmk)

The Makefile is a thin bmk wrapper - do not edit it. Trailing args are forwarded; make help lists everything.

make test                         # lint + pyright + import-linter + bandit + pip-audit + pytest
make push MSG="feat: ..."         # test, commit, push (MSG= is the safe channel)
make bump-patch                   # bump X.Y.(Z+1); also bump-minor / bump-major
make release                      # tag + GitHub release; CI publishes to PyPI

CI, the PyPI publish workflow, and CodeQL come from .github/, managed by the default_cicd_public template. Never hand-edit .github/*. To publish to PyPI, add a Trusted Publisher on PyPI (owner, repo, workflow default_release_public.yml, environment pypi) or set the PYPI_API_TOKEN secret.

If the new repo also ships a skill, it is a marketplace

A repo that ships a Claude Code skill (a skills/<name>/SKILL.md plus .claude-plugin/plugin.json and marketplace.json) is a plugin marketplace. Two consequences that a plain library does not have:

• Protect its default branch on GitHub (block force-push and deletion, enforce on admins). A published marketplace that gets force-pushed silently freezes every install (/plugin marketplace update is a git pull that can no longer fast-forward).
• Bump the plugin version on every skill change (.claude-plugin/plugin.json, semver). Installs only re-fetch on a version change. Keep history append-only; never squash or force-push a published marketplace.

Common mistakes

Mistake	Fix
./rename.sh lib_wombat (passing the name as arg)	Name the DIRECTORY; run ./rename.sh with no arg.
Skipping ./rename_dry.sh	Always preview first; the dry-run is the safety check.
reset_git_history.sh with the template as origin	It force-pushes to the first remote; git remote remove origin first.
Keeping the master branch	New repos use main (git branch -m master main).
Editing .github/*	Template-managed; change CI in default_cicd_public instead.
Hand-editing the Makefile or version in code	Makefile is bmk-generated; bump only pyproject.toml.

Reference

The template's docs go deeper - open them on the default branch (latest) under https://github.com/bitranox/bitranox_template_py_lib/blob/master/docs/: installation.md, usage.md, development.md, and the systemdesign/ reference. A repo you generate from the template carries these same files locally, so inside your new project the plain docs/... paths resolve.