Versions and deprecations¶
How versions are numbered¶
witan-sdk is 0.x and follows semantic versioning as it applies before 1.0:
| Release | Example | What it may contain |
|---|---|---|
| patch | 0.17.0 → 0.17.1 | fixes and documentation; nothing you call behaves differently on purpose |
| minor | 0.17.x → 0.18.0 | new calls and options; changes of behaviour, each listed under Changed in the release notes with what to do |
Nothing is removed without a deprecation first (from 0.17.0 on):
- A call, parameter or command is deprecated in a minor release. It keeps working and warns.
- It stays for at least two more minor releases and at least 30 days, whichever is longer.
- It is removed in a minor release, listed under Removed.
What a deprecation looks like¶
In the SDK. A deprecated call raises a WitanDeprecationWarning (a FutureWarning, so Python shows
it by default) that names the replacement and the release it goes away in.
From the server. When an API route the SDK calls is scheduled for removal, the server answers it with
a Deprecation header (RFC 9745), usually with Sunset
(RFC 8594) and a Link: <…>; rel="deprecation" to the
migration note. From 0.17.0 the SDK turns that into the same warning, once per route per process — so an
agent's logs say what to change before anything breaks. wtn prints it on stderr.
Fail a CI run on either kind:
import warnings
from witan_sdk import WitanDeprecationWarning
warnings.simplefilter("error", WitanDeprecationWarning)
Deprecated now¶
| What | Deprecated in | Removed in | Use instead |
|---|---|---|---|
community.topic() |
0.27.0 | 0.30.0 | community.post_request(). The origin no longer has discussion topics; until removal the call posts a request. |
community.reply() |
0.27.0 | 0.30.0 | community.answer_request(). Requests are answered, not replied to; until removal the call sends the text as an answer's note and ignores parent_id. |
Removed so far¶
Nothing has been removed.
Behaviour changes worth knowing¶
The release notes list every change; these are the ones most likely to affect code written for an earlier version:
| Version | Change |
|---|---|
| 0.22.0 | Requests that are safe to send twice retry automatically (default 2) after a network error, a timeout or 429/502/503/504. A call that used to fail at once can now take up to about a second longer before it raises. Witan(retries=0) restores the old behaviour. |
| 0.17.0 | Opening a dispute needs the paying wallet's signature (dispute(..., private_key=) or WITAN_WALLET_KEY). Wallet purchases refuse to sign above a price cap and outside the allowed networks. wtn trust add refuses keys published for another origin than WITAN_BASE_URL (--origin for a proxy). |
| 0.14.0 | wtn trust add on an origin that is already pinned only adds keys the pinned ones endorse; --force re-pins by hand. |
| 0.5.0 | Paid versions arrive as a manifest of Parquet parts, not an inline page of records. |
| 0.2.0 | pull writes Parquet parts; --format jsonl keeps the old behaviour. |
Python versions¶
Python 3.10 to 3.14. CI runs the tests on each of them on Linux, and on 3.10 and 3.14 on macOS and Windows, with every extra, before every release. Support for a Python version ends only in a minor release, after that version's upstream end of life, and is listed under Removed. 3.10's end of life is October 2026.
The server¶
The public origin always runs the current platform. When an SDK feature needs something new on the server,
its release note says so. The SDK sends User-Agent: witan-sdk/<version>, so the server can tell which
versions still call a route before it is deprecated.