Skip to content

feat: add declarative reconnect flag with transport-factory auto-disable#720

Open
GregHolmes wants to merge 1 commit into
mainfrom
feat/reconnect-parity-hook
Open

feat: add declarative reconnect flag with transport-factory auto-disable#720
GregHolmes wants to merge 1 commit into
mainfrom
feat/reconnect-parity-hook

Conversation

@GregHolmes
Copy link
Copy Markdown
Contributor

@GregHolmes GregHolmes commented May 27, 2026

Summary

Adds a new reconnect: bool = True kwarg to DeepgramClient and AsyncDeepgramClient. When a custom transport_factory is provided, reconnect is auto-set to False to signal that the custom transport owns its own retry/reconnect lifecycle.

Why

Custom transports (e.g., the SageMaker transport in deepgram-python-sdk-transport-sagemaker) implement their own retry and reconnect logic — full-jitter backoff, retry-budget windows, replay buffers, etc. Stacking SDK-level retries on top of that would cause storm-on-storm behavior under burst load, which is the failure mode that motivated this parity work across the SDKs.

This adds an explicit, declarative way to express "the SDK is not responsible for reconnects." Today the Python SDK has no wrapper reconnect layer (the websockets library doesn't auto-reconnect; transports manage their own), so the flag is declarative only: it documents intent and reserves the slot for any future SDK-side reconnect logic.

Parity with other SDKs

Behavior

# Default — reconnect=True, no custom transport: SDK behaves as before
client = DeepgramClient(api_key="...")
assert client.reconnect is True

# Custom transport — reconnect auto-disabled to False
client = DeepgramClient(api_key="...", transport_factory=my_factory)
assert client.reconnect is False

# Explicit opt-in even with custom transport — caller takes responsibility
client = DeepgramClient(
    api_key="...",
    transport_factory=my_factory,
    reconnect=True,
)
assert client.reconnect is True

Test plan

Covered in tests/custom/test_transport.py:

  • Default state: client.reconnect == True
  • Explicit reconnect=False is respected
  • transport_factory auto-disables → reconnect == False
  • Explicit override transport_factory=..., reconnect=True is respected

Release impact

  • feat: → minor version bump per release-please conventions
  • Fully backwards-compatible — new optional kwarg with sensible default; existing callers need no change
  • No regen impact: hand-written patch to src/deepgram/client.py, already in .fernignore

Add `reconnect: bool = True` to DeepgramClient and AsyncDeepgramClient.
When a custom `transport_factory` is provided, `reconnect` is auto-set
to `False` to signal that the custom transport owns its own
retry/reconnect lifecycle. Stored on `self.reconnect` for inspection.

The Python SDK has no wrapper reconnect layer today (the `websockets`
library doesn't auto-reconnect; transports manage their own
reconnects), so this flag is declarative only — it documents intent
and is reserved for any future SDK-side reconnect logic. Custom
transports such as SageMaker already own their retry lifecycle, so
double-stacking SDK-side retries on top would cause storm-on-storm
under burst load.

Tests cover the default, explicit False, transport_factory
auto-disable, and the explicit-True override that opts back in.
@GregHolmes GregHolmes requested a review from lukeocodes as a code owner May 27, 2026 16:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants