用于 Python 的推送通道 HTTP API 库
This package lets you trigger events to your client and query the state of your channels. When used with a server, you can validate webhooks and authenticate private- or presence- channels.
In order to use this library, you need to have a free account on . After registering, you will need the application credentials for your app.
You can install this module using your package management method or choice,
normally easy_install or pip. For example:
pip install pusherNote: Python 2 is no longer supported. Python 2 reached end-of-life on January 1, 2020. This library requires Python 3.6+.
The minimum configuration required to use the Pusher object are the three
constructor arguments which identify your Pusher Channels app. You can find them by
going to "API Keys" on your app at .
import pusher
pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', cluster=u'cluster')You can then trigger events to channels. Channel and event names may only
contain alphanumeric characters, - and _:
pusher_client.trigger(u'a_channel', u'an_event', {u'some': u'data'})import pusher
pusher_client = pusher.Pusher(app_id, key, secret, cluster=u'cluster')| Argument | Description |
|---|---|
app_id String |
Required |
| The Pusher Channels application ID | |
key String |
Required |
| The Pusher Channels application key | |
secret String |
Required |
| The Pusher Channels application secret token | |
cluster String |
Default:mt1 |
The pusher application cluster. Will be overwritten if host is set |
|
host String |
Default:None |
| The host to connect to | |
port int |
Default:None |
| Which port to connect to | |
ssl bool |
Default:True |
| Use HTTPS | |
String |
Default:None |
Deprecated, see encryption_master_key_base64 |
|
encryption_master_key_base64 String |
Default:None |
| The encryption master key for End-to-end Encryption | |
backend Object |
an object that responds to the send_request(request) method. If none is provided, a pusher.requests.RequestsBackend instance is created. |
json_encoder Object |
Default: None |
| Custom JSON encoder. | |
json_decoder Object |
Default: None |
| Custom JSON decoder. |
The constructor will throw a TypeError if it is called with parameters that don’t match the types listed above.
import pusher
pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', ssl=True, cluster=u'cluster')To trigger an event on one or more channels, use the trigger method on the Pusher object.
Pusher::trigger| Argument | Description |
|---|---|
channels String or Collection |
Required |
| The name or list of names of the channel you wish to trigger events on | |
event String |
Required |
| The name of the event you wish to trigger. | |
data JSONable data |
Required |
| The event's payload | |
socket_id String |
Default:None |
| The socket_id of the connection you wish to exclude from receiving the event. You can read more here. |
| Return Values | Description |
|---|---|
buffered_events Dict |
A parsed response that includes the event_id for each event published to a channel. See example. |
Pusher::trigger will throw a TypeError if called with parameters of the wrong type; or a ValueError if called on more than 100 channels, with an event name longer than 200 characters, or with more than 10240 characters of data (post JSON serialisation).
This call will trigger to 'a_channel' and 'another_channel', and exclude the recipient with socket_id "1234.12".
pusher_client.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")Pusher::trigger_batchIt's also possible to send distinct messages in batches to limit the overhead of HTTP headers. There is a current limit of 10 events per batch on our multi-tenant clusters.
| Argument | Description |
|---|---|
batch Array of Dict |
Required |
| A list of events to trigger |
Events are a Dict with keys:
| Argument | Description |
|---|---|
channel String |
Required |
| The name of the channel to publish to. | |
name String |
Required |
| The name of the event you wish to trigger. | |
data JSONable data |
Required |
| The event's payload | |
socket_id String |
Default:None |
| The socket_id of the connection you wish to exclude from receiving the event. You can read more here. |
| Return Values | Description |
|---|---|
Dict |
An empty dict on success |
Pusher::trigger_batch will throw a TypeError if the data parameter is not JSONable.
pusher_client.trigger_batch([
{ u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'data'}, u'socket_id': '1234.12'},
{ u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'other data'}}
])Pusher::send_to_user| Argument | Description |
|---|---|
user_id String |
Required |
| The user id | |
event String |
Required |
| The name of the event you wish to trigger. | |
data JSONable data |
Required |
| The event's payload |
| Return Values | Description |
|---|---|
buffered_events Dict |
A parsed response that includes the event_id for each event published to a channel. See example. |
Pusher::trigger will throw a TypeError if called with parameters of the wrong type; or a ValueError if called on more than 100 channels, with an event name longer than 200 characters, or with more than 10240 characters of data (post JSON serialisation).
This call will send a message to the user with id '123'.
pusher_client.send_to_user( u'123', u'some_event', {u'message': u'hello worlds'})Pusher::channels_info| Argument | Description |
|---|---|
prefix_filter String |
Default: None |
| Filter the channels returned by their prefix | |
attributes Collection |
Default: [] |
| A collection of attributes which should be returned for each channel. If empty, an empty dictionary of attributes will be returned for each channel. | |
Available attributes: "user_count". |
| Return Values | Description |
|---|---|
channels Dict |
A parsed response from the HTTP API. See example. |
Pusher::channels_info will throw a TypeError if prefix_filter is not a String.
channels = pusher_client.channels_info(u"presence-", [u'user_count'])
#=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}Pusher::channel_info| Argument | Description |
|---|---|
channel String |
Required |
| The name of the channel you wish to query | |
attributes Collection |
Default: [] |
| A collection of attributes to be returned for the channel. |
Available attributes:
"user_count" : Number of distinct users currently subscribed. Applicable only to presence channels.
"subscription_count": Number of connections currently subscribed to the channel. Enable this feature in your Pusher dashboard's App Settings.
| Return Values | Description |
|---|---|
channel Dict |
A parsed response from the HTTP API. See example. |
Pusher::channel_info will throw a ValueError if channel is not a valid channel.
channel = pusher_client.channel_info(u'presence-chatroom', [u"user_count"])
#=> {u'user_count': 42, u'occupied': True}Pusher::users_info| Argument | Description |
|---|---|
channel String |
Required |
| The name of the presence channel you wish to query |
| Return Values | Description |
|---|---|
users Dict |
A parsed response from the HTTP API. See example. |
Pusher::users_info will throw a ValueError if channel is not a valid channel.
pusher_client.users_info(u'presence-chatroom')
#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}Pusher::authenticateIn order for users to subscribe to a private- or presence-channel, they must be authenticated by your server.
The client will make a POST request to an endpoint (either "/pusher/auth" or any which you specify) with a body consisting of the channel's name and socket_id.
Using your Pusher instance, with which you initialized Pusher, you can generate an authentication signature. Having responded to the request with this signature, the subscription will be authenticated.
| Argument | Description |
|---|---|
channel String |
Required |
| The name of the channel, sent to you in the POST request | |
socket_id String |
Required |
| The channel's socket_id, also sent to you in the POST request | |
custom_data Dict |
Required for presence channels |
This will be a dictionary containing the data you want associated with a member of a presence channel. A "user_id" key is required, and you can optionally pass in a "user_info" key. See the example below. |
| Return Values | Description |
|---|---|
response Dict |
A dictionary to send as a response to the authentication request. |
Pusher::authenticate will throw a ValueError if the channel or socket_id that it’s called with are invalid.
auth = pusher_client.authenticate(
channel=u"private-channel",
socket_id=u"1234.12"
)
# return `auth` as a responseauth = pusher_client.authenticate(
channel=u"presence-channel",
socket_id=u"1234.12",
custom_data={
u'user_id': u'1',
u'user_info': {
u'twitter': '@pusher'
}
}
)
# return `auth` as a responsePusher::authenticate_userTo authenticate users on Pusher Channels on your application, you can use the authenticate_user function:
| Argument | Description |
|---|---|
socket_id String |
Required |
| The channel's socket_id, also sent to you in the POST request | |
user_data Dict |
Required for presence channels |
| This will be a |
暂无开放 Issues,或尚未同步最近议题。