From 31885554684774f3151dd9e01ad532b7f0ddd44c Mon Sep 17 00:00:00 2001 From: Artem30801 Date: Mon, 12 Oct 2020 16:17:38 +0300 Subject: [PATCH] docs: added docstrings to client_core --- docs/en/api.md | 12 ++++++------ drone/modules/client_core.py | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/docs/en/api.md b/docs/en/api.md index 175f917..da15071 100644 --- a/docs/en/api.md +++ b/docs/en/api.md @@ -2,7 +2,6 @@ `clever-show` can be modified or used as set of modules to repurpose the software or implement different behaviors, expand functionality. - ## messaging Location: `clever-show/lib/lib.py` @@ -14,6 +13,7 @@ Location: `clever-show/lib/lib.py` * `set_keepalive(sock, after_idle_sec=1, interval_sec=3, max_fails=5)` - sets `keepalive` parameters of given socket. Please note, this function is cross-platform but execution and exact effects can vary based on the platform. ### Decorators + In order to register your function as callback for message or command, you can use those decorators: * `message_callback(action_string)`- callback decorator. Functions registered by this decorator will be called upon receiving action message with `action_string` as action. @@ -59,7 +59,7 @@ message = MessageManager() ### Public attributes * `income_raw` - bytes string, append incoming data to this attribute. -* `content` - string (by default `None`). Would be populated when receiving and processing of the message will be completed. +* `content` - object (by default `None`). Would be populated when receiving and processing of the message will be completed. #### Public API methods @@ -166,9 +166,9 @@ config_path - string optional argument. Path to the file with configuration. Th ### Public attributes -* `server_connection` - ConnectionManager object representing connation to the server. -* `connected` - read-only boolean, whether client is connected to the server. -* `client_id` - read-only string, ID of the client +* `server_connection` - ConnectionManager object representing connection to the server. +* `connected` - read-only boolean, whether the client is connected to the server. +* `client_id` - read-only string, ID of the client. * `config` - ConfigManager object, containing loaded client configuration. * `config_path` - path to configuration file. There also should be config specification file at `config_path\config\configspec_client.ini`. @@ -177,7 +177,7 @@ config_path - string optional argument. Path to the file with configuration. Th * `on_broadcast_bind()` - method called on binding to the server by broadcast. Override that method in order to add functionality. * `load_config()` - loads or reloads config from file specified in `config_path`. -* `time_now()` - gets and returns system time or NTP time depending on config. +* `time_now()` - gets and returns system time or NTP time depending on the config. * `start()` - reloads config and starts infinite loop of connecting to the server and processing said connection. Calling of this method *will* indefinitely halt execution of any subsequent code. ### Static methods diff --git a/drone/modules/client_core.py b/drone/modules/client_core.py index a82846d..f66e689 100644 --- a/drone/modules/client_core.py +++ b/drone/modules/client_core.py @@ -24,6 +24,17 @@ active_client = None # needs to be refactored: Singleton \ factory callbacks class Client(object): + """ + Client base class provides config loading, communication with server (including automatic reconnection, broadcast listening and binding). + + Attributes: + server_connection (ConnectionManager) - connection to the server. + connected (bool) - whether the client is connected to the server. + client_id (string) - ID of the client. + config (ConfigManager) - contains loaded client configuration. + config_path (string) - path to configuration file. There also should be config specification file at 'config_path\config\configspec_client.ini'. + """ + def __init__(self, config_path=os.path.join(current_dir, os.pardir, "config", "client.ini")): self.selector = selectors.DefaultSelector() self.client_socket = None @@ -41,6 +52,9 @@ class Client(object): active_client = self def load_config(self): + """ + Loads or reloads config from file specified in 'config_path'. + """ self.config.load_config_and_spec(self.config_path) config_id = self.config.id.lower() @@ -58,6 +72,15 @@ class Client(object): @staticmethod def get_ntp_time(ntp_host, ntp_port): + """Gets and returns time from specified host and port of NTP server. + + Args: + ntp_host (string): hostname or address of the NTP server. + ntp_port (int): port of the NTP server. + + Returns: + int: Current time recieved from the NTP server + """ NTP_PACKET_FORMAT = "!12I" NTP_DELTA = 2208988800L # 1970-01-01 00:00:00 NTP_QUERY = '\x1b' + 47 * '\0' @@ -69,6 +92,11 @@ class Client(object): return unpacked[10] + float(unpacked[11]) / 2 ** 32 - NTP_DELTA def time_now(self): + """gets and returns system time or NTP time depending on the config. + + Returns: + int: Current time. + """ if self.config.ntp_use: timenow = self.get_ntp_time(self.config.ntp_host, self.config.ntp_port) else: @@ -76,6 +104,8 @@ class Client(object): return timenow def start(self): + """Reloads config and starts infinite loop of connecting to the server and processing said connection. Calling of this method will indefinitely halt execution of any subsequent code. + """ self.load_config() logger.info("Starting client") @@ -166,6 +196,8 @@ class Client(object): broadcast_client.close() def on_broadcast_bind(self): # TODO move ALL binding code here + """Method called on binding to the server by broadcast. Override that method in order to add functionality. + """ pass def _process_connections(self):