Configuration
Credentials and client behavior live in a single dataclass, TebraConfig. The client accepts it directly or builds one from keyword arguments.
Resolution order
TebraClient(...) or TebraConfig.resolve(...) win.TEBRA_USER, TEBRA_PASSWORD, TEBRA_CUSTOMER_KEY, TEBRA_WSDL, and TEBRA_READ_ONLY..envFinally a .env file in the working directory (or dotenv_path). Parsing is side-effect free — os.environ is never changed.Environment variables
| Variable | Maps to | Notes |
|---|---|---|
TEBRA_USER | user | Required unless passed explicitly. |
TEBRA_PASSWORD | password | Required unless passed explicitly. |
TEBRA_CUSTOMER_KEY | customer_key | Required unless passed explicitly. |
TEBRA_WSDL | wsdl | Optional WSDL override. |
TEBRA_READ_ONLY | read_only | Truthy values: 1, true, yes, on. |
TEBRA_USER=user@example.com
TEBRA_PASSWORD=your-password
TEBRA_CUSTOMER_KEY=your-customer-key
TEBRA_READ_ONLY=true
TebraConfig fields
| Parameter | Type | Description |
|---|---|---|
userrequired | str | Tebra API user name or email. |
passwordrequired | str | Tebra API password. Hidden from repr(). |
customer_keyrequired | str | Tebra CustomerKey. Hidden from repr(). |
wsdl | str | WSDL URL. Defaults to DEFAULT_WSDL (the Tebra 2.1 single-WSDL endpoint). |
timeout | float | Per-operation HTTP timeout in seconds. Default 30.0. |
wsdl_timeout | float | WSDL download/compile timeout in seconds. Default 60.0. |
cache_wsdl | bool | Enable the disk WSDL cache. Default True. |
cache_ttl | int | WSDL cache lifetime in seconds before refresh. Default 86400 (1 day). |
cache_dir | Path | None | Custom WSDL cache directory. Defaults to the platform user cache directory. |
respect_throttles | bool | Enforce per-endpoint minimum spacing. Default True. |
throttle_buffer_ms | float | Safety buffer added to every throttle interval. Default 40.0. |
max_retries | int | Retries for retryable reads (throttle XML, transient transport). Default 2. |
read_only | bool | Block every operation listed in WRITE_OPERATIONS. Default False. |
verify_ssl | bool | Verify TLS certificates. Default True. |
client_version | str | None | Optional ClientVersion sent in the SOAP request header. |
password and customer_key are declared with repr=False, so printing the config or logging a traceback cannot leak them.TebraConfig.resolve
TebraConfig.resolve#
readTebraConfig.resolve(*, 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) -> TebraConfigClassmethod that builds a configuration from explicit values, environment variables, and an optional .env file. Raises TebraConfigError when a required credential is missing.
| Parameter | Type | Description |
|---|---|---|
user | str | None | Explicit credential; falls back to TEBRA_USER or .env. |
password | str | None | Explicit credential; falls back to TEBRA_PASSWORD or .env. |
customer_key | str | None | Explicit key; falls back to TEBRA_CUSTOMER_KEY or .env. |
wsdl | str | None | Explicit WSDL URL; falls back to TEBRA_WSDL, then DEFAULT_WSDL. |
read_only | bool | None | Explicit guard; when omitted reads TEBRA_READ_ONLY / .env. |
dotenv_path | Path | str | None | Optional path to a specific .env file. Does not mutate os.environ. |
… | — | All other TebraConfig fields are accepted with the same defaults. |
TebraConfigfrom tebra_soap_api import TebraConfig
config = TebraConfig.resolve(read_only=True, dotenv_path=".env.staging")
print(config.user)
print(config) # password and customer_key are redactedbuild_request_header
TebraConfig.build_request_header#
readTebraConfig.build_request_header() -> dict[str, str]Builds the standard SOAP request header from user, password, and customer_key. Adds ClientVersion only when client_version is set. Most callers never need this; the client injects the header automatically.
dict[str, str]header = config.build_request_header()
# {"User": "...", "Password": "...", "CustomerKey": "..."}Constants
DEFAULT_WSDL#
The default Tebra 2.1 single-WSDL endpoint: https://webservice.kareo.com/services/soap/2.1/KareoServices.svc?singleWsdl.
DEFAULT_ENDPOINT_THROTTLE_MS#
Baseline per-endpoint spacing used before a live GetThrottles call updates the client.
| Endpoint | Milliseconds |
|---|---|
| GetAllPatients | 2500 |
| GetThrottles | 5000 |
| GetPatients | 1000 |
| GetTransactions | 1000 |
| GetExternalVendors | 1000 |
| GetEligibilityStatus | 1000 |
| Any other endpoint | 250 (fallback) |
WRITE_OPERATIONS#
A frozenset of every mutating SOAP operation. When read_only=True, the client raises TebraReadOnlyError for any of these before dispatching.
CreateAppointment, CreateAppointmentReason, CreateDocument, CreateEncounter, CreatePatient, CreatePayment, CreateUnappliedPayment, DeleteAppointment, DeleteDocument, RegisterExternalVendor, SendHL7Message, UpdateAppointment, UpdateAppointmentStatus, UpdateEncounterStatus, UpdatePatient, UpdatePatientsExternalID, UpdatePrimaryPatientCase.