pubnub-python-tools

Quickly interact with PubNub using the Python SDK.

Pre-requisites

---

For MacOS use homebrew to install packages or the following PubNub Ansible Role Python SDK that sets everything for you.

• python3
• python-tk

Install

---

To install pubnub-python-tools:

Install using pip

Install from Pypi:

pip install pubnub-python-tools

To install the testing version https://test.pypi.org/project/pubnub-python-tools/:

python -m pip install -i https://test.pypi.org/simple/ pubnub-python-tools

Testing version might be outdated or unstable.

Automatic build and install

It is recommended to setup a virtual environment.

To install locally the latest git version:

git clone https://github.com/sergio-munoz/pubnub-python-tools
chmod +x ./scripts/build_install.sh
./scripts/build_install.sh

Manually build and install

Setup a new python virtual environment and install packages in requirements_build.txt:

python -m venv build_venv
source build_venv/bin/activate
(build_venv) $ pip install -r build_requirements.txt
(build_venv) $ hatch build
(build_venv) $ pip install dist/pubnub_python_tools-${VERSION}.tar.gz

Install into a Jupyter Notebook

To install the into the Jupyter Notebook kernel:

import sys
!{sys.executable} -m pip install -U pubnub
!{sys.executable} -m pip install -U --index-url https://test.pypi.org/simple/ --no-deps pubnub-python-tools

PubNub Auth Settings

---

Always set the UUID (USER_ID) to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. Not setting the UUID can significantly impact your billing.

To run pubnub commands you need to setup your PubNub credentials using any of the following ways:

Automatically

Run the setup.sh script with your PubNub subscribe key, publish key and user_id:

$ ./scripts/install.sh $PN_SUBSCRIBE_KEY $PN_PUBLISH_KEY $PN_USER_ID

Using an .env file

Requires python-dotenv. Install using: pip install python-dotenv

If you can't see your .env file try using: ls -la

Create an .env file to avoid typing your credentials each time.

Copy the env file sample env file into your own .env (watch the dot '.') file and replace with your PubNub keys.

$ cp env .env

A minimal .env file to work properly needs at least your PubNub's subscribe key, publish key and a chosen user id:

$ cat .env

PN_SUBSCRIBE_KEY=sub-xxx-xxx
PN_PUBLISH_KEY=pub-xxx-xxx
PN_USER_ID=UUID

Manually via CLI

This has the highest precedence

Manually set cli variables before each command:

-sk $PN_SUBSCRIBE_KEY -pk $PN_PUBLISH_KEY -u $PN_USER_ID

CLI Args:

• -sk, --subscribe-key - PubNub subscribe key.
• -pk, --publish-key - PubNub publish key.
• -u, --user-id - User ID (UUID).

Overriding Global variables

This has the lowest precedence

NOTE: It is not recommended to hard-code your credentials due to security purposes.

Override the global variables manually in file pubnub_python_tools/config/module_config.py:

# OVERRIDE GLOBAL VARIABLES
SUBSCRIBE_KEY = "pub-xxx-xxx"
PUBLISH_KEY = "sub-xxx-xxx"
USER_ID = "UUID"

Sample Use

---

Run PubNub using the script: run_pn.py.

$ python ./scripts/run_pn.py -s "Space01" -p "Space01" -m "Hello from MySpace01"

Or if installed, run PubNub using the command: pubnub-python-tools.

$ pubnub-python-tools -s "Space01" -p "Space01" -m "Hello from MySpace01"

Get help using the --help flag.

$ python ./scripts/run_pn.py --help
$ pubnub-python-tools --help

Usage Examples

---

Remember to always set up your UUID USER_ID with -u.

Subscribe

Subscribe to a channel forever.

python run_pn.py -s "Space"

Publish

Publish one message to a space.

python-pubnub-tools -p "Space" -m "payload"

Publish multiple messages to a space.

python-pubnub-tools -p "Space" -mm "payload1" "payload2" "payloadN"

Publish one message to multiple spaces.

python-pubnub-tools -p "SpaceA" "SpaceB" "SpaceN" -m "payload"

Publish multiple messages to multiple spaces.

python-pubnub-tools -pm "SpaceA" "SpaceB", "SpaceN" -mm "payload1" "payload2" "payloadN"

For some reason the pubnub python sdk fails to publish when instantiated without a subscribe key, so pass it to avoid issues.

Presence

Subscribe to a channel with Presence forever.

pubnub-python-tools -s "Space" -pres

HereNow

Call Here Now on a channel.

pubnub-python-tools -here "Space"

For advanced HereNow topics see: cache busting information. NOTE: TBD SOON

Unsubscribe

Send a leave event to a channel subscribed with Presence.

python run_pn.py -us "Space"

CLI Commands Reference

From pubnub-python-tools --help:

  -h, --help            show this help message and exit
  --stop-on-fail        Stop batch operations if something goes wrong.
  --version             Current pubnub-python-tools Version
  -a ASYNC_CMD, --async-cmd ASYNC_CMD
                        Run command asynchronously using Asyncio
  -dm DEV_MAN, --dev-man DEV_MAN
                        Attach a Device Manager to file
  -here HERE_NOW, --here-now HERE_NOW
                        Here now on a Channel
  -m MESSAGE, --message MESSAGE
                        Message to publish
  -mm MULTIPLE_MESSAGES [MULTIPLE_MESSAGES ...], --multiple-messages MULTIPLE_MESSAGES [MULTIPLE_MESSAGES ...]
                        Messages to publish
  -p PUBLISH, --publish PUBLISH
                        Publish a message to a Channel
  -pk PUBLISH_KEY, --publish-key PUBLISH_KEY
                        PubNub PublishKey
  -pm PUBLISH_MULTIPLE_CHANNELS [PUBLISH_MULTIPLE_CHANNELS ...], --publish-multiple-channels PUBLISH_MULTIPLE_CHANNELS [PUBLISH_MULTIPLE_CHANNELS ...]
                        Publish to multiple Channels
  -pres, --presence     Subscribe with Presence
  -regex REGEX_ACL, --regex-acl REGEX_ACL Replace regex pattern into a PubNub regex
  -s SUBSCRIBE, --subscribe SUBSCRIBE
                        Subscribe to a Channel
  -sk SUBSCRIBE_KEY, --subscribe-key SUBSCRIBE_KEY
                        PubNub SubscribeKey
  -u UUID, --uuid UUID  PubNub UUID
  -us UNSUBSCRIBE, --unsubscribe UNSUBSCRIBE

Use Cases

---

Subscribe and Publish

Because subscribe and publish happen so fast the subscribe might not be listening when the publish was made and thus it will not be shown, but it will be published, if other devices are listening, they will reflect the changes. This is classic pub/sub behavior.

Open one terminal and run:

(venv) $ python run_pn.py -s "Space" -p "Space" -m "payload 1"

Open another terminal and run that command modified to show that the user is still subscribed the channel:

(venv) $ python run_pn.py -s "Space" -p "Space" -m "payload 2"

Dig into the logger/main_log.log to see more information.

Tests

---

Unit Tests

To all run tests use unittest:

(venv) $ python -m unittest tests/test_*

----------------------------------------------------------------------
Ran 20 tests in 30.680s

OK

Coverage

(venv) $ python -m coverage run -m unittest discover
(venv) $ python -m coverage report -i

Name                                                       Stmts   Miss  Cover
------------------------------------------------------------------------------
src/pubnub_python_tools/app/device_manager.py                 74     16    78%
src/pubnub_python_tools/app/main_app.py                       46     35    24%
src/pubnub_python_tools/app/pubnub_config.py                  16      0   100%
src/pubnub_python_tools/app/pubnub_handle_disconnects.py      29     20    31%
src/pubnub_python_tools/app/pubnub_here_now_callback.py       45      9    80%
src/pubnub_python_tools/app/pubnub_listener.py               133     73    45%
src/pubnub_python_tools/app/pubnub_manager.py                 89     33    63%
src/pubnub_python_tools/app/pubnub_manager_asyncio.py         48     11    77%
src/pubnub_python_tools/app/pubnub_on_request.py               3      0   100%
src/pubnub_python_tools/app/pubnub_publish.py                 15     11    27%
src/pubnub_python_tools/cli/v1.py                             18      0   100%
src/pubnub_python_tools/config/module_config.py               20      3    85%
src/pubnub_python_tools/logger/logging_config.py              32      9    72%
tests/__init__.py                                              4      0   100%
tests/test_device_manager.py                                  67      0   100%
tests/test_main_app.py                                         9      0   100%
tests/test_pubnub_manager.py                                  79      0   100%
tests/test_pubnub_manager_asyncio.py                         102     10    90%
tests/test_request_function.py                                15      0   100%
tests/test_v1.py                                              32      0   100%
------------------------------------------------------------------------------
TOTAL                                                        876    230    74%

6 empty files skipped.