Package: emitter-io
Emitter Python SDKThis repository contains a Python client forEmitter(see alsoEmitter GitHub). Emitter is anopen-sourcereal-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 byEmitter. The code uses theEclipse Paho MQTT Python Clientfor handling all the network communication and MQTT protocol.InstallationExamplesAPI referenceToDoLicenseInstallationThis SDK is available as a pip package. Install with:pip install emitter-ioExamplesThese examples show you the whole communication process.Python 2:sample-python2.pyPython 3:sample-python3.pyAPI referenceClient().connect().disconnect().keyban().keygen().link().me().on_connect.on_disconnect.on_error.on_keyban.on_keygen.on_me.on_message.on_presence.presence().publish().publish_with_link().subscribe().subscribe_with_group().unsubscribe()EmitterMessage().as_string().as_object().as_binary()Client()TheClientclass represents the client connection to an Emitter server.Emitter#connect(host="api.emitter.io", port=443, secure=True, keepalive=30)emitter=Client()emitter.connect()Connects to an Emitter server.hostis the address of the Emitter broker. (Optional |Str| Default:"api.emitter.io")portis the port of the emitter broker. (Optional |Int| Default:443)securewhether the connection should be secure. (Optional |Bool| Default:True)keepaliveis the time the connection is kept alive (Optional |Int| Default:30)If you don't want a secure connection, set the port to 8080, unless your broker is configured differently.To handle connection events, see the.on_connectproperty.Emitter#disconnect()emitter.disconnect()Disconnects from the connected Emitter server.To handle disconnection events, see the.on_disconnectproperty.Emitter#keyban(master_key, target_key, ban)instance.keyban("MEj8QNnzy6pKtE887hpXbD0KyKXi4w4f","ftibXtPMKXI5p2FjhyINf8tvl2GAHaNG",True)Sends a request to ban/unban a channel key.master_keyis yourmaster keyto use for the operation. (Required |Str)target_keyis the key ban or unban. (Required |Str)banis whether to ban or unban the key. (Required |Bool)To handle keyban responses, see the.on_keybanproperty.
It will take a minute for the change to take effect.Emitter#keygen(key, channel, permissions, ttl=0)instance.keygen("Z5auMQhNr0eVnGBAgWThXus1dgtSsvuQ","channel/","rwslpex")Sends a key generation request to the server.keyis yourmaster keyto use for the operation. (Required |Str)channelis the channel name to generate a key for. (Required |Str)permissionsare the permissions associated to the key. (Required |Str)rfor readwfor writesfor storelfor loadpfor presenceefor extendxfor executettlis the time to live of the key.0means it never expires (Optional |Int| Default:0)To handle keygen responses, see the.on_keygenproperty.
Requesting a keygen with an extendable channel creates a private channel.Emitter#link(key, channel, name, private, subscribe, options={})instance.link("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb","channel","a0",True,{Client.with_ttl(604800),Client.without_echo()})//oneweekSends a link creation request to the server. This allows for the creation of a link between a short 2-character name and an actual channel. This function no longer allows the creation of a private channel. For this, use.keygen.keyis the key to the channel. (Required |Str)channelis the channel name. (Required |Str)nameis the short name for the channel. (Required |Str)subscribewhether or not to subscribe to the channel. (Required |Bool)optionsa set of options. Currently available options are:with_at_most_once()to send with QoS0.with_at_least_once()to send with QoS1.with_retain()to retain this message.with_ttl(ttl)to set a time to live for the message.without_echo()to tell the broker not to send the message back to this client.Emitter#me()instance.me()Requests information about the connection. Information provided in the response contains the id of the connection, as well as the links that were established with.link()requests.To handle the responses, see the.on_meproperty.Emitter#on_connectProperty used to get or set the connection handler, that handle events emitted upon successful (re)connection. No arguments provided.Emitter#on_disconnectProperty used to get or set the disconnection handler, that handle events emitted after a disconnection. No arguments provided.Emitter#on_errorProperty used to get or set the error handler, that handle events emitted when an error occurs following any request. The event comes with a status code and a text message describing the error.{"status":400,"message":"the request was invalid or cannot be otherwise served"}Emitter#on_keybanProperty used to get or set the handler for.keyban()requests. Here is a sample of the message received after such a request:{"status": 200,
 "banned": True}Emitter#on_keygenToDo: Description!Emitter#on_meProperty used to get or set the handler that handle responses to.me()requests. Information provided in the response contains the id of the connection, as well as the links that were established with.link()requests.{"id":"74W77OC5OXDBQRUUMSHROHRQPE","links":{"a0":"test/","a1":"test/"}}Emitter#on_messageEmitted when the client receives a message packet. The message object will be ofEmitterMessageclass, encapsulating the channel and the payload.Emitter#on_presenceEmitted either when a presence call was made requesting a status, using theEmitter#presence()function, or when a user subscribed/unsubscribed to the channel and updates were previously requested using again a call to theEmitter#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"}}timeis the time of the event asUnix time.eventis the event type:subscribewhen an remote instance subscribed to the channel,unsubscribewhen an remote instance unsubscribed from the channel andstatuswhenEmitter#presence()is called the first time.channelis the channel name.whoin case of theeventis(un)subscribeone dict with the user id, when theeventisstatus, it is a list with the users. When more than 1000 users at the moment subscribed to the channel, 1000 randomly selected are displayed.idis an internal generated id of the remote instance.usernameis a custom chosen name by the remote instance. Please note that it isoptionaland check always if this parameter exists.Emitter#presence(key, channel, status=False, changes=False, optional_handler=None)instance.presence(""5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb"","channel",True,True)Sends a presence request to the server.keyis the channel key to use for the operation. (Required |Str)channelis the channel name of which you want to call the presence. (Required |Str)statusis whether the broker should send a full status of the channel. (Optional |Bool| Default:False)changesis whether to subscribe to presence changes on the channel.  (Optional |Bool| Default:False)optional_handleris the handler to insert in the handler trie.  (Optional |callable| Default:None)Note: if you do not provide a handler here, make sure you did set the default handler for all presence messages using the.on_presenceproperty.Emitter#publish(key, channel, message, options={})emitter.publish("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb","channel","Hello Emitter!",{Client.with_ttl(604800),Client.without_echo()})//oneweekPublishes a message to a particual channel.keyis the channel key to use for the operation. (Required |Str)channelis the channel name to publish to. (Required |Str)messageis the message to publish (Required |String)optionsa set of options. Currently available options are:with_at_most_once()to send with QoS0.with_at_least_once()to send with QoS1.with_retain()to retain this message.with_ttl(ttl)to set a time to live for the message.without_echo()to tell the broker not to send the message back to this client.Emitter#publish_with_link(link, message)instance.publishWithLink("a0","Hello Emitter!")Sends a message through the link.linkis the 2-character name of the link. (Required |Str)messageis the message to send through the link. (Required |Str)Emitter#subscribe(key, channel, optional_handler=None, options={})instance.subscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb","channel",options={Client.with_last(5)})Subscribes to a particular channel.keyis the channel key to use for the operation. (Required |Str)channelis the channel name to subscribe to. (Required |Str)optional_handleris the handler to insert in the handler trie.  (Optional |callable| Default:None)optionsa set of options. Currently available options are:with_last(x)to receive the lastxmessages stored on the channel.TODOwith_fromwith_untilNote: if you do not provide a handler here, make sure you did set the default handler for all messages using the.on_messageproperty.Emitter#subscribe_with_group(key, channel, share_group, optional_handler=None, options={})instance.subscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb","channel","sg")Subscribes to a particular share group for a channel. A message sent to that channel will be forwarded to only one member of the share group, chosen randomly. For more information about share groups, seeEmitter: Load-balance Messages using Subscriber Groups (on YouTube).keyis the channel key to use for the operation. (Required |Str)channelis the channel name to subscribe to. (Required |Str)share_groupis the name of the group to join. (Required |Str)optional_handleris the handler to insert in the handler trie.  (Optional |callable| Default:None)optionsa set of options.Note: if you do not provide a handler here, make sure you did set the default handler for all messages using the.on_messageproperty.Emitter#unsubscribe(key, channel)instance.unsubscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb","channel")Unsubscribes from a particual channel.keyis the channel key to use for the operation. (Required |Str)channelis the channel name to unsubscribe from. (Required |Str)This deletes handlers for that channel from the trie.EmitterMessage()TheEmitterMessageclass represents a message received from the Emitter server. It contains two properties:channelis the channel name the message was published to. (Str)binaryis the buffer associated with the payload. (BinaryStr)EmitterMessage#asString()message.asString()Returns the payload as a utf-8String.EmitterMessage#asObject()message.asObject()Returns the payload as a JSON-deserialized dictionary.EmitterMessage#asBinary()message.asBinary()Returns the payload as a raw binary buffer.ToDoThere are some points where the Python libary can be improved:Complete thekeygenentry in the README (see theToDomarkings)Describe how to use the trie of handlers for regular messages and presence.Addwith_fromandwith_until.asObject should return an actual object instead of a dictionary.LicenseEclipse Public License 1.0 (EPL-1.0)Copyright (c) 2016-2019Misakai Ltd.