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

# Python SDK

> Official Python SDK for Westyx Nexus - sync and async clients, framework adapters.

Official Python SDK for [Westyx Nexus](https://westyx.dev) - the centralised secrets, feature flags, and config service.

```python theme={null}
from westyx_nexus import NexusClient, NexusConfig

nexus = NexusClient.create(NexusConfig(
    base_url="https://blue-ocean-a5rx7.westyx.dev",
    api_key="wxs_...",
))

db_url   = nexus.get_config("database.url")
stripe   = nexus.get_secret("stripe.key")
new_flow = nexus.get_flag("checkout.v2", default=False)

nexus.close()
```

## What's new in v0.10.0

* Version alignment across the Westyx Nexus SDK suite.

## What's new in v0.9.0

* **`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](workload-identity#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.

## What's new in v0.8.0

* **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`. `EvaluationContext` is ignored. See [OpenFeature provider](openfeature-provider).

## What's new in v0.5.1

* **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.

## What's new in v0.5.0

* **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.

## What's new in v0.4.0

* **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.

## Highlights

* **Python 3.11+** - single runtime dependency (`httpx`); the optional `aws_iam` WIF provider adds `botocore` via the `[aws-iam]` extra
* **Both sync and async APIs** - `NexusClient` and `AsyncNexusClient` share the same cache + SSE protocol; only the I/O model differs
* **Optional framework adapters** - Django, FastAPI, Flask integrations via extras (`pip install "westyx-nexus-sdk[django]"`)
* **Thread-safe TTL cache** with atomic snapshot replacement and ETag/304 support
* **SSE live updates** - propagates remote changes within milliseconds; falls back to TTL polling after 3 transport errors
* **Typed error hierarchy** - `NexusError` base + 11 subclasses for `isinstance` / `except` matching
* **Workload Identity Federation** *(v0.2.0)* - Kubernetes / AWS IRSA / GCP / Azure auto-detection; bearer JWT auth; **AWS IAM (`aws_iam`)** for ECS/Fargate/Lambda/plain-EC2 *(v0.9.0)*
* **Stream observer hooks** *(v0.2.0)* - structured callbacks for SSE lifecycle events
* **AB Testing** *(v0.3.0)* - `evaluate_ab` for batch per-user flag evaluation
* **File-type secrets** *(v0.3.0)* - `get_secret_file_path` materialises `type: "file"` secrets to temp files
* **OpenFeature provider** *(v0.8.0)* - `NexusProvider` sub-package (`westyx-nexus-openfeature`) for the OpenFeature Python SDK

## Package

Hosted on the [GitLab PyPI Package Registry](https://gitlab.com/westyx/nexus/sdk/python/-/packages). Install:

```sh theme={null}
pip install westyx-nexus-sdk
```

Latest release: **v0.10.0** *(2026-07-05 - version alignment across the Westyx Nexus SDK suite)*.

## Pages

| Page                                         | Description                                        |
| -------------------------------------------- | -------------------------------------------------- |
| [Installation](installation)                 | Register the GitLab PyPI registry, install         |
| [Configuration](configuration)               | `NexusConfig` field reference                      |
| [API reference](api-reference)               | Every public method, property, and async coroutine |
| [Error handling](error-handling)             | Error hierarchy + when each is raised              |
| [SSE live updates](sse-live-updates)         | How live propagation works in sync vs async        |
| [Stream observer](stream-observer)           | `StreamObserver` reference                         |
| [Workload identity](workload-identity)       | WIF setup, providers, custom token sources         |
| [Caching behaviour](caching-behaviour)       | When does the SDK hit the network                  |
| [OpenFeature provider](openfeature-provider) | Use Nexus via the OpenFeature SDK                  |