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.
DEBUG. This transport overrides post() and logs only the sanitized endpoint, HTTP status, and payload byte size, so patient data is not emitted even when your application enables debug logging.| 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"])