PubNub Python SDK 9.1.0
This page outlines the steps to follow to create a simple Hello, World application with PubNub. This covers the basics of integrating PubNub in your application: setting up a connection to PubNub, and sending and receiving messages.
PubNub account
Sign in or create an account to create an app on the Admin Portal and get the keys to use in your application.
When you create a new app, the first set of keys is generated automatically, but a single app can have as many keysets as you like. We recommend that you create separate keysets for production and test environments.
Download the SDK
Download the SDK from any of the following sources:
Use pip
To integrate PubNub into your project using pip:
pip install 'pubnub>=9.1.0'
Get the source code
https://github.com/pubnub/python/
View the supported platforms here.
Configure PubNub
In the IDE of your choice, create a new App class with the following content. This is the minimum configuration you need to send and receive messages with PubNub.
Make sure to replace myPublishKey and mySubscribeKey with your app's publish and subscribe keys from the Admin Portal.
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
config = PNConfiguration()
config.subscribe_key = '_mySubscribeKey_'
config.publish_key = '_myPublishKey_'
config.user_id = 'example'
For more information, refer to the Configuration section of the SDK documentation.
Add event listeners
Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.
Copy the following code to configure your app to print out the connection status to the console. Additionally, we added a second listener that prints the content of every received message.
# this will replace default SubscribeListener with thing that will print out messages to console
class Listener(SubscribeListener):
def status(self, pubnub, status):
print(f'Status: \n{status.category.name}')
pubnub.add_listener(Listener())
# creates a subscription
subscription = pubnub.channel('example').subscription()
subscription.on_message = lambda message: print(f'Message from {message.publisher}: {message.message}')
For more information, refer to the Listeners section of the SDK documentation.
Publish and subscribe
To receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone subscribed to that channel.
In this app, a simple "Hello from PubNub Python SDK" string is published to the "example" channel.
To subscribe to real-time updates, you must create a subscription or a subscription set and send a subscribe() call.
It is best to define the subscription before you introduce the listeners and send the subscribe() call, so place the relevant code in the appropriate places within your code.
subscription = pubnub.channel('example').subscription()
# add a listener
subscription.on_message = lambda message: print(f'Message from {message.publisher}: {message.message}')
subscription.subscribe()
time.sleep(1)
# publish
publish_result = pubnub.publish().channel("example").message("Hello from PubNub Python SDK").sync()
For more information, refer to the Publish and Subscribe section of the SDK documentation, and to Publishing a Message.
Putting it all together
Your App class should now look similar to the following:
import os
import time
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub, SubscribeListener
# this will print out the subscription status to console
class Listener(SubscribeListener):
def status(self, pubnub, status):
print(f'Status: \n{status.category.name}')
# here we create configuration for our pubnub instance
config = PNConfiguration()
Now, run your app to see if you did everything correctly. You should see the "Hello from PubNub Python SDK" message in the console.
Congratulations! You've just subscribed to a channel and sent your first message.
Walkthrough
Instead of focusing on the order in which you wrote the code, let's focus on the order in which it runs. The app you just created does a few things:
- configures a PubNub connection
- adds the
statusandmessageevent listeners - subscribes to a channel
- publishes a message
Configuring PubNub
The following code is the minimum configuration you need to send and receive messages with PubNub. For more information, refer to the Configuration section of the SDK documentation.
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
pnconfig = PNConfiguration()
pnconfig.subscribe_key = 'mySubscribeKey'
pnconfig.publish_key = 'myPublishKey'
pnconfig.user_id = "my_custom_user_id"
pubnub = PubNub(pnconfig)
Add event listeners
Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.
You added two listeners to the app: status and message. Status listens for status events and when it receives an event of type PNConnectedCategory, it prints the status to the console. The other listener, message, listens for incoming messages on a particular channel. When it receives a message, the app simply prints the received message.
# this will replace default SubscribeListener with thing that will print out messages to console
class Listener(SubscribeListener):
def status(self, pubnub, status):
print(f'Status: \n{status.category.name}')
pubnub.add_listener(Listener())
# creates a subscription
subscription = pubnub.channel('example').subscription()
subscription.on_message = lambda message: print(f'Message from {message.publisher}: {message.message}')
For more information, refer to the Listeners section of the SDK documentation.
Publishing and subscribing
PubNub uses the Publish/Subscribe model for real-time communication. This model involves two essential parts:
- Channels are transient paths over which your data is transmitted
- Messages contain the data you want to transmit to one or more recipients
When you want to receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel. In this example, you subscribe to a channel named example.
A message can be any type of JSON-serializable data (such as objects, arrays, integers, strings) that is smaller than 32 KiB. PubNub will, in most cases, deliver your message to its intended recipients in fewer than 100 ms regardless of their location. You can also share files up to 5MB.
The sample app creates a subscription, subscribes to the channel, and then calls the publish() method, which sends the "Hello from PubNub Python SDK" message.
subscription = pubnub.channel('example').subscription()
# add a listener
subscription.on_message = lambda message: print(f'Message from {message.publisher}: {message.message}')
subscription.subscribe()
time.sleep(1)
# publish
publish_result = pubnub.publish().channel("example").message("Hello from PubNub Python SDK").sync()
You can subscribe to more than one channel with a single subscribe call but in this example, you subscribe to a single channel.
For more information, refer to the Publish and Subscribe section of the SDK documentation, and to Publishing a Message.
Next steps
You have just learned how to use the Python SDK to send and receive messages using PubNub. Next, take a look at the SDK's reference documentation which covers PubNub API in more detail.