Transport & throttling
The transport layer keeps latency low: WSDL documents are cached on disk and in memory, HTTP connections are pooled, and each SOAP endpoint has its own async rate limiter.
FileWsdlCache
FileWsdlCache#
readFileWsdlCache(cache_dir=None, timeout=86400)A thread-safe filesystem cache for WSDL/XSD documents. It avoids the Python 3.12+ sqlite timestamp issues in Zeep's default SqliteCache and uses atomic writes (.tmp then replace). Cache entries are named by the SHA-256 of the URL. Defaults to the platform user cache directory under tebra_soap_api/wsdl.
| Parameter | Type | Description |
|---|---|---|
cache_dir | Path | None | Directory for cached documents. Created if missing. |
timeout | int | None | Maximum age in seconds before an entry is treated as stale. None disables expiry. |
cache.add#
readadd(url, content) -> NoneWrite a WSDL/XSD document to the cache atomically.
| Parameter | Type | Description |
|---|---|---|
urlrequired | str | Document URL used as the cache key. |
contentrequired | bytes | str | Raw document bytes or text. |
Nonecache.get#
readget(url) -> bytes | NoneReturn cached bytes for a URL, or None when missing, unreadable, or expired.
| Parameter | Type | Description |
|---|---|---|
urlrequired | str | Document URL. |
bytes | Nonecache.clear#
readclear() -> NoneDelete all cached XML, metadata, and temporary files in the cache directory.
Nonefrom tebra_soap_api import FileWsdlCache
cache = FileWsdlCache(cache_dir="./.wsdl-cache", timeout=86400)
cache.clear() # force a fresh WSDL download on the next connect()
WSDL document loading
load_wsdl_document_sync#
helperload_wsdl_document_sync(wsdl_url, *, cache=None, timeout=60.0, verify_ssl=True, strict=False) -> DocumentLoad and compile a Zeep Document synchronously. A compiled document is reused from a process-wide in-memory cache, so multiple clients in one process share the parsed schema.
zeep.wsdl.Documentload_wsdl_document_async#
helperasync load_wsdl_document_async(wsdl_url, *, cache=None, timeout=60.0, verify_ssl=True, strict=False) -> DocumentLoad and compile the WSDL in a worker thread via asyncio.to_thread, so the event loop is never blocked. Reuses the same in-memory document cache.
zeep.wsdl.Document(wsdl_url, strict) and is process-wide. Closing a client does not clear it, so reconnecting is fast.TebraAsyncTransport
TebraAsyncTransport#
readTebraAsyncTransport(*, operation_timeout=30.0, verify_ssl=True, http_client=None, cache=None)A Zeep AsyncTransport backed by httpx.AsyncClient with keep-alive pooling (10 keep-alive, 20 max connections). It avoids leaked synchronous WSDL client sessions and can reuse a caller-supplied HTTP client.
| Parameter | Type | Description |
|---|---|---|
operation_timeout | float | HTTP timeout in seconds. Default 30.0. |
verify_ssl | bool | Verify TLS certificates. Default True. |
http_client | httpx.AsyncClient | None | Inject an existing client. When omitted the transport owns and closes its own. |
cache | ZeepCacheBase | None | Optional WSDL cache passed to Zeep. |
await transport.aclose#
readasync aclose() -> NoneClose the owned HTTP client and any WSDL client session. Called automatically by TebraClient.close().
NoneEndpointThrottler
EndpointThrottler#
readEndpointThrottler(*, enabled=True, buffer_ms=40.0, overrides_ms=None)Per-endpoint async rate limiter. Each operation gets its own asyncio.Lock and last-call timestamp. Back-to-back calls to the same endpoint are spaced; calls to different endpoints run concurrently.
| Parameter | Type | Description |
|---|---|---|
enabled | bool | Enable enforcement. Default True. |
buffer_ms | float | Extra safety spacing added to each interval. Default 40.0. |
overrides_ms | dict[str, float] | None | Override or add endpoint intervals in milliseconds. |
throttler.get_interval_seconds#
readget_interval_seconds(operation) -> floatReturn the effective spacing in seconds for an operation: (base_ms + buffer_ms) / 1000, falling back to 250 ms for unknown endpoints.
| Parameter | Type | Description |
|---|---|---|
operationrequired | str | SOAP operation name. |
floatthrottler.update_from_throttles#
readupdate_from_throttles(throttle_details) -> NoneUpdate intervals from a GetThrottles response. Reads Endpoint and ThrottleTimeMs from each row.
| Parameter | Type | Description |
|---|---|---|
throttle_detailsrequired | list[dict] | Rows returned by GetThrottles. |
Nonethrottler.slot#
readasync with throttler.slot(operation):Async context manager that serializes same-endpoint calls and enforces the minimum interval. When disabled it yields immediately.
| Parameter | Type | Description |
|---|---|---|
operationrequired | str | SOAP operation name. |
Default intervals
| Endpoint | Base interval | Reason |
|---|---|---|
GetAllPatients | 2500 ms | Cursor pagination is expensive server-side. |
GetThrottles | 5000 ms | Administrative endpoint with a wide window. |
GetPatients | 1000 ms | Search endpoint. |
GetTransactions | 1000 ms | Ledger query. |
GetExternalVendors | 1000 ms | Vendor listing. |
GetEligibilityStatus | 1000 ms | Eligibility query. |
| Any other endpoint | 250 ms + buffer | Fallback spacing. |
Example: refresh throttles
# Ask Tebra for live intervals and sync the client's throttler.
details = await client.get_throttles(sync_client_throttler=True)
for row in details:
print(row["Endpoint"], row["ThrottleTimeMs"])