TebraClient
TebraClient is an async context manager that owns the WSDL document, the pooled HTTP transport, and the per-endpoint throttler. It exposes the domain resources plus a set of flat convenience methods.
Lifecycle
TebraClient#
readTebraClient(config=None, *, user=None, password=None, customer_key=None, wsdl=None, timeout=30.0, wsdl_timeout=60.0, cache_wsdl=True, cache_ttl=86400, cache_dir=None, respect_throttles=True, throttle_buffer_ms=40.0, max_retries=2, read_only=None, verify_ssl=True, client_version=None, dotenv_path=None, zeep_client=None)Creates the client and mounts every resource namespace: practices, patients, appointments, charges, encounters, providers, locations, procedure_codes, payments, documents, and system. Network work starts only when you call connect() or enter the async context manager.
| Parameter | Type | Description |
|---|---|---|
config | TebraConfig | None | A pre-built config. When omitted, the remaining keyword arguments are passed to TebraConfig.resolve. |
user | str | None | Tebra API user. |
password | str | None | Tebra API password. |
customer_key | str | None | Tebra CustomerKey. |
wsdl | str | None | WSDL URL override. |
timeout | float | Operation timeout. Default 30.0. |
wsdl_timeout | float | WSDL timeout. Default 60.0. |
cache_wsdl | bool | Enable disk WSDL cache. Default True. |
cache_ttl | int | Cache lifetime in seconds. Default 86400. |
cache_dir | Path | str | None | Custom WSDL cache directory. |
respect_throttles | bool | Enable per-endpoint spacing. Default True. |
throttle_buffer_ms | float | Buffer added to throttle intervals. Default 40.0. |
max_retries | int | Retries for retryable reads. Default 2. |
read_only | bool | None | Block mutating operations. Defaults to TEBRA_READ_ONLY / .env, else False. |
verify_ssl | bool | Verify TLS certificates. Default True. |
client_version | str | None | Optional SOAP ClientVersion. |
dotenv_path | Path | str | None | Specific .env path. |
zeep_client | Any | None | Inject a pre-built Zeep async client (advanced/testing). When supplied, the client does not own its lifecycle. |
from tebra_soap_api import TebraClient
client = TebraClient(
read_only=True,
timeout=45.0,
max_retries=3,
)await client.connect()#
readasync connect() -> TebraClientLoads the cached WSDL schema (compiling off the event loop) and opens the pooled async HTTP transport. Idempotent and protected by an async lock. Returns the same client.
TebraClientawait client.close()#
readasync close() -> NoneCloses the underlying HTTP connection pool and releases an owned Zeep client. Safe to call more than once.
Noneasync with TebraClient(...)#
readasync __aenter__() -> TebraClientConnects and returns the client; __aexit__ closes the transport. This is the recommended pattern so connections are always released.
async with TebraClient(read_only=True) as client:
practices = await client.get_practices()client.is_connected#
readis_connected -> boolProperty indicating whether a Zeep client is currently bound. It becomes True after connect() and False after close() for an owned client.
boolRaw dispatcher
await client.call#
readasync call(operation, payload=None, *, raw=False, check_errors=True, **kwargs) -> AnyExecutes any Tebra SOAP 2.1 operation with authentication injection, write protection, per-endpoint throttling, retries, and structured error handling. Prefer the typed resource methods; use this for operations without a wrapper.
| Parameter | Type | Description |
|---|---|---|
operationrequired | str | Exact SOAP operation name, for example GetPractices. |
payload | Mapping | None | Body fields placed directly into the SOAP request. |
raw | bool | Return the raw Zeep response instead of plain dict/list data. Default False. |
check_errors | bool | Inspect SecurityResponse and ErrorResponse and raise typed errors. Default True. |
**kwargs | Any | Merged into the request body alongside payload. |
dict / list for normal calls; the raw Zeep object when raw=True.GetCustomerIdFromKey is sent without a RequestHeader; UpdatePatient is dispatched with UpdatePatientReq instead of request. The dispatcher applies both quirks automatically.practices = await client.call(
"GetPractices",
{"Filter": {}, "Fields": {"ID": True, "PracticeName": True}},
)Flat convenience methods
These methods delegate to resources and cover the common read paths. Anything not listed here (writes, schedules, documents, external vendors) is available through the resource namespaces.
| Flat method | Delegates to | SOAP operation |
|---|---|---|
| get_practices | practices.list | GetPractices |
| get_practice | practices.get | GetPractices |
| get_patient | patients.get | GetPatient |
| get_patients / search_patients | patients.list | GetPatients |
| iter_all_patients | patients.iter_all | GetAllPatients |
| get_all_patients | patients.list_all | GetAllPatients |
| get_appointments | appointments.list | GetAppointments |
| get_appointment | appointments.get | GetAppointment |
| get_appointment_reasons | appointments.list_reasons | GetAppointmentReasons |
| get_charges | charges.list | GetCharges |
| get_procedure_codes | procedure_codes.list | GetProcedureCodes |
| get_encounter_details | encounters.get_details | GetEncounterDetails |
| get_providers | providers.list | GetProviders |
| get_provider_schedules | providers.get_schedules | GetProviderSchedules |
| get_service_locations | locations.list | GetServiceLocations |
| get_payments | payments.list | GetPayments |
| get_transactions | payments.list_transactions | GetTransactions |
| get_throttles | system.get_throttles | GetThrottles |
| get_customer_id | system.get_customer_id | GetCustomerIdFromKey |
Common signatures
await client.get_practices#
readasync get_practices(*, practice_id=None, practice_name=None, active=None, fields=None, **kwargs) -> list[dict]List practices. Alias: list_practices. See PracticesResource.list for all filter options.
list[dict[str, Any]]await client.get_patients#
readasync get_patients(*, practice_id=None, practice_name=None, first_name=None, last_name=None, full_name=None, dob=None, fields=None, **kwargs) -> list[dict]Search patients. Alias: search_patients. Uses GetPatients; see PatientsResource.list for the full filter surface.
list[dict[str, Any]]await client.get_appointments#
readasync get_appointments(*, practice_name=None, practice_id=None, start_date=None, end_date=None, patient_id=None, patient_full_name=None, fields=None, **kwargs) -> list[dict]Query appointments. practice_id is resolved to PracticeName; date-only bounds expand to UTC day boundaries.
list[dict[str, Any]]await client.get_charges#
readasync get_charges(*, practice_name=None, practice_id=None, patient_name=None, from_service_date=None, to_service_date=None, fields=None, **kwargs) -> list[dict]Query charges. Ranges longer than 60 days are split automatically. Set auto_chunk_days=None through the resource method to disable.
list[dict[str, Any]]Concurrency
Different endpoints have independent locks, so asyncio.gather runs them in parallel. Back-to-back calls to the same endpoint are spaced to respect Tebra’s throttle windows.
appointments, charges, providers, locations = await asyncio.gather(
client.get_appointments(practice_id=7, start_date="2026-04-01", end_date="2026-04-15"),
client.get_charges(practice_id=7, from_service_date="2026-04-01", to_service_date="2026-04-15"),
client.get_providers(practice_id=7, active_only=True),
client.get_service_locations(practice_id=7),
)
Extending with a custom resource
Subclass BaseResource when you need an operation that is not wrapped yet. It holds a reference to the client and offers protected helpers: _call(operation, **payload) for a raw SOAP call, _query_list(...) to extract a clean list from an ArrayOf* response, and _clean_single(...) to clean a single record while dropping ghost rows.
from tebra_soap_api.resources import BaseResource
class MyResource(BaseResource):
async def recent_practices(self) -> list[dict]:
return await self._query_list(
"GetPractices",
outer_key="Practices",
inner_key="PracticeData",
filter_data={"Active": "True"},
fields=["ID", "PracticeName"],
)
client.my_resource = MyResource(client)
BaseResource is exported from tebra_soap_api.resources.