From 71c34bdc3acf699be0dabf93ce3fa6b3ba9de11c Mon Sep 17 00:00:00 2001 From: Giacomo Tanganelli <giacomo.tanganelli@for.unipi.it> Date: Wed, 1 Mar 2017 11:36:56 +0100 Subject: [PATCH] update documentation --- coapthon/client/coap.py | 5 +- coapthon/client/helperclient.py | 106 +++++++++++++++++++++++++++++++- coapthon/serializer.py | 4 +- 3 files changed, 112 insertions(+), 3 deletions(-) diff --git a/coapthon/client/coap.py b/coapthon/client/coap.py index 23557e0..f9d934f 100644 --- a/coapthon/client/coap.py +++ b/coapthon/client/coap.py @@ -21,12 +21,15 @@ class CoAP(object): + """ + Client class to perform requests to remote servers. + """ def __init__(self, server, starting_mid, callback, sock=None): """ Initialize the client. :param server: Server address for incoming connections - :param callback:the calback function to be invoked when a response is received + :param callback:the callback function to be invoked when a response is received :param starting_mid: used for testing purposes :param sock: if a socket has been created externally, it can be used directly """ diff --git a/coapthon/client/helperclient.py b/coapthon/client/helperclient.py index e6adfcb..941f639 100644 --- a/coapthon/client/helperclient.py +++ b/coapthon/client/helperclient.py @@ -11,30 +11,63 @@ class HelperClient(object): + """ + Helper Client class to perform requests to remote servers in a simplified way. + """ def __init__(self, server, sock=None): + """ + Initialize a client to perform request to a server. + + :param server: the remote CoAP server + :param sock: if a socket has been created externally, it can be used directly + """ self.server = server self.protocol = CoAP(self.server, random.randint(1, 65535), self._wait_response, sock=sock) self.queue = Queue() def _wait_response(self, message): + """ + Private function to get responses from the server. + + :param message: the received message + """ if message.code != defines.Codes.CONTINUE.number: self.queue.put(message) def stop(self): + """ + Stop the client. + """ self.protocol.stopped.set() self.queue.put(None) self.protocol.close() def close(self): + """ + Close the client. + """ self.stop() def _thread_body(self, request, callback): + """ + Private function. Send a request, wait for response and call the callback function. + + :param request: the request to send + :param callback: the callback function + """ self.protocol.send_message(request) while not self.protocol.stopped.isSet(): response = self.queue.get(block=True) callback(response) def cancel_observing(self, response, send_rst): # pragma: no cover + """ + Delete observing on the remote server. + + :param response: the last received response + :param send_rst: if explicitly send RST message + :type send_rst: bool + """ if send_rst: message = Message() message.destination = self.server @@ -46,22 +79,55 @@ def cancel_observing(self, response, send_rst): # pragma: no cover self.stop() def get(self, path, callback=None, timeout=None): # pragma: no cover + """ + Perform a GET on a certain path. + + :param path: the path + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ request = self.mk_request(defines.Codes.GET, path) return self.send_request(request, callback, timeout) def observe(self, path, callback, timeout=None): # pragma: no cover + """ + Perform a GET with observe on a certain path. + + :param path: the path + :param callback: the callback function to invoke upon notifications + :param timeout: the timeout of the request + :return: the response to the observe request + """ request = self.mk_request(defines.Codes.GET, path) request.observe = 0 return self.send_request(request, callback, timeout) def delete(self, path, callback=None, timeout=None): # pragma: no cover + """ + Perform a DELETE on a certain path. + + :param path: the path + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ request = self.mk_request(defines.Codes.DELETE, path) return self.send_request(request, callback, timeout) def post(self, path, payload, callback=None, timeout=None): # pragma: no cover + """ + Perform a POST on a certain path. + + :param path: the path + :param payload: the request payload + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ request = self.mk_request(defines.Codes.POST, path) request.token = generate_random_token(2) request.payload = payload @@ -69,17 +135,41 @@ def post(self, path, payload, callback=None, timeout=None): # pragma: no cover return self.send_request(request, callback, timeout) def put(self, path, payload, callback=None, timeout=None): # pragma: no cover + """ + Perform a PUT on a certain path. + + :param path: the path + :param payload: the request payload + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ request = self.mk_request(defines.Codes.PUT, path) request.payload = payload return self.send_request(request, callback, timeout) def discover(self, callback=None, timeout=None): # pragma: no cover + """ + Perform a Discover request on the server. + + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ request = self.mk_request(defines.Codes.GET, defines.DISCOVERY_URL) return self.send_request(request, callback, timeout) def send_request(self, request, callback=None, timeout=None): # pragma: no cover + """ + Send a request to the remote server. + + :param request: the request to send + :param callback: the callback function to invoke upon response + :param timeout: the timeout of the request + :return: the response + """ if callback is not None: thread = threading.Thread(target=self._thread_body, args=(request, callback)) thread.start() @@ -89,11 +179,25 @@ def send_request(self, request, callback=None, timeout=None): # pragma: no cove return response def send_empty(self, empty): # pragma: no cover + """ + Send empty message. + + :param empty: the empty message + """ self.protocol.send_message(empty) def mk_request(self, method, path): + """ + Create a request. + + :param method: the CoAP method + :param path: the path of the request + :return: the request + """ request = Request() request.destination = self.server request.code = method.number request.uri_path = path - return request + return request + + diff --git a/coapthon/serializer.py b/coapthon/serializer.py index 3fac23c..1f877b2 100644 --- a/coapthon/serializer.py +++ b/coapthon/serializer.py @@ -10,7 +10,9 @@ class Serializer(object): - + """ + Serializer class to serialize and deserialize CoAP message to/from udp streams. + """ @staticmethod def deserialize(datagram, source): """