Configuration
Construct the sync or async Python client, and understand when each verifies its API key.
Sync client
from tawaguard import TawaGuard
client = TawaGuard("YOUR_API_KEY")The sync constructor verifies your key against /verify immediately by
default — a bad key raises TawaAPIError at construction time rather than
on the first scan call. Pass verify_auth=False to skip that round trip.
Supports the context manager protocol, which closes the underlying connection pool on exit:
with TawaGuard("YOUR_API_KEY") as client:
result = client.analyze("…")Async client
import asyncio
from tawaguard import AsyncTawaGuard
async def main():
async with AsyncTawaGuard("YOUR_API_KEY") as client:
result = await client.analyze("…")
asyncio.run(main())Unlike the sync client, AsyncTawaGuard() constructed directly is lazy —
it can't await a verification call inside __init__, so a bad key
doesn't surface until the first real request. To verify eagerly instead,
use one of:
# Eager: verifies immediately
client = await AsyncTawaGuard.create("YOUR_API_KEY")
# Also eager: __aenter__ verifies on entry
async with AsyncTawaGuard("YOUR_API_KEY") as client:
...
# Lazy: verification deferred to the first request
client = AsyncTawaGuard("YOUR_API_KEY")Options
client = TawaGuard(
"YOUR_API_KEY",
base_url="https://tawa.internal.acme.com/v1", # override for a private deployment
max_retries=3,
timeout=30.0,
verify_auth=True, # sync client only
)| Option | Type | Default | Description |
|---|---|---|---|
detector | str | unset | Reserved. Not sent to the service |
base_url | str | "https://gateway.tawaguard.com/v1" | API endpoint |
max_retries | int | 3 | Max retry attempts for 429/5xx responses |
timeout | float | 30.0 | Request timeout in seconds |
verify_auth | bool | True | Verify the API key against /verify on construction (sync client only) |
AsyncTawaGuard accepts the same options except verify_auth (see
above for how it verifies instead).
Unlike the TypeScript client, the Python client does not automatically
switch to a region-resolved gateway after authenticating — every request
goes to base_url for the lifetime of the client.
Error handling
All API and network errors raise TawaAPIError:
from tawaguard import TawaGuard, TawaAPIError
try:
client = TawaGuard("YOUR_API_KEY")
result = client.analyze("user input")
except TawaAPIError as err:
print(err.message) # error description
print(err.status_code) # HTTP status code (or None for network errors)
print(err.retryable) # whether a retry could succeedSee Errors & retries for the retry behavior this raises out of.
Closing the client
client.close() # sync
await client.aclose() # asyncBoth support their respective context manager protocol (with / async with),
which calls this automatically.