Added and documented the new keyban API.

README.md

@@ -30,19 +30,22 @@ These examples show you the whole communication process.
 * Python 2: [*sample-python2.py*](emitter/sample-python2.py)
 * Python 3: [*sample-python3.py*](emitter/sample-python3.py)
 
+![alt animated gif demonstrating the todo list](SampleAppScreenshot.png?raw=true)
 
 <a id="api"></a>
 ## API reference
 
 * [`Client()`](#client)
   * [`.connect()`](#connect)
   * [`.disconnect()`](#disconnect)
+  * [`.keyban()`](#keyban)
   * [`.keygen()`](#keygen)
   * [`.link()`](#link)
   * [`.me()`](#me)
   * [`.on_connect`](#on_connect)
   * [`.on_disconnect`](#on_disconnect)
   * [`.on_error`](#on_error)
+  * [`.on_keyban`](#on_keyban)
   * [`.on_keygen`](#on_keygen)
   * [`.on_me`](#on_me)
   * [`.on_message`](#on_message)
@@ -68,7 +71,7 @@ The `Client` class represents the client connection to an Emitter server.
 <a id="connect"></a>
 ### Emitter#connect(host="api.emitter.io", port=443, secure=True, keepalive=30)
 
-```
+```python
 emitter = Client()
 
 emitter.connect()
@@ -87,21 +90,36 @@ To handle connection events, see the [`.on_connect`](#on_connect) property.
 <a id="disconnect"></a>
 ### Emitter#disconnect()
 
-```
+```python
 emitter.disconnect()
 ```
 Disconnects from the connected Emitter server.
 
 To handle disconnection events, see the [`.on_disconnect`](#on_disconnect) property.
 
+-------------------------------------------------------
+<a id="keyban"></a>
+### Emitter#keyban(master_key, target_key, ban)
+
+```python
+instance.keyban("MEj8QNnzy6pKtE887hpXbD0KyKXi4w4f", "ftibXtPMKXI5p2FjhyINf8tvl2GAHaNG", True)
+```
+Sends a request to ban/unban a channel key. 
+* `master_key` is your *master key* to use for the operation. (Required | `Str`)
+* `target_key` is the key ban or unban. (Required | `Str`)
+* `ban` is whether to ban or unban the key. (Required | `Bool`)
+
+To handle keyban responses, see the [`.on_keyban`](#on_keyban) property.
+Requesting a keygen with an extendable channel creates a private channel.
+
 -------------------------------------------------------
 <a id="keygen"></a>
 ### Emitter#keygen(key, channel, permissions, ttl=0)
 
-```
+```python
 instance.keygen("Z5auMQhNr0eVnGBAgWThXus1dgtSsvuQ", "channel/", "rwslpex")
 ```
-Sends a key generation request to the server. See also [`Emitter`](#client-keygen) for a description of the event and [`Emitter#on()`](#on) for the possibilities of event handling.
+Sends a key generation request to the server. 
 * `key` is your *master key* to use for the operation. (Required | `Str`)
 * `channel` is the channel name to generate a key for. (Required | `Str`)
 * `permissions` are the permissions associated to the key. (Required | `Str`)
@@ -121,7 +139,7 @@ Requesting a keygen with an extendable channel creates a private channel.
 <a id="link"></a>
 ### Emitter#link(key, channel, name, private, subscribe, options={})
 
-```
+```python
 instance.link("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb",
               "channel",
               "a0",
@@ -144,7 +162,7 @@ Sends a link creation request to the server. This allows for the creation of a l
 <a id="me"></a>
 ### Emitter#me()
 
-```
+```python
 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()`](#link) requests.
@@ -169,23 +187,35 @@ Property used to get or set the disconnection handler, that handle events emitte
 
 Property 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.
 
-```
+```json
 {"status": 400,
  "message": "the request was invalid or cannot be otherwise served"}
 ```
 
+-------------------------------------------------------
+<a id="on_keyban"></a>
+### Emitter#on_keyban
+
+Property used to get or set the handler for [`.keyban()`](#keyban) requests. Here is a sample of the message received after such a request:
+
+```json
+{'status': 200,
+ 'banned': True}
+```
+
 -------------------------------------------------------
 <a id="on_keygen"></a>
 ### Emitter#on_keygen
 
 **ToDo: Description!**
+
 -------------------------------------------------------
 <a id="on_me"></a>
 ### Emitter#on_me
 
 Property used to get or set the handler that handle responses to [`.me()`](#me) requests. Information provided in the response contains the id of the connection, as well as the links that were established with [`.link()`](#link) requests.
 
-```
+```json
 {"id": "74W77OC5OXDBQRUUMSHROHRQPE",
  "links": {"a0": "test/",
            "a1": "test/"}}
@@ -203,7 +233,7 @@ Emitted when the client receives a message packet. The message object will be of
 
 Emitted either when a presence call was made requesting a status, using the [`Emitter#presence()`](#presence) function, or when a user subscribed/unsubscribed to the channel and updates were previously requested using again a call to the [`Emitter#presence()`](#presence) function. Example arguments below.
 
-```
+```json
 {"time": 1577833210,
  "event": "status",
  "channel": "<channel name>",
@@ -229,7 +259,7 @@ Emitted either when a presence call was made requesting a status, using the [`Em
 <a id="presence"></a>
 ### Emitter#presence(key, channel, status=False, changes=False, optional_handler=None)
 
-```
+```python
 instance.presence(""5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb"",
                   "channel",
                   True,
@@ -248,7 +278,7 @@ Note: if you do not provide a handler here, make sure you did set the default ha
 <a id="publish"></a>
 ### Emitter#publish(key, channel, message, options={})
 
-```
+```python
 emitter.publish("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb",
                  "channel",
                  "Hello Emitter!",
@@ -269,7 +299,7 @@ Publishes a message to a particual channel.
 <a id="publish_with_link"></a>
 ### Emitter#publish_with_link(link, message)
 
-```
+```python
 instance.publishWithLink("a0",
                          "Hello Emitter!")
 ```
@@ -282,7 +312,7 @@ Sends a message through the link.
 <a id="subscribe"></a>
 ### Emitter#subscribe(key, channel, optional_handler=None, options={})
 
-```
+```python
 instance.subscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb",
                    "channel",
                    options={Client.with_last(5)})
@@ -305,7 +335,7 @@ Note: if you do not provide a handler here, make sure you did set the default ha
 <a id="subscribe_with_group"></a>
 ### Emitter#subscribe_with_group(key, channel, share_group, optional_handler=None, options={})
 
-```
+```python
 instance.subscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb",
                    "channel",
                    "sg")
@@ -326,7 +356,7 @@ Note: if you do not provide a handler here, make sure you did set the default ha
 <a id="unsubscribe"></a>
 ### Emitter#unsubscribe(key, channel)
 
-```
+```python
 instance.unsubscribe("5xZjIQp6GA9fpxso1Kslqnv8d4XVWChb",
                      "channel")
 ```
@@ -348,7 +378,7 @@ The `EmitterMessage` class represents a message received from the Emitter server
 <a id="asString"></a>
 ### EmitterMessage#asString()
 
-```
+```python
 message.asString()
 ```
 Returns the payload as a utf-8 `String`.
@@ -357,7 +387,7 @@ Returns the payload as a utf-8 `String`.
 <a id="asObject"></a>
 ### EmitterMessage#asObject()
 
-```
+```python
 message.asObject()
 ```
 Returns the payload as a JSON-deserialized dictionary.
@@ -366,7 +396,7 @@ Returns the payload as a JSON-deserialized dictionary.
 <a id="asBinary"></a>
 ### EmitterMessage#asBinary()
 
-```
+```python
 message.asBinary()
 ```
 Returns the payload as a raw binary buffer.

emitter/emitter.py

@@ -35,6 +35,7 @@ def __init__(self):
 		self._handler_trie_presence = SubTrie()
 		self._handler_me = None
 		self._handler_keygen = None
+		self._handler_keyban = None
 
 	@property
 	def on_connect(self):
@@ -78,6 +79,13 @@ def on_keygen(self):
 	def on_keygen(self, func):
 		self._handler_keygen = func
 
+	@property
+	def on_keyban(self):
+		return self._handler_keyban
+	@on_keyban.setter
+	def on_keyban(self, func):
+		self._handler_keyban = func
+
 	@property
 	def on_message(self):
 		return self._handler_message
@@ -156,6 +164,10 @@ def _on_message(self, client, userdata, msg):
 			# This is a keygen message.
 			self._handler_keygen(message.as_object())
 
+		elif self._handler_keyban and message.channel.startswith("emitter/keyban"):
+			# This is a keyban message.
+			self._handler_keyban(message.as_object())
+
 		elif message.channel.startswith("emitter/presence"):
 			# This is a presence message.
 			#self._invoke_trie_handlers(self._handler_trie_presence, self._handler_presence, message)
@@ -245,6 +257,14 @@ def presence(self, key, channel, status=False, changes=False, optional_handler=N
 		# Publish the request.
 		self._mqtt.publish("emitter/presence/", json.dumps(request))
 
+	def keyban(self, master_key, target_key, ban):
+		"""
+		* Sends a ban or unban request for a target key using a master key.
+		"""
+		request = {"secret": master_key, "target": target_key, "banned": ban}
+		# Publish the request.
+		self._mqtt.publish("emitter/keyban/", json.dumps(request))
+
 	def keygen(self, key, channel, permissions, ttl=0):
 		"""
 		* Sends a key generation request to the server.

emitter/sample-python3.py

@@ -17,6 +17,7 @@
 share_group = tkinter.StringVar(root, value="sg")
 share_group_key = tkinter.StringVar(root, value="b7FEsiGFQoSYA6qyeu1dDodFnO0ypp0f")
 #share_group_key = tkinter.StringVar(root, value="Q_dM5ODuhWjaR_LNo886hVjoecvt5pMJ") #local
+master_key = tkinter.StringVar(root, value="MEj8QNnzy6pKtE887hpXbD0KyKXi4w4f")
 
 def connect():
 	emitter.connect(host="127.0.0.1", port=8080, secure=False)
@@ -27,7 +28,8 @@ def connect():
 	emitter.on_presence = lambda p: result_text.insert("0.0", "Presence message on channel: '" + str(p) + "'\n\n")
 	emitter.on_message = lambda m: result_text.insert("0.0", "Message received on default handler, destined to " + m.channel + ": " + m.as_string() + "\n\n")
 	emitter.on_error = lambda e: result_text.insert("0.0", "Error received: " + str(e) + "\n\n")
-	emitter.on_me = lambda me: result_text.insert("0.0", "Information about Me received: " + str(me) +"\n\n")
+	emitter.on_me = lambda me: result_text.insert("0.0", "Information about Me received: " + str(me) + "\n\n")
+	emitter.on_keyban = lambda kb: result_text.insert("0.0", "Keyban message received: " + str(kb) + "\n\n")
 	emitter.loop_start()
 
 def disconnect():
@@ -84,6 +86,16 @@ def pub_to_link():
 def me():
 	emitter.me()
 
+def keyban():
+	str_target_key = channel_key.get()
+	str_master_key = master_key.get()
+	emitter.keyban(str_master_key, str_target_key, True)
+
+def keyunban():
+	str_target_key = channel_key.get()
+	str_master_key = master_key.get()
+	emitter.keyban(str_master_key, str_target_key, False)
+
 # Col 1
 tkinter.Label(root, text="Channel : ").grid(column=1, row=1)
 channel_entry = tkinter.Entry(root, width=40, textvariable=channel)
@@ -109,6 +121,9 @@ def me():
 share_key_entry = tkinter.Entry(root, width=40, textvariable=share_group_key)
 share_key_entry.grid(column=1, row=12)
 
+tkinter.Label(root, text="Master key : ").grid(column=1, row=13)
+share_key_entry = tkinter.Entry(root, width=40, textvariable=master_key)
+share_key_entry.grid(column=1, row=14)
 
 # Col 2
 connect_button = tkinter.Button(root, text="Connect", width=30, command=connect)
@@ -146,8 +161,14 @@ def me():
 me_button = tkinter.Button(root, text="Me", width=30, command=me)
 me_button.grid(column=4, row=2)
 
+keyban_button = tkinter.Button(root, text="Key ban", width=30, command=keyban)
+keyban_button.grid(column=4, row=4)
+
+keyban_button = tkinter.Button(root, text="Key unban", width=30, command=keyunban)
+keyban_button.grid(column=4, row=5)
+
 # Text area
 result_text = tkinter.Text(root, height=30, width=120)
-result_text.grid(column=1, row=14, columnspan=4)
+result_text.grid(column=1, row=15, columnspan=4)
 
 root.mainloop()

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="emitter-io",
-    version="2.1.0",
+    version="2.2.0",
     author="Florimond Husquinet",
     author_email="[email protected]",
     description="A Python library to interact with the Emitter API.",