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.

SOAP payloads are not loggedZeep’s default async transport writes the complete SOAP request and response bodies at 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.
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