> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westyx.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK - Version history

> What changed in each release of the Python SDK, and how to migrate across a breaking change.

Every release of `westyx-nexus-sdk` and `westyx-nexus-openfeature`, newest first. Both release from
one tag and share one version number. Where a release broke something, its **Migrating** section
shows the change to make. The repository's
[`CHANGELOG.md`](https://gitlab.com/westyx/nexus/sdk/python/-/blob/main/CHANGELOG.md) carries the
same releases in full detail.

## v0.19.1 - 2026-11-19

* **OpenFeature `423 service_locked` hold:** uses a timed suppression window (default 5 minutes) matching `environment_disabled`, so `evaluate-ab` recovers automatically once the lockdown is lifted.
* **Stream observer on `423`:** calls `on_fallback(FALLBACK_REASON_SERVICE_LOCKED)` followed by `on_disconnected(NexusServiceLockedError("stream"))` in both sync and async clients.

## v0.19.0 (2026-11-19)

* **HTTP 423 `service_locked`:** adds `NexusServiceLockedError` and `FALLBACK_REASON_SERVICE_LOCKED`; stops SSE reconnects immediately and halts background sync retries until an explicit `sync()` succeeds.
* **OpenFeature provider:** suppresses repeated `evaluate-ab` requests while the service is locked down, serving the cached snapshot as `STALE`.

## v0.18.1 - 2026-11-12

* **The OpenFeature provider stops asking a switched-off environment.** While the environment is switched off in the console, a targeted evaluation serves the snapshot as `STALE` and the provider sends no `evaluate_ab` request - for any user - for the `addon_suppression` window, with one warning; any success clears it. `westyx-nexus-openfeature` requires `westyx-nexus-sdk>=0.18.0`.

## v0.18.0 - 2026-11-12

* **A switched-off environment is reported by name.** `403 {"error":"environment_disabled"}` raises
  `NexusEnvironmentDisabledError`. The cache keeps serving; the background refresh and the stream
  wait five minutes between attempts (`on_fallback("environment-disabled")`), and the first
  successful sync clears it. Both clients.
* **Every API error carries its status and code.** A response no more specific exception describes
  raises `NexusApiError` with `status_code`, `code` and `operation`; the message never carries the
  response body. A `429` on the sync path is `NexusRateLimitedError`, and a quarantine `429` on any
  path is `NexusQuarantinedError`.
* **The SDK logs through the `westyx_nexus` logger by default** - silent until your application
  configures logging, visible as soon as it does. `NexusLogger` gains `warning`; a logger without
  it still works.
* **The startup summary**: `nexus: client loaded` names the configs, secrets and flags the first
  sync delivered - never a value. `WESTYX_NEXUS_LOG_STARTUP=1` also writes it to standard error.
* **`sync_errors`** lists the resources the server did not deliver, each logged once as a warning;
  `log_sync_errors=False` keeps the list without the log lines.
* **Concurrent `sync()` calls on `NexusClient` apply one at a time**, so an older response never
  replaces a newer one.
* **The stream recovers on its own from every refusal.** A `401` or a switched-off environment
  retries on the `sse_reconnect_cooldown` schedule; a successful connection starts the failure count
  and the backoff over, and so does the cooldown.
* **A WIF refresh that fails while the session is still valid no longer fails the request**; an
  expired session with no `api_key` raises `NexusSessionExpiredError` with the refresh error as its
  `__cause__`, and a credential that is gone raises `NexusWIFNotConfiguredError` at once.
* **Python 3.15** is supported and tested.

### Migrating to v0.18.0

* Code that matched the message of an unmapped status (`unexpected status 500`) reads
  `err.status_code` instead.
* With no `logger=`, SDK records now reach the `westyx_nexus` logger; to keep them out of a root
  logger configured at `INFO`, set `logging.getLogger("westyx_nexus").setLevel(logging.WARNING)`.
* A custom `NexusLogger` may add `warning`; without it, warnings arrive at `info`.

## v0.17.0 - 2026-09-30

* **The endpoint can come from the environment.** `NexusConfig.base_url` is optional; when it is `None` or empty, `create()` reads `WESTYX_SERVICE_ENDPOINT` (`SERVICE_ENDPOINT_ENV`), which `westyx dev run` sets for the script's service - so neither the endpoint nor a key has to be in your code. `base_url` wins when both are set, a `base_url` that is not a `str` raises `TypeError`, and an error about a value from the variable names the variable.
* **The Flask and Django adapters support Workload Identity Federation.** `NEXUS_BASE_URL` and `NEXUS_API_KEY` are optional, a new `NEXUS_WIF` setting configures WIF, and with neither a key nor `NEXUS_WIF` the adapter uses WIF with the default provider - so `westyx dev run` starts a Flask or Django application with no Nexus settings.
* **`NexusSessionExpiredError`** is raised when a WIF session is rejected and no `api_key` is configured to fall back on; a developer session keeps its `westyx dev setup` message.

## v0.16.0 - 2026-08-27

* **A custom `logger` whose method raises no longer fails an SDK operation.** Every internal log call is contained, so a logging sink that raises - a full disk, a down syslog target - is dropped and the read, refresh, or `create()` (sync and async) that logged continues. The stream observer already had this guarantee; it now covers the logger too. The WIF credential source is deliberately not contained - it is on the auth path and still surfaces its error.

## v0.15.0 - 2026-08-21

* **The async client has the write API.** `AsyncNexusClient` gains `set_secret`, `delete_secret` and `delete_secret_version`, mirroring `NexusClient`; both route every write status through one shared path so they cannot drift.
* **The public-key guard reads the backend's `key_type`, not just the key prefix** - a key the server reports as public is refused secrets even without the `wxp_` prefix, because either signal is enough.
* **`follow_redirects` is off on every HTTP client** and **the SSE line reader is bounded**, so a credential-bearing request never follows a server-chosen redirect and a server that never emits a newline cannot make the client buffer without limit.
* **The async client keeps blocking file I/O off the event loop** - file-secret writes and cleanup run in a worker thread.
* **Thread safety and the free-threaded (no-GIL) position are documented.**
* Changed: **minimum `httpx` is now `>=0.26`** (0.25 does not import on Python 3.14).

## v0.14.0 - 2026-08-10

* **The WIF provider set is a type.** `WIFProvider` is a `StrEnum` unioned with the equivalent `Literal`, so the enum member and the plain string both type-check and a value outside the set does not. Members *are* strings, so nothing changes at runtime; an invalid one raises `ValueError` at `WIFConfig(...)`.
* **`exchange_payload`** builds the whole token-exchange body from an `ExchangeContext`, so a credential that is not an OIDC token can be expressed - and the `aws_iam` shape is reachable without `botocore` if you sign the request yourself.
* **A `developer` provider.** After `westyx dev setup`, `WIFConfig(enabled=True)` authenticates a developer machine against a WIF-enforced service with the session the CLI already obtained - no token exchange, nothing to install. It is the last provider `auto` considers.
* **The API key and the session token stay out of `__repr__`**, which is what a traceback rendered with frame locals prints.
* Breaking: **`WIFConfig` is keyword-only**, and `provider="aws_iam"` with `token_source` is refused.

## v0.13.0 - 2026-08-06

* **File-type secrets live in a per-client private directory**, created `0700` lazily on the first file-type secret; every file inside is created `0600` with `O_EXCL`, so the mode is a guarantee regardless of what already occupies the path. A process-level `atexit` hook removes the files even when the process exits without `close()`. See [File-type secret security](https://docs.westyx.dev/sdks/python/file-secret-security.md).
* **A 402 Payment Required throttles the background refresh** to one attempt every five minutes instead of ending it, and any successful sync - a `304 Not Modified` included - clears `billing_overdue`. Settling the invoice restores service without a restart.
* **The SSE stream has an idle deadline** - new `stream_idle_timeout` option, default 90 s, sized against the server's 30 s keepalives. A connection reaped by a load balancer surfaces as a transport error and reconnects instead of blocking forever. See [SSE live updates](https://docs.westyx.dev/sdks/python/sse-live-updates.md).
* Breaking: **`ttl_seconds` (and `stream_idle_timeout`) are validated at `create()`** - zero, negatives and `bool` raise `ValueError` naming the option instead of silently becoming the default.

## v0.12.0 - 2026-08-03

* **Per-user flag targeting through the [OpenFeature provider](https://docs.westyx.dev/sdks/python/openfeature-provider.md).** With a targeting key in the evaluation context, a boolean flag is resolved through the AB Testing add-on, so its rollout percentage and cohort rules apply to that identity. One request serves every flag the snapshot knows for that identity, results are memoised, and concurrent evaluations for one identity coalesce into a single request. Without a targeting key nothing changes.
* **`find_flag(key)`** on both clients returns the flag's `is_active` state or `None` when the flag is not in the cache at all - the distinction `get_flag` cannot express, and the one an OpenFeature provider needs in order to answer `FLAG_NOT_FOUND`.
* **`NexusProviderOptions`** tunes the targeting TTL, the memoised-identity cap and the add-on suppression window; a value that cannot work is rejected at construction, naming the option.
* Breaking: `evaluate_ab` refuses a non-string attribute value with `TypeError` naming the attribute, the provider no longer coerces numbers, and an unknown flag resolves as `FLAG_NOT_FOUND`.

## v0.11.0 - 2026-07-27

A correctness and type-safety release. Nothing in the public API breaks.

* **Ships `py.typed`** (PEP 561) for both packages. Without the marker, type checkers ignore an installed package's annotations entirely - every SDK call resolved to `Any` in your project, however well annotated the SDK was. The SDK is now clean under both `mypy --strict` and `pyright`. See [Type checking](https://docs.westyx.dev/sdks/python/type-checking.md).
* **SSE reconnect fixes.** A misconfigured `sse_reconnect_cooldown` used to kill the stream worker: the handler meant to fall back to the default schedule called a logger method that does not exist, and raised. The value is validated at `create()` now and rejected with a message naming the bad input. Separately, `AsyncNexusClient` ignored `sse_reconnect_cooldown` entirely and ended its stream permanently after three transient transport errors - it now reconnects on the configured schedule, matching `NexusClient`. See [SSE live updates](https://docs.westyx.dev/sdks/python/sse-live-updates.md).
* **The SSE client now has a connect timeout.** Lifting the read deadline on a long-lived stream is right; lifting the connect deadline with it was not, and a connect to a black-holed endpoint hung indefinitely with no error and no reconnect.
* **File-type secrets are written `0600`**, applied at creation rather than by a chmod afterwards, and opened with `O_NOFOLLOW`. Each client materialises to its own paths, so two clients holding the same secret never share a file. See [File-type secret security](https://docs.westyx.dev/sdks/python/file-secret-security.md).
* **A faulting stream observer is reported.** Your observer still cannot break the SDK, but a callback that raises is logged with the hook name and the original exception instead of vanishing.
* **No `assert` in shipped code** - `python -O` strips them, and the session-refresh precondition guard went with them.
* **CI gates on `ruff`, `mypy`, `pyright` and `bandit`**, and the suite runs on Python 3.11 through 3.14 - every version this package advertises.

## v0.10.0 - 2026-07-05

* Version alignment across the Westyx Nexus SDK suite.

## v0.9.0 - 2026-07-03

* **`aws_iam` WIF provider (AWS IAM Caller Identity)** - authenticates non-EKS AWS compute (**ECS/Fargate, Lambda, plain EC2**) that has IAM credentials but no OIDC token. The SDK SigV4-signs an STS `GetCallerIdentity` request (never sent to AWS) and posts it to `/v1/auth/token-exchange`; Nexus replays it against a pinned STS endpoint to prove your IAM role. The signed `X-Nexus-Server-ID` is your service's own base-URL host - a captured request is valid for that one service only, and there is nothing to configure. Requires the optional `botocore` dependency (`pip install 'westyx-nexus-sdk[aws-iam]'`). See [Workload identity](https://docs.westyx.dev/sdks/python/workload-identity.md#aws-iam-non-eks-aws-compute).
* **Azure Workload Identity (AKS)** - the `azure` provider now prefers the projected federated token file (`$AZURE_FEDERATED_TOKEN_FILE`) before falling back to IMDS; auto-detection probes the file too.
* **Probe-based auto-detection** - auto-detect now stats the Kubernetes / AWS-IRSA / Azure token files and live-probes the GCP and Azure metadata servers (\~1 s timeout), instead of keying on environment variables absent on real cloud nodes.
* **Security hardening** - both clients reject plain-http `base_url`s (loopback excepted); the Azure IMDS path refuses the generic default audience (must be `api://<client-id>`); the async client no longer blocks the event loop on metadata calls; the `httpx.Client` leak is fixed; metadata/exchange reads are bounded.

## v0.8.0 - 2026-06-16

* **OpenFeature provider** - new `westyx-nexus-openfeature` sub-package ships `NexusProvider`, an `AbstractProvider` for the [OpenFeature Python SDK](https://github.com/open-feature/python-sdk). Wraps an existing `NexusClient`; booleans via `get_flag`, string/integer/float/object via `get_config`. See [OpenFeature provider](https://docs.westyx.dev/sdks/python/openfeature-provider.md).

## v0.5.1 - 2026-06-03

* **Requires Python 3.11+** - Python 3.10 is EOL; minimum is now 3.11.
* **Security improvements** - exception messages contain only status codes; file-type secret paths are fully hashed; WIF tokens stripped of whitespace on all providers.
* **WIF reliability** - session refreshes before each SSE reconnect; expired sessions no longer cause permanent TTL-polling fallback.
* **CI** - tests run on merge requests; publish restricted to `main`-branch tags.

## v0.5.0 - 2026-06-01

* **Write API** - `set_secret`, `delete_secret`, `delete_secret_version` for programmatic secret management. secret keys only; public keys raise `NexusPublicKeyError` immediately without a network call.
* **`NexusRateLimitedError`** - new error for HTTP 429 on write endpoints.

## v0.4.0 - 2026-05-28

* **Path prefix change** - all API paths are now `/v1/` (previously `/api/v1/`). Update `base_url` to use `<slug>.westyx.dev`.
* **`NexusQuarantinedError`** - new typed error raised on `429` with quarantine body. Both sync and stream paths detect this.
* **`on_quarantined(reason, expires_at)` observer callback** - `StreamObserver` gains a sixth callback; fires on quarantine events from both the stream and sync paths.
* **Quarantine backoff** - stream sleeps until `expires_at` before reconnecting; background sync is paused during the quarantine window.
* **Removed `ConfigEntry.is_public`** - the field is no longer populated.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.