Models

Attributes

• conduit
• id
• shard_count
• websockets

Methods

• async forfetch_shards
• asyncupdate_shard_count

class twitchio.ConduitInfo

A special class wrapping Conduit assigned only to AutoClient and AutoBot.

This class serves as an abstraction layer to managing the Conduit assigned to AutoClient or AutoBot and contains various information and helper methods.

Warning

The should not need to create this class yourself. Instead you can access it via conduit_info.

property conduit: twitchio.models.eventsub_.Conduit | None

A property returning the Conduit that the AutoClient currently has ownership of. Could be None if a conduit has not yet been assigned, however this is usually done automatically during the startup stages of the AutoClient.

property shard_count: int | None

Property returning the amount of shards the AutoClient currently contains as an int. Could be None if a conduit has not yet been assigned, however this is usually done automatically during the startup stages of the AutoClient.

property id: str | None

Property returning the ID of the Conduit that the AutoClient currently has ownership of. Could be None if a conduit has not yet been assigned, however this is usually done automatically during the startup stages of the AutoClient.

property websockets: mappingproxy[str, twitchio.eventsub.websockets.Websocket]

Property returning a mapping of Websocket Shard-ID to Websocket that are currently active and assigned to the underlying Conduit.

Warning

This property exists only for those requiring lower level access over the underlying websocket(s); however ideally the websocket(s) should not be altered or interfered with. The mapping and property itself cannot be altered.

async update_shard_count(shard_count: int, /, *, assign_transports: bool = True) → Self

This function is a coroutine.

Method wrapping twitchio.Conduit.update() which updates the number of shards assigned to the Conduit. This method can be used to scale the Conduit up (more shards) or down with less shards.

Warning

Caution should be used when scaling multi-process solutions that connect to the same Conduit. In this particular case it is more likely appropriate to close down and restart each instance and adjust the shard_ids parameter on AutoClient accordingly. However this method can be called with assign_transports=False first to allow each instance to easily adjust when restarted.

Parameters

• shard_count (int) – A positional-only int which is the new amount of shards the Conduit should contain. The amount of shards should be between 1 and 20_000.

• assign_transports (bool) – A keyword-only bool set which determines whether new websockets should be created and assigned to the Conduit. This should be set to False in multi-instance/process setups that require the AutoClient’s to be restarted to rebalance shards accordingly. Defaults to True which is the best case for a single instance of AutoClient.

Raises

• MissingConduit – No Conduit has been assigned to the AutoClient.

• ValueError – The shard_count parameter cannot be lower than 1 and no higher than 20_000.

• HTTPException – A an error occurred making the request to Twitch.

Returns

Returns the updated ConduitInfo and allows for chaining methods and attributes.

Return type

ConduitInfo

fetch_shards(*, status: ShardStatus | None = None) → HTTPAsyncIterator[ConduitShard]

This function returns a HTTPAsyncIterator

Method wrapping twitchio.Conduit.fetch_shards() which returns the shard info for the Conduit retrieved from the Twitch API.

Note

The Shard ID’s contained in the objects returned from this method may differ to the shard ID’s associated with websockets. If you need to compare, each websocket has an attribute named session_id which can be used instead.

Status	Description
enabled	The shard is enabled.
webhook_callback_verification_pending	The shard is pending verification of the specified callback URL.
webhook_callback_verification_failed	The specified callback URL failed verification.
notification_failures_exceeded	The notification delivery failure rate was too high.
websocket_disconnected	The client closed the connection.
websocket_failed_ping_pong	The client failed to respond to a ping message.
websocket_received_inbound_traffic	The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
websocket_internal_error	The Twitch WebSocket server experienced an unexpected error.
websocket_network_timeout	The Twitch WebSocket server timed out writing the message to the client.
websocket_network_error	The Twitch WebSocket server experienced a network error writing the message to the client.
websocket_failed_to_reconnect	The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.

Parameters

status (str) – An optional str which when provided, filters the shards by their status on the API. Possible statuses are listed above. Defaults to None which fetches all shards.

Returns

An HTTPAsyncIterator which can be awaited or used with async for to retrieve the ConduitShard’s.

Return type

HTTPAsyncIterator[ConduitShard]

Raises

• MissingConduit – No Conduit has been assigned to the AutoClient.

• HTTPException – An error occurred making the request to Twitch.

Attributes

• id
• raw
• shard_count

Methods

• asyncdelete
• async forfetch_shards
• asyncupdate

class twitchio.Conduit

The Conduit model which is returned from various API endpoints relating to Conduits on Twitch.

This class can be used to manage the underlying Conduit, however for a more intuitive approach see: AutoClient or AutoBot which wraps this class and provides a ConduitInfo class instead.

Supported Operations

Operation	Usage(s)	Description
__str__	str(conduit), f"{conduit}"	Return the official str represntation.
__repr__	repr(conduit), f"{conduit!r}"	Return the official represntation.
__eq__	conduit == other, conduit != other	Compare equality of two conduits.

raw

The raw response from Twitch which was used to create this class.

Type

dict[Any, Any]

shard_count

The amount of shards assigned to this conduit.

Type

int

property id: str

Property returning the Conduit ID as a str.

async delete() → None

This function is a coroutine.

Method to delete the associated Conduit from the API.

Returns

Successfully removed the Conduit

Return type

None

Raises

HTTPException – 404 - Conduit was not found or you do not own this Conduit.

async update(shard_count: int, /) → Conduit

This function is a coroutine.

Method which updates the underlying Conduit on the Twitch API with the provided shard_count.

Important

If you are using AutoClient or AutoBot this will not update the underlying websocket connections. See: update_shard_count() instead.

Parameters

shard_count (int) – The new amount of shards the Conduit should be assigned. Should be between 1 and 20_000.

Raises

ValueError – shard_count must be between 1 and 20_000.

Returns

The updated Conduit.

Return type

Conduit

fetch_shards(*, status: ShardStatus | None = None) → HTTPAsyncIterator[ConduitShard]

This function returns a HTTPAsyncIterator

Method which returns the shards for the Conduit retrieved from the Twitch API.

Status	Description
enabled	The shard is enabled.
webhook_callback_verification_pending	The shard is pending verification of the specified callback URL.
webhook_callback_verification_failed	The specified callback URL failed verification.
notification_failures_exceeded	The notification delivery failure rate was too high.
websocket_disconnected	The client closed the connection.
websocket_failed_ping_pong	The client failed to respond to a ping message.
websocket_received_inbound_traffic	The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
websocket_internal_error	The Twitch WebSocket server experienced an unexpected error.
websocket_network_timeout	The Twitch WebSocket server timed out writing the message to the client.
websocket_network_error	The Twitch WebSocket server experienced a network error writing the message to the client.
websocket_failed_to_reconnect	The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.

Parameters

status (str) – An optional str which when provided, filters the shards by their status on the API. Possible statuses are listed above. Defaults to None which fetches all shards.

Returns

An HTTPAsyncIterator which can be awaited or used with async for to retrieve the ConduitShard’s.

Return type

HTTPAsyncIterator[ConduitShard]

Raises

HTTPException – An error occurred making the request to Twitch.

Attributes

• callback
• connected_at
• disconnected_at
• id
• method
• raw
• session_id
• status

class twitchio.ConduitShard

ConduitShard model containing various information about a Shard on a Conduit.

raw

The raw data retrieved from Twitch.

Type

dict[str, Any]

id

The ID of the shard. Will be a nummeric str between 0 and 19_999.

Type

str

method

A str literal of either websocket or webhook, indicating what transport this shard uses.

Type

str

session_id

If method == websocket, this will be the session_id of the websocket. Could be None if the shard is not connected or method == webhook.

Type

str | None

connected_at

A datetime.datetime of when the shard was connected in UTC. Only availabe when method == websocket.

Type

datetime.datetime | None

disconnected_at

A datetime.datetime of when the shard was lost connection in UTC. Only availabe when method == websocket.

Type

datetime.datetime | None

callback

The URL that notifications for the shard are sent via Webhooks. Only availabe when method == webhook.

Type

str | None

property status: ShardStatus

Property returning the status of the shard.

The possible statuses are provided below.

Status	Description
enabled	The shard is enabled.
webhook_callback_verification_pending	The shard is pending verification of the specified callback URL.
webhook_callback_verification_failed	The specified callback URL failed verification.
notification_failures_exceeded	The notification delivery failure rate was too high.
websocket_disconnected	The client closed the connection.
websocket_failed_ping_pong	The client failed to respond to a ping message.
websocket_received_inbound_traffic	The client sent a non-pong message. Clients may only send pong messages (and only in response to a ping message).
websocket_internal_error	The Twitch WebSocket server experienced an unexpected error.
websocket_network_timeout	The Twitch WebSocket server timed out writing the message to the client.
websocket_network_error	The Twitch WebSocket server experienced a network error writing the message to the client.
websocket_failed_to_reconnect	The client failed to reconnect to the Twitch WebSocket server within the required time after a Reconnect Message.

Attributes

• errors
• success

class twitchio.MultiSubscribePayload

Payload received from the multi_subscribe() method.

This payload contains a list of MultiSubscribeSuccess which are the successful subscriptions and another list of MultiSubscribeError which are any subscriptions that failed.

This payload is only returned when the parameters wait is set to True and stop_on_error is False in multi_subscribe().

If the wait parameter in multi_subscribe() is set to False, you can await the returned asyncio.Task later to retrieve this payload.

success

A list of MultiSubscribeSuccess containing information about the successful subscriptions.

Type

list[MultiSubscribeSuccess]

errors

A list of MultiSubscribeError containing information about unsuccessful subscriptions.

Type

list[MultiSubscribeError]

Attributes

• response
• subscription

class twitchio.MultiSubscribeSuccess

A special typing.NamedTuple containing two fields available in the MultiSubscribePayload, when a subscription to a Conduit is made successfully via multi_subscribe().

subscription

The subscription payload passed to multi_subscribe() which was successfully subscribed to.

Type

SubscriptionPayload

response

The response data from the subscription received from Twitch.

Type

dict[str, Any]

Attributes

• error
• subscription

class twitchio.MultiSubscribeError

A special typing.NamedTuple containing two fields available in the MultiSubscribePayload, when a subscription to a Conduit is attempted via multi_subscribe() and fails.

subscription

The subscription payload passed to multi_subscribe() which failed.

Type

SubscriptionPayload

error

The HTTPException containing various information, caught while attempting to subscribe to this subscription.

Type

HTTPException