Thanks for your interest in improving the Warmbly Python SDK! This guide covers everything you need to get a change merged.
This project is governed by our Code of Conduct. By participating you are expected to uphold it. Please report unacceptable behavior to team@warmbly.com.
We use uv and nox, but
plain pip + venv works just as well.
git clone https://github.com/warmbly/warmbly-py
cd warmbly-py
# with uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
# or with pip
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev]"
# install the git hooks
pre-commit install| Task | Command |
|---|---|
| Run the tests | pytest |
| Tests across every Python | nox -s tests |
| Lint | ruff check src tests |
| Format | ruff format src tests |
| Type-check | mypy src tests |
| All pre-commit hooks | pre-commit run --all-files |
| Build the docs | mkdocs serve |
nox -s tests, nox -s lint, and nox -s typecheck mirror exactly what CI runs.
- Branch off
main:git switch -c feat/short-description. - Write code and tests. New behavior needs tests; bug fixes need a
regression test. The shipped package is held at 100% statement and branch
coverage (
fail_under = 100), so CI fails on any uncovered line. - Keep types honest. The SDK ships
py.typed; everything must passmypy --strict. Nohttpxtype may appear in a public signature. - Add a changelog fragment (see below).
- Run the hooks:
pre-commit run --all-files. - Open a PR. The PR title must follow
Conventional Commits (e.g.
feat: add contacts.export). It becomes the squash-merge commit message.
We assemble CHANGELOG.md at release time from news fragments, so changelog
edits never cause merge conflicts. Add one file per PR under changelog/:
echo "Add `client.contacts.export()`." > changelog/123.feature.mdThe filename is <issue-or-pr-number>.<type>.md, where <type> is one of:
feature, change, deprecation, removal, bugfix, security, doc.
We use the Developer Certificate of Origin. Sign off every commit (certifying you wrote the code or have the right to contribute it):
git commit -s -m "feat: ..."towncrier build --version X.Y.Zto assemble the changelog. Pass the bare version:title_formatinpyproject.tomladds thev, so avX.Y.Zhere renders the heading asvvX.Y.Z.- Commit, then tag:
git tag vX.Y.Z && git push --tags. - The release workflow builds, then publishes to PyPI via Trusted Publishing
and drafts a GitHub release. No API tokens are involved; the
pypienvironment requires a reviewer before anything uploads.
Versioning follows SemVer 2.0.0. The public API is the
warmbly.__all__ export set plus documented resource methods; underscore-prefixed
modules are private.