Python SDK

Requires Python 3.12 or newer. The current client is asynchronous; a synchronous client is not provided. Follow SDK installation to install from PyPI.

import asyncio
from tabsail import AsyncTabSail, RequestOptions

async def main():
    async with AsyncTabSail() as client:
        async with client.with_session(
            timeout_seconds=300,
            wait_for_capacity=True,
            options=RequestOptions(timeout_ms=120000),
        ) as session:
            print(session.id)

asyncio.run(main())

This complete example verifies acquisition and release. Add your browser-client actions inside the owned-session scope.

Configuration and ownershipCopy Anchor Link

AsyncTabSail accepts keyword arguments base_url, api_key, request_timeout_ms, max_retries, and an optional HTTP transport. The two environment variables supply omitted credentials. The SDK appends /v1 and does not load .env files.

The client context closes its local HTTP pool. Explicitly created remote sessions remain your responsibility. The with_session context owns its acquired session and performs independent cleanup.

MethodsCopy Anchor Link

• Sessions: create, get, list, close, watch.
• Lifecycle: wait_until_ready, wait_until_released, wait_for_handoff.
• Connections: sessions.connections.create.
• Handoffs: sessions.handoffs.create, get, complete, wait_until_completed.
• Files: sessions.files.upload, list, get, download, delete.

create accepts keyword creation fields timeout_seconds, viewport, metadata, and region. List methods take keyword limit/cursor and status or origin filters. Resource methods accept an optional options=RequestOptions(...).

connections.create defaults to type="cdp". Live requests additionally use mode="view" or mode="control" with handoff_id.

Waits and checkpointsCopy Anchor Link

Wait helpers accept timeout_ms and poll_interval_ms. Pass after=HandoffCheckpoint.from_session(stable_session) to wait_for_handoff. Use a new stable checkpoint after each completed handoff.

with_session accepts ready_timeout_ms, cleanup_timeout_ms, poll_interval_ms, and wait_for_capacity. Pass the total acquisition budget through RequestOptions rather than an unsupported direct timeout_ms keyword.

watch is an async iterator. If you can exit early, wrap it with contextlib.aclosing so the local subscription is deterministically closed. This does not close the browser.

File streamsCopy Anchor Link

upload accepts bytes, pathlib.Path, or an open binary file. The SDK opens and closes Path inputs; the caller owns an already opened file object.

download is used as an async context manager. DownloadStream exposes content_type, content_length, is_closed, aiter_bytes, and aclose. Stream bytes before closing the browser.

Models and errorsCopy Anchor Link

Models use snake_case properties while HTTP uses camelCase. See Resource models.

Exported errors are SDKError, APIError, ConfigurationError, NetworkError, RequestTimeoutError, WaitTimeoutError, ProtocolError, RequestCancelledError, ResultUnknownError, SessionTerminatedError, HandoffCancelledError, and CleanupError.

Error attributes include code, status, retryable, request_id, retry_after, and session_id when available. Unknown results preserve recovery details.

If business work succeeded but cleanup failed, the owned helper raises CleanupError. If work or cancellation already failed, it propagates that original exception and attaches CleanupError as its cleanup_error attribute, with session_id and idempotency_key for recovery. Inspect both paths rather than assuming that catching CleanupError alone covers every outstanding cleanup.