Ttebra_soap_apiAsync Tebra SOAP 2.1
SOAP 2.1
Internals

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#

read
FileWsdlCache(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.

Parameters
ParameterTypeDescription
cache_dirPath | NoneDirectory for cached documents. Created if missing.
timeoutint | NoneMaximum age in seconds before an entry is treated as stale. None disables expiry.

cache.add#

read
add(url, content) -> None

Write a WSDL/XSD document to the cache atomically.

Parameters
ParameterTypeDescription
urlrequiredstrDocument URL used as the cache key.
contentrequiredbytes | strRaw document bytes or text.
ReturnsNone

cache.get#

read
get(url) -> bytes | None

Return cached bytes for a URL, or None when missing, unreadable, or expired.

Parameters
ParameterTypeDescription
urlrequiredstrDocument URL.
Returnsbytes | None

cache.clear#

read
clear() -> None

Delete all cached XML, metadata, and temporary files in the cache directory.

ReturnsNone
from 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#

helper
load_wsdl_document_sync(wsdl_url, *, cache=None, timeout=60.0, verify_ssl=True, strict=False) -> Document

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

Returnszeep.wsdl.Document

load_wsdl_document_async#

helper
async load_wsdl_document_async(wsdl_url, *, cache=None, timeout=60.0, verify_ssl=True, strict=False) -> Document

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

Returnszeep.wsdl.Document
Warm connectsThe in-memory cache is keyed by (wsdl_url, strict) and is process-wide. Closing a client does not clear it, so reconnecting is fast.

TebraAsyncTransport

TebraAsyncTransport#

read
TebraAsyncTransport(*, 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.

Parameters
ParameterTypeDescription
operation_timeoutfloatHTTP timeout in seconds. Default 30.0.
verify_sslboolVerify TLS certificates. Default True.
http_clienthttpx.AsyncClient | NoneInject an existing client. When omitted the transport owns and closes its own.
cacheZeepCacheBase | NoneOptional WSDL cache passed to Zeep.

await transport.aclose#

read
async aclose() -> None

Close the owned HTTP client and any WSDL client session. Called automatically by TebraClient.close().

ReturnsNone

EndpointThrottler

EndpointThrottler#

read
EndpointThrottler(*, 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.

Parameters
ParameterTypeDescription
enabledboolEnable enforcement. Default True.
buffer_msfloatExtra safety spacing added to each interval. Default 40.0.
overrides_msdict[str, float] | NoneOverride or add endpoint intervals in milliseconds.

throttler.get_interval_seconds#

read
get_interval_seconds(operation) -> float

Return the effective spacing in seconds for an operation: (base_ms + buffer_ms) / 1000, falling back to 250 ms for unknown endpoints.

Parameters
ParameterTypeDescription
operationrequiredstrSOAP operation name.
Returnsfloat

throttler.update_from_throttles#

read
update_from_throttles(throttle_details) -> None

Update intervals from a GetThrottles response. Reads Endpoint and ThrottleTimeMs from each row.

Parameters
ParameterTypeDescription
throttle_detailsrequiredlist[dict]Rows returned by GetThrottles.
ReturnsNone

throttler.slot#

read
async with throttler.slot(operation):

Async context manager that serializes same-endpoint calls and enforces the minimum interval. When disabled it yields immediately.

Parameters
ParameterTypeDescription
operationrequiredstrSOAP operation name.

Default intervals

EndpointBase intervalReason
GetAllPatients2500 msCursor pagination is expensive server-side.
GetThrottles5000 msAdministrative endpoint with a wide window.
GetPatients1000 msSearch endpoint.
GetTransactions1000 msLedger query.
GetExternalVendors1000 msVendor listing.
GetEligibilityStatus1000 msEligibility query.
Any other endpoint250 ms + bufferFallback 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"])

Related