Status Events for Python-Asyncio SDK
The PubNub Python-Asyncio Software Development Kit (SDK) provides status events that describe the connection state and error conditions. This page outlines the available status categories, what they mean, and the versions in which their behavior was introduced or changed.
Subscribe loop
These status events apply to the newer subscribe loop introduced in version 7.4.0 and enabled by default in version 8.0.0.
The PubNub Python SDK provides status events to notify you about the state of the SDK through the PNStatusCategory enum and PNStatus types.
Subscription-related statuses
| Status | Description | Introduced in version |
|---|---|---|
PNConnectedCategory | The connection has been established and is ready to receive real-time updates. | Introduced in 4.0.0, behavior changed in 10.3.0 |
PNDisconnectedCategory | The connection has been intentionally terminated. | Introduced in 4.0.0, behavior changed in 10.3.0 |
PNUnexpectedDisconnectCategory | The connection was unexpectedly lost. Emitted when the subscribe loop fails, the client disconnects from real-time data channels, or the reconnection retry limit is reached and the SDK stops attempting to reconnect. | Introduced in 4.0.0, behavior changed in 10.3.0 |
PNConnectionErrorCategory | Failed to establish the initial connection, with details about the error. This event is also emitted during connection failures in reconnect scenarios. | 10.3.0 |
PNSubscriptionChangedCategory | The mix of subscribed channels and channel groups has changed. | 10.3.0 |
Previous status categories
| Status | Description | Introduced in version | Behavior changed in version |
|---|---|---|---|
PNReconnectedCategory | SDK was able to reconnect to PubNub. In the newer subscribe loop, reconnection is handled with more granular statuses. | 4.0.0 | 7.4.0, 10.3.0 (enhanced) |
PNAcknowledgmentCategory | An API call was successful. This status has additional details based on the type of the successful operation. Also used in various transitions in the newer subscribe loop. | 4.0.0 | 7.4.0, 10.3.0 (enhanced) |
PNTimeoutCategory | Processing has failed because of request time out. | 4.0.0 | No significant change |
PNNetworkIssuesCategory | The SDK isn't able to reach PubNub servers due to network connectivity issues. | 4.0.0 | 10.3.0 (partially replaced by PNConnectionErrorCategory) |
PNCancelledCategory | Emitted when a subscribe operation is cancelled. | 4.0.0 | No significant change |
SDK connection lifecycle
Intermediate states like connecting and reconnecting are now handled internally without emitting specific statuses. For more general information on statuses and reconnection policies, refer to SDK Connection Lifecycle.
Other statuses
The SDK provides additional statuses for various operations:
| Status | Description |
|---|---|
PNAccessDeniedCategory | The SDK will announce this error when the Access Manager does not allow the operation. Indicates authorization failures, typically due to invalid keys or token. |
PNBadRequestCategory | PubNub API server was unable to parse SDK request correctly or request is missing required parameters like subscribe key or publish key. |
PNMalformedFilterExpressionCategory | Emitted when a filter expression is malformed. |
PNMalformedResponseCategory | Emitted when the server response is malformed. |
PNDecryptionErrorCategory | Emitted when a message decryption error occurs, usually due to incorrect crypto key. Added in 4.5.4. |
PNTLSConnectionFailedCategory | Emitted when a TLS connection fails, indicating secure connection issues. |
PNTLSUntrustedCertificateCategory | Emitted when a TLS certificate is untrusted. |
PNInternalExceptionCategory | Emitted for internal exceptions. |
PNUnknownCategory | Returned when the subscriber gets a non-200 HTTP response code from the server or for unknown error types. |
Error handling
The Python SDK uses PNStatus to provide detailed error information. When handling errors, you'll encounter various status categories like PNNetworkIssuesCategory for connectivity issues, PNTimeoutCategory for request timeouts, and PNConnectionErrorCategory for connection failures.
The status object contains properties to help identify and handle errors:
| Property | Description |
|---|---|
category | The PNStatusCategory value identifying the type of status event. |
error | Boolean indicating if this status represents an error. |
error_data | Contains detailed error information when an error occurs. |
affected_channels | List of channels affected by this status event. |
affected_groups | List of channel groups affected by this status event. |
status_code | HTTP status code if applicable. |
operation | The operation type that triggered this status. |
tls_enabled | Boolean indicating if TLS was enabled for this operation. |
uuid | The UUID associated with this operation. |
auth_key | The authentication key used for this operation. |