emitter-io 1.2.0

A Python library to interact with the Emitter API.

Emitter Python SDK

This repository contains a Python client for Emitter (see also Emitter GitHub). Emitter is an open-source real-time communication service for connecting online devices. At its core, emitter.io is a distributed, scalable and fault-tolerant publish-subscribe messaging platform based on MQTT protocol and featuring message storage.

This library provides a nicer high-level MQTT interface fine-tuned and extended with specific features provided by Emitter. The code uses the Eclipse Paho MQTT Python Client for handling all the network communication and MQTT protocol.

• Installation
• Examples
• API reference
• ToDo
• License

Installation

This SDK is available as a pip package. Install with:

pip install emitter-io

Examples

These examples show you the whole communication process.

• Python 2: sample-python2.py
• Python 3: sample-python3.py

API reference

• Emitter()
  • .connect()
  • .publish()
  • .subscribe()
  • .unsubscribe()
  • .disconnect()
  • .on()
  • .presence()
  • .keygen()
• EmitterMessage()
  • .asString()
  • .asObject()
  • .asBinary()

---

Emitter()

The Emitter class represents the client connection to an Emitter server.

See Emitter#on() for the possibilities of event handling.

Events

Event 'connect'

Emitted on successful (re)connection. No arguments provided.

Event 'disconnect'

Emitted after a disconnection. No arguments provided.

Event 'message'

Emitted when the client receives a message packet. The message object will be of EmitterMessage class, encapsulating the channel and the payload.

Event 'presence'

Emitted when a presence call was made using the Emitter#presence() function. Example arguments below.

{"time": 1577833210,
 "event": "status",
 "channel": "<channel name>",
 "who": [{"id": "ABCDE12345FGHIJ678910KLMNO", "username": "User1"},
         {"id": "PQRST12345UVWXY678910ZABCD"}]}
{"time": 1577833220,
 "event": "subscribe",
 "channel": "<channel name>",
 "who": {"id": "ABCDE12345FGHIJ678910KLMNO", "username": "User1"}}
{"time": 1577833230,
 "event": "unsubscribe",
 "channel": "<channel name>",
 "who": {"id": "ABCDE12345FGHIJ678910KLMNO"}}

• time is the time of the event as Unix time.
• event is the event type: subscribe when an remote instance subscribed to the channel, unsubscribe when an remote instance unsubscribed from the channel and status when Emitter#presence() is called the first time.
• channel is the channel name.
• who in case of the event is (un)subscribe one dict with the user id, when the event is status, it is a list with the users. When more than 1000 users at the moment subscribed to the channel, 1000 randomly selected are displayed.
  • id is an internal generated id of the remote instance.
  • username is a custom chosen name by the remote instance. Please note that it is optional and check always if this parameter exists.

Event 'keygen'

ToDo: Description!

---

Emitter#connect(options={})

import emitter

instance = emitter.connect({
    "host": "api.emitter.io",
    "port": 443,
    "keepalive": 30,
    "secure": True
})

Connects to an Emitter server and returns an Emitter instance.

• host is the address of the Emitter broker. (Optional | Str | Default: "api.emitter.io")
• port is the port of the emitter broker. (Optional | Int | Default when secure: 443, otherwise: 8080)
• keepalive is the time the connection is keeped alive (Optional | Int | Default: 30)
• secure is if there should be a secure connection. It's recommend to use True. (Optional | Bool | Default: True)

---

Emitter#publish(key, channel, message, ttl=None)

instance.publish("<channel key>",
                 "<channel name>",
                 "Hello Emitter!",
                 ttl=604800) // one week

Publishes a message to a particual channel.

• key is the channel key to use for the operation. (Required | Str)
• channel is the channel name to publish to. (Required | Str)
• message is the message to publish (Required | String | Default: 30)
• ttl is the time to live of the message in seconds. When None or 0 the message will only be send to all connected instances. (Optional | Int | Default: None)

---

Emitter#subscribe(key, channel, last=None)

instance.subscribe("<channel key>",
                   "<channel name>",
                   last=5)

Subscribes to a particual channel.

• key is the channel key to use for the operation. (Required | Str)
• channel is the channel name to subscribe to. (Required | Str)
• last is the number of most recent stored messages to retrieve. (Optional | Int | Default: None)

---

Emitter#unsubscribe(key, channel)

instance.unsubscribe("<channel key>",
                     "<channel name>")

Unsubscribes from a particual channel.

• key is the channel key to use for the operation. (Required | Str)
• channel is the channel name to unsubscribe from. (Required | Str)

---

Emitter#disconnect()

instance.disconnect()

Disconnects from the connected Emitter server.

---

Emitter#on(event, callback)

Registers a callback for different events. See Emitter for a description of the events. The callbacks are all overridden when calling connect().

def connectCallback()
    print("Yeah, we connected to Emitter!")

def disconnectCallback()
    print("Oh no, we disconnected from Emitter!")

instance.on("connect", connectCallback)
instance.on("disconnect", disconnectCallback)

def messageHandler(message) # because of the f-Strings only for Python 3.6+
    print("We just recieved a message!")
    print(f"See it asString: {message.asString()}")
    print(f"See it asObject: {message.asObject()}")
    print(f"See it asBinary: {message.asBinary()}")

instance.on("message", messageHandler)

def presenceHandler(status) # because of the f-Strings only for Python 3.6+
    if status["event"] == "subscribe":
        print(f"A remote instance subscribed the channel! Details: {status}")
    elif status["event"] == "unsubscribe":
        print(f"A remote instance unsubscribed the channel! Details: {status}")
    elif status["event"] == "status":
        print(f"Presence information: {status}")

instance.on("presence", presenceHandler)

ToDo: Keygen example!

---

Emitter#presence(key, channel)

instance.presence("<channel key>",
                  "<channel name>")

Sends a presence request to the server. See also Emitter for a description of the event and Emitter#on() for the possibilities of event handling.

• key is the channel key to use for the operation. (Required | Str)
• channel is the channel name of which you want to call the presence. (Required | Str)

---

Emitter#keygen(key, channel)

instance.keygen("<master key>",
                "<channel name>")

Sends a key generation request to the server. See also Emitter for a description of the event and Emitter#on() for the possibilities of event handling.

• key is your master key to use for the operation. (Required | Str)
• channel is the channel name to generate a key for. (Required | Str)

---

EmitterMessage()

The EmitterMessage class represents a message received from the Emitter server. It contains two properties:

• channel is the channel name the message was published to. (Str)
• binary is the buffer associated with the payload. (Binary Str)

---

EmitterMessage#asString()

message.asString()

Returns the payload as a utf-8 String.

---

EmitterMessage#asObject()

message.asObject()

Returns the payload as a JSON-deserialized Python Object.

---

EmitterMessage#asBinary()

message.asBinary()

Returns the payload as a raw binary buffer.

ToDo

There are some points where the Python libary can be improved:

• Complete the presence and keygen entries in the README (see the ToDo markings)
• Add more features to reach the same feature set as the JavaScript libary (username in presence; Emitter#me() function)

License

Eclipse Public License 1.0 (EPL-1.0)

Copyright (c) 2016-2019 Misakai Ltd.