Versioning & migration

Versioning

The Python SDK follows Semantic Versioning:

• MAJOR — breaking changes to the public Python API or the minimum supported Python version.
• MINOR — new endpoints, new methods, new optional arguments, new interceptor hooks.
• PATCH — bug fixes, performance improvements, regenerated models that don’t remove or rename fields.

The SDK version is independent from the backend API version. We regenerate models on every backend contract change and bundle them into the next minor or patch release.

Compatibility matrix

SDK version	Python	OpenApp API
0.x	3.10+	v1

Until 1.0.0 we reserve the right to make small breaking changes between minor versions — but we’ll always call them out in the changelog.

Upgrading

Patch / minor

pip install --upgrade openapp-sdk

No code changes required.

Major

Major releases ship with a dedicated migration guide published in the changelog and in this section. Typical migration effort is under an hour per codebase.

Deprecations

Deprecated APIs raise a DeprecationWarning and are kept working for at least one subsequent minor release. Run with -W error::DeprecationWarning in CI to catch them early.

Pinning

For production services, pin to a compatible range:

pyproject.toml

[project]
dependencies = [
  "openapp-sdk>=0.2,<0.3",
]

or use a lock file (uv.lock, poetry.lock, requirements.txt).

Yanked versions

If we ship a broken release we yank it from PyPI (docs). Yanked versions stay installable by exact pin but are hidden from new installs; a patch release follows within 24 hours.

Changelog

See the Python SDK changelog for the full release history.