API Reference¶
Client¶
-
class
aiosfstream.
SalesforceStreamingClient
(*, consumer_key, consumer_secret, username, password, replay=<ReplayOption.NEW_EVENTS: -1>, replay_fallback=None, connection_timeout=10.0, max_pending_count=100, sandbox=False, json_dumps=<function dumps>, json_loads=<function loads>, loop=None)[source]¶ Salesforce Streaming API client with username/password authentication
This is a convenience class which is suitable for the most common use case. To use a different authentication method, use the general
Client
class with a differentAuthenticator
Parameters: - consumer_key (str) – Consumer key from the Salesforce connected app definition
- consumer_secret (str) – Consumer secret from the Salesforce connected app definition
- username (str) – Salesforce username
- password (str) – Salesforce password
- replay (ReplayOption, ReplayMarkerStorage, collections.abc.MutableMapping or None) – A ReplayOption or an object capable of storing replay ids if you want to take advantage of Salesforce’s replay extension. You can use one of the
ReplayOptions
, or an object that supports the MutableMapping protocol likedict
,defaultdict
,Shelf
etc. or a customReplayMarkerStorage
implementation. - replay_fallback (ReplayOption) – Replay fallback policy, for when a subscribe operation fails because a replay id was specified for a message outside the retention window
- connection_timeout (int, float or None) – The maximum amount of time to wait for the transport to re-establish a connection with the server when the connection fails.
- max_pending_count (int) – The maximum number of messages to prefetch from the server. If the number of prefetched messages reach this size then the connection will be suspended, until messages are consumed. If it is less than or equal to zero, the count is infinite.
- sandbox (bool) – Marks whether the connection has to be made with a sandbox org or with a production org
- json_dumps (
callable()
) – Function for JSON serialization, the default isjson.dumps()
- json_loads (
callable()
) – Function for JSON deserialization, the default isjson.loads()
- loop – Event
loop
used to schedule tasks. If loop isNone
thenasyncio.get_event_loop()
is used to get the default event loop.
-
class
aiosfstream.
Client
(authenticator, *, replay=<ReplayOption.NEW_EVENTS: -1>, replay_fallback=None, connection_timeout=10.0, max_pending_count=100, json_dumps=<function dumps>, json_loads=<function loads>, loop=None)[source]¶ Salesforce Streaming API client
Parameters: - authenticator (AuthenticatorBase) – An authenticator object
- replay (ReplayOption, ReplayMarkerStorage, collections.abc.MutableMapping or None) – A ReplayOption or an object capable of storing replay ids if you want to take advantage of Salesforce’s replay extension. You can use one of the
ReplayOptions
, or an object that supports the MutableMapping protocol likedict
,defaultdict
,Shelf
etc. or a customReplayMarkerStorage
implementation. - replay_fallback (ReplayOption) – Replay fallback policy, for when a subscribe operation fails because a replay id was specified for a message outside the retention window
- connection_timeout (int, float or None) – The maximum amount of time to wait for the transport to re-establish a connection with the server when the connection fails.
- max_pending_count (int) – The maximum number of messages to prefetch from the server. If the number of prefetched messages reach this size then the connection will be suspended, until messages are consumed. If it is less than or equal to zero, the count is infinite.
- json_dumps (
callable()
) – Function for JSON serialization, the default isjson.dumps()
- json_loads (
callable()
) – Function for JSON deserialization, the default isjson.loads()
- loop – Event
loop
used to schedule tasks. If loop isNone
thenasyncio.get_event_loop()
is used to get the default event loop.
-
coroutine
open
()[source]¶ Establish a connection with the Streaming API endpoint
Raises: - ClientError – If none of the connection types offered by the server are supported
- ClientInvalidOperation – If the client is already open, or in other words if it isn’t
closed
- TransportError – If a network or transport related error occurs
- ServerError – If the handshake or the first connect request gets rejected by the server.
- AuthenticationError – If the server rejects the authentication request or if a network failure occurs during the authentication
-
coroutine
publish
(channel, data)[source]¶ Publish data to the given channel
Warning
The Streaming API is implemented on top of CometD. The publish operation is a CometD operation. While it’s still a legal operation, Salesforce chose not to implement the publishing of Generic Streaming and Platform events with CometD.
You should use the REST API to generate Generic Streaming events, or use the REST or SOAP API to publish Platform events.
Parameters: Returns: Publish response
Return type: Raises: - ClientInvalidOperation – If the client is
closed
- TransportError – If a network or transport related error occurs
- ServerError – If the publish request gets rejected by the server
- ClientInvalidOperation – If the client is
-
coroutine
subscribe
(channel)[source]¶ Subscribe to channel
Parameters: channel (str) – Name of the channel
Raises: - ClientInvalidOperation – If the client is
closed
- TransportError – If a network or transport related error occurs
- ServerError – If the subscribe request gets rejected by the server
- ClientInvalidOperation – If the client is
-
coroutine
unsubscribe
(channel)[source]¶ Unsubscribe from channel
Parameters: channel (str) – Name of the channel
Raises: - ClientInvalidOperation – If the client is
closed
- TransportError – If a network or transport related error occurs
- ServerError – If the unsubscribe request gets rejected by the server
- ClientInvalidOperation – If the client is
-
coroutine
receive
()[source]¶ Wait for incoming messages from the server
Returns: Incoming message
Return type: Raises: - ClientInvalidOperation – If the client is closed, and has no more pending incoming messages
- ServerError – If the client receives a confirmation message which is not
successful
- TransportTimeoutError – If the transport can’t re-establish connection with the server in
connection_timeout
time.
-
closed
¶ Marks whether the client is open or closed
-
subscriptions
¶ Set of subscribed channels
-
connection_type
¶ The current connection type in use if the client is open, otherwise
None
-
pending_count
¶ The number of pending incoming messages
Once
open
is called the client starts listening for messages from the server. The incoming messages are retrieved and stored in an internal queue until they get consumed by callingreceive
.
-
has_pending_messages
¶ Marks whether the client has any pending incoming messages
Authenticators¶
-
class
aiosfstream.auth.
AuthenticatorBase
(sandbox=False, json_dumps=<function dumps>, json_loads=<function loads>)[source]¶ Abstract base class to serve as a base for implementing concrete authenticators
Parameters: - sandbox (bool) – Marks whether the authentication has to be done for a sandbox org or for a production org
- json_dumps (
callable()
) – Function for JSON serialization, the default isjson.dumps()
- json_loads (
callable()
) – Function for JSON deserialization, the default isjson.loads()
-
class
aiosfstream.
PasswordAuthenticator
(consumer_key, consumer_secret, username, password, sandbox=False, json_dumps=<function dumps>, json_loads=<function loads>)[source]¶ Authenticator for using the OAuth 2.0 Username-Password Flow
Parameters: - consumer_key (str) – Consumer key from the Salesforce connected app definition
- consumer_secret (str) – Consumer secret from the Salesforce connected app definition
- username (str) – Salesforce username
- password (str) – Salesforce password
- sandbox (bool) – Marks whether the authentication has to be done for a sandbox org or for a production org
- json_dumps (
callable()
) – Function for JSON serialization, the default isjson.dumps()
- json_loads (
callable()
) – Function for JSON deserialization, the default isjson.loads()
-
client_id
= None¶ OAuth2 client id
-
client_secret
= None¶ OAuth2 client secret
-
password
= None¶ Salesforce password
-
username
= None¶ Salesforce username
-
class
aiosfstream.
RefreshTokenAuthenticator
(consumer_key, consumer_secret, refresh_token, sandbox=False, json_dumps=<function dumps>, json_loads=<function loads>)[source]¶ Authenticator for using the OAuth 2.0 Refresh Token Flow
Parameters: - consumer_key (str) – Consumer key from the Salesforce connected app definition
- consumer_secret (str) – Consumer secret from the Salesforce connected app definition
- refresh_token (str) – A refresh token obtained from Salesforce by using one of its authentication methods (for example with the OAuth 2.0 Web Server Authentication Flow)
- sandbox (bool) – Marks whether the authentication has to be done for a sandbox org or for a production org
- json_dumps (
callable()
) – Function for JSON serialization, the default isjson.dumps()
- json_loads (
callable()
) – Function for JSON deserialization, the default isjson.loads()
-
client_id
= None¶ OAuth2 client id
-
client_secret
= None¶ OAuth2 client secret
-
refresh_token
= None¶ Salesforce refresh token
Replay¶
-
class
aiosfstream.
ReplayOption
[source]¶ Replay options supported by Salesforce
-
ALL_EVENTS
= -2¶ Receive all events, including past events that are within the 24-hour retention window and new events sent after subscription
-
NEW_EVENTS
= -1¶ Receive new events that are broadcast after the client subscribes
-
-
class
aiosfstream.
ReplayMarker
(date, replay_id)¶ Bases:
tuple
Class for storing a message replay id and its creation date
Parameters: -
date
¶ Alias for field number 0
-
replay_id
¶ Alias for field number 1
-
-
class
aiosfstream.
ReplayMarkerStorage
[source]¶ Abstract base class for replay marker storage implementations
-
coroutine
get_replay_marker
(subscription)[source]¶ Retrieve a stored replay marker for the given subscription
Parameters: subscription (str) – Name of the subscribed channel Returns: A replay marker or None
if there is nothing stored for the given subscriptionReturn type: ReplayMarker or None
-
coroutine
set_replay_marker
(subscription, replay_marker)[source]¶ Store the replay_marker for the given subscription
Parameters: - subscription (str) – Name of the subscribed channel
- replay_marker (ReplayMarker) – A replay marker
-
coroutine
-
class
aiosfstream.
MappingStorage
(mapping)[source]¶ Mapping based replay marker storage
Parameters: mapping (collections.abc.MutableMapping) – A MutableMapping object for storing replay markers
-
class
aiosfstream.
DefaultMappingStorage
(mapping, default_id)[source]¶ Mapping based replay marker storage which will return a defualt replay id if there is not replay marker for the given subscription
Parameters: - mapping (collections.abc.MutableMapping) – A MutableMapping object for storing replay markers
- default_id (int) – A replay id
Exceptions¶
Exception types
Exception hierarchy:
AiosfstreamException
AuthenticationError
ClientError
ClientInvalidOperation
TransportError
TransportInvalidOperation
TransportTimeoutError
TransportConnectionClosed
ServerError
-
exception
aiosfstream.exceptions.
AiosfstreamException
[source]¶ Base exception type.
All exceptions of the package inherit from this class.
-
exception
aiosfstream.exceptions.
ClientInvalidOperation
[source]¶ The requested operation can’t be executed on the current state of the client
-
exception
aiosfstream.exceptions.
TransportError
[source]¶ Error during the transportation of messages
-
exception
aiosfstream.exceptions.
TransportInvalidOperation
[source]¶ The requested operation can’t be executed on the current state of the transport
-
exception
aiosfstream.exceptions.
TransportConnectionClosed
[source]¶ The connection unexpectedly closed