solidwebpush package

Module contents

This module lets your server send Web Push Notifications to your clients.

(Please, visit https://github.com/sergioburdisso/solidwebpush for more info).

---

class solidwebpush.Pusher(db_name='subscriptors.db', verbose=False)

Pusher objects allows you to integrate Web Push Notifications into your project.

Instantiate this class to integrate Web Push Notifications into your server. Objects of this class will create your public and private key, track your subscriptions, notify your clients, and do all the required work for you.

e.g.

>>> from solidwebpush import Pusher
>>>
>>> pusher = Pusher()
>>>
>>> #what's my base64-encoded public key?
>>> print pusher.getB64PublicKey()
>>>
>>> subscription = "{Alice's serviceWorker subscription object}"
>>>
>>> #notify Alice
>>> pusher.sendNotification(subscription, "Hello World!")
>>>
>>> #or
>>> #permanently subscribe Alice
>>> pusher.newSubscription(alice_session_id, subscription)
>>>
>>> #so that, from now on we can notify her by
>>> pusher.notify(alice_session_id, "Hello World")
>>>
>>> #or notify all the permanently subscribed clients
>>> pusher.notifyAll("Hello World")

(for more “toy” examples visit

https://github.com/sergioburdisso/solidwebpush/tree/master/examples)

getB64PrivateKey()

Base64 private key getter.

(probably you won’t care about private key at all)

Returns:Base64-encoded version of the private key Return type:str

getB64PublicKey()

Base64 public key getter.

Returns the string you’re going to use when subscribing your serviceWorker. (as long as you’re planning to decode it using JavaScript’s atob function)

Returns:Base64-encoded version of the public key Return type:str

getGroupId(session_id)

Given a session id returns the group id it belongs to.

Parameters:session_id (str) – A session id Returns:a group id value Return type:int

getIdSession(subscription)

Given a subscription object returns the session id associated with it.

Parameters:subscription (str) – The client’s subscription JSON object Returns:the session id associated with subscription Return type:str

getPrivateKey()

Raw private key getter.

(probably you won’t care about private key at all)

Returns:the raw private key Return type:str

getPublicKey()

Raw public key getter.

Returns:the raw public key Return type:str

getSubscription(session_id)

Given a session id returns the subscription object associated with it.

Parameters:session_id (str) – A session id Returns:The client’s subscription JSON object associated with the session id. Return type:str

getUrlB64PrivateKey()

Url-Safe Base64 private key getter.

(probably you won’t care about private key at all)

Returns:URLSafe-Base64-encoded version of the private key Return type:str

getUrlB64PublicKey()

Url-Safe Base64 public key getter.

This is the string you’re going to use when subscribing your serviceWorker. (so long as you’re planning to decode it using a function like urlB64ToUint8Array from https://developers.google.com/web/fundamentals/getting-started/codelabs/push-notifications/)

Returns:URLSafe-Base64-encoded version of the public key Return type:str

newSubscription(session_id, subscription, group_id=0)

Permanently subscribe a client.

Subscribes the client by permanently storing its subscription and group id (group_id). This will allow you to push notifications using the client id (session_id) instead of its subscription object.

Groups help you organize subscribers. For instance, suppose you want to notify Bob by sending a notification to all of his devices. If you previously subscribed each one of his devices to the same group let’s say 13, then calling notifyAll with 13 will push notifications to all of them:

>>> BobsGroup = 13
>>> ...
>>> pusher.newSubscription(
        BobsTabletSessionId,
        subscription0,
        BobsGroup
    )
>>> ...
>>> pusher.newSubscription(
        BobsLaptopSessionId,
        subscription1,
        BobsGroup
    )
>>> ...
>>> pusher.newSubscription(
        BobsMobileSessionId,
        subscription2,
        BobsGroup
    )
>>> ...
>>> pusher.notifyAll(BobsGroup)

Parameters:

• session_id (str) – The client’s identification (e.g. a cookie or other session token)
• subscription (str) – The client’s subscription JSON object
• group_id (int) – an optional Group ID value (0 by default)

notify(session_id, data, nonblocking=False)

Notify a given client.

Pushes a notification carrying data to the client associated with the session_id. session_id is the value passed to the newSubscription method when storing the client’s subscription object.

Parameters:

• session_id (str) – The client’s identification (e.g. a cookie or other session token)
• data (str or dict) – A string or a dict object to be sent. The dict will be automatically converted into a JSON string before being sent. An example of a dict object would be: {"title": "hey Bob!", "body": "you rock"}
• nonblocking (bool) – Whether to block the caller until this method finishes running or not.

notifyAll(data, group_id=None, exceptions=[], nonblocking=False)

Notify a group of clients.

When no group_id is given, notify all subscribers (except for those in exceptions). Otherwise, it only notifies all members of the group_id group (except for those in exceptions).

Parameters:

• data (str or dict) – A string or a dict object to be sent. The dict will be automatically converted into a JSON string before being sent. An example of a dict object would be: {"title": "hey Bob!", "body": "you rock"}
• group_id (int) – an optional Group ID value (0 by default)
• exceptions (list) – The list of sessions ids to be excluded.
• nonblocking (bool) – Whether to block the caller until this method finishes running or not.

removeSubscription(session_id)

Permanently unsubscribes a client.

Unsubscribes the client by permanently removing its subscription and group id.

Parameters:session_id (str) – The client’s identification (e.g. a cookie or other session token)

sendNotification(subscription, data, nonblocking=False)

Send the data to the Message Server.

Pushes a notification carrying data to the client associated with the subscription object. If nonblocking is True, the program won’t block waiting for the message to be completely sent. The wait() method should be used instead. (see wait() for more details)

Parameters:

• subscription (str) – the client’s subscription JSON object
• data (str or dict) – A string or a dict object to be sent. The dict will be automatically converted into a JSON string before being sent. An example of a dict object would be: {"title": "hey Bob!", "body": "you rock"}
• nonblocking (bool) – Whether to block the caller until this method finishes running or not.

sendNotificationToAll(subscriptions, data, nonblocking=False, processes=None)

Send the data to the Message Server.

Pushes a notification carrying data to each of the clients associated with the list of subscriptions. If nonblocking is True, the program won’t block waiting for all the messages to be completely sent. The wait() method should be used instead. (see wait() for more details)

Parameters:

• subscriptions (list) – The list of client’s subscription JSON object
• data (str or dict) – A string or a dict object to be sent. The dict will be automatically converted into a JSON string before being sent. An example of a dict object would be: {"title": "hey Bob!", "body": "you rock"}
• processes (int) – The [optional] number of worker processes to use. If processes is not given then the number returned by os.cpu_count() is used.
• nonblocking (bool) – Whether to block the caller until this method finishes running or not.

setVerbose(value)

Verbose mode.

Enable and disable the verbose mode (disabled by default). When verbose mode is active, some internal messages are going to be displayed, as well as the responses from the Message Server.

Parameters:value (bool) – True to enable or False to disable

wait()

Wait for all the messages to be completely sent.

Block the program and wait for all the notifications to be sent, before continuing. This only works if there exist a previous call to a method with the nonblocking parameter set to True, as shown in the following example:

>>> pusher.sendNotificationToAll(
    listOfsubscriptions,
    "Hello World",
    nonblocking=True
)
>>> # Maybe some other useful computation here
>>> pusher.wait()