Skip to content

Maintaining the SDK

This page is for those who work on the SDK itself. Plugin authors only need Writing plugins.

Layout

sdk/
├── sdk/python/
│   ├── pyproject.toml    # the published package: spot-sdk-python
│   ├── README.md         # its PyPI description
│   └── spot_sdk/
├── tests/                # the test suite, with .eml fixtures
├── docs/                 # this site (mkdocs.yml)
├── pyproject.toml        # the uv workspace root: the development environment
├── uv.lock
└── Makefile

The environment is managed with uv: uv sync installs the root pyproject.toml (the development group and the package in sdk/python/) into .venv, and the make targets run in it with uv run. uv lock updates uv.lock.

Working on the SDK

Command What it does
make test the suite, with coverage; it fails under 100 %
make quality ruff format, ruff check --fix and mypy (strict)
make docs builds this site into public/ (mkdocs.yml), with --strict: a warning fails the build
make docs-pdf builds the site with its PDF export (mkdocs.pdf.yml); not strict, as WeasyPrint cannot resolve the code-line anchors of the merged page
make docs-serve serves public/ on port 8005
make build-python builds the wheel and sdist into sdk/python/dist/

Rules the suite keeps:

  • coverage stays at 100 %, and each rule has a test that fails without it;
  • every warning, ResourceWarning included, is an error (pytest.ini);
  • the tests never touch the network: the clients take an httpx2.MockTransport, and the app runs in FastAPI's TestClient.

The models are the contract between core and the plugins: a change to them is a change to the contract. Core imports PluginKind, Egress, SettingField, Manifest and CONTRACT_VERSION from the SDK and keeps no copy of them.

Releasing

Versions follow PEP 440: 2.0.0, or a pre-release such as 2.0.0b1. Core and the plugins pin the exact version, and adopt each release by hand.

  1. Set the version: make version-python VERSION=2.0.0b2.
  2. Move the [Unreleased] entries of CHANGELOG.md under the version.
  3. Commit, and merge to main once the pipeline is green.
  4. Tag the merge commit with the version's CHANGELOG entries as the tag message:
git tag -a v2.0.0b2 -F release-notes.txt
git push origin v2.0.0b2

The tag's pipeline builds the package and publishes it to PyPI (publish:pypi, with the PYPI_TOKEN CI variable). It runs on tags matching v<major>.<minor>.<patch>, optionally followed by a<n>, b<n> or rc<n>. A python-v* tag publishes to the GitLab package registry instead (publish:python).

The documentation site is rebuilt by the pages job on main and on tags.

To publish by hand, set PYPI_TOKEN and run make build-python publish-python-pypi.