Versioning & stability

The Python SDK uses its own SemVer, independent of the /v1/ API version. The HTTP path is permanently /v1/; SDK version bumps are about the Python surface (method names, argument shapes, exception classes).

Current state

SemVer mapping

While the SDK is in 0.x, pin it tightly in production:

# requirements.txt
thrustlab>=0.1.0,<0.2.0

After 1.0, a looser constraint is safe:

thrustlab>=1.0,<2.0

Reading the installed version

import thrustlab
print(thrustlab.__version__)

The same value is reported in the User-Agent on every request — see logging & debugging.

Release cadence

• Patch releases ship as bug fixes are needed; no schedule.
• Minor releases ship roughly when a new /v1/ resource lands or a pattern (idempotency / pagination / retries) gets a meaningful upgrade.
• The plan is to graduate to 1.0 once the SDK has been used in production for a quarter without breaking changes.

Deprecation policy (post-1.0)

After 1.0, the SDK will follow the same deprecation timeline as the API:

1. New name lands; old name keeps working.
2. Old name emits a DeprecationWarning for at least one minor.
3. Old name is removed in the next major (e.g. 1.x → 2.0).

You can promote DeprecationWarning to errors in CI to catch usage early:

import warnings
warnings.filterwarnings("error", category=DeprecationWarning, module="thrustlab")

Compatibility with the /v1/ API

The /v1/ HTTP path is permanent — it does not get a v2. New fields are additive (don't break old SDK versions), and the stability policy governs what counts as a breaking change.

In practice this means:

• An old SDK can talk to a newer server. New optional fields are simply not exposed by the SDK — you'll see them in result["raw"] but not as typed attributes.
• A new SDK can talk to an older server, but only if every method it invokes exists. New methods raise 404 against an old server.

See also

• Stability policy — /v1/ API breaking-change rules
• Changelog — every shipped change