Cleanup and adjusted comments

Author: Gedusim

pyghthouse/_thread.py

@@ -13,9 +13,8 @@ class PHThread(Thread):
         - Main routine:     Loop for sending frames to the webserver.
         - Ending Phase:     Closes the connection and cleanup threads.
 
-        In the main routine, this thread will build and send frames from 
-        **canvas**. The time between each frame is indicated by 
-        **send_interval**.
+        In the main routine, this thread will build and send frames from **canvas**. The time between each frame is
+        indicated by **send_interval**.
 
         Attributes
         ----------
@@ -36,13 +35,14 @@ class PHThread(Thread):
 
         ready : Event
             Event flag is set to *True* in the send process of a frame.
-            This flag will always be *True* when connected is *True*, unless the even is unset Can be used for waiting operations.
+            This flag will always be *True* when connected is *True*, unless the event is unset.
+            Used for waiting operations (see method `Pyghthouse.wait()`).
 
         stop_event : Event
             Indicates when the Pyghthouse routine should be stopped.
 
         error : Event
-            Event flag is set to *True* when an error accured inside the pyghthouse routine.
+            Event flag is set to *True* when an error occured inside the pyghthouse routine.
         """
 
     def __init__(self, send_interval, image_callback, canvas:PyghthouseCanvas, 
@@ -138,7 +138,7 @@ def _send_image(self):
         """
         Build and send current frame.
 
-        If error accures process, the connection will be closed.
+        Also sets the **ready** flag after successful frame creation.
         """
         if self.callback is not None:
             self._set_callback_image()
@@ -153,6 +153,8 @@ def _send_image(self):
     def _set_callback_image(self):
         """
         Set image from callback function.
+
+        When an error occures, the connection will be closed and the exeption will be stored for further handeling in `ph.py`
         """
         try:
             image_from_callback = self.callback()

pyghthouse/connection/wsconnector.py

@@ -16,12 +16,12 @@ class WSConnector:
         Event flag is set to *True* when websocket thread is connected to the webserver and **send** can be used.
     
     error : Event
-        Event flag is set to *True* when error accured and connection is closed.
+        Event flag is set to *True* when error occured and connection is closed.
         
     The flag **error** has a higher priotiy than the **connected** flag. Meaning when **error** is set to *True*, the
     connection is closed even when **connected** can be set to *True*.
 
-    For further invastigation, check developer notes in **on_error**
+    For further invastigation, check developer notes in `_on_error()`.
     """
 
     def __init__(self, username:str, token:str, address:str, 
@@ -73,10 +73,7 @@ def __init__(self, username:str, token:str, address:str,
         if ignore_ssl_cert:
             kwargs = None
 
-        self.timeout = 3
-        if timeout > 0:
-            self.timeout = timeout
-        setdefaulttimeout(self.timeout)
+        self.set_timeout(timeout)
 
         self.thread = Thread(target=self.ws.run_forever, kwargs=kwargs)
 
@@ -90,8 +87,8 @@ def open(self):
         After opening the websocket, the websocket thread sets the **connected** event flag to *True* and is ready to
         send data.
 
-        When an error accured upon opening, the **error** flag will be set to *True* and **on_error()** will be called.
-        In this case, the connection will be closed again and the **connected** flag will cleared to *False* again.
+        When an error occured upon opening, the **error** flag will be set to *True* and `_on_error()` will be called.
+        In this case, the connection will be closed again and the **connected** flag will be cleared to *False* again.
         """
         if self.verbosity == VerbosityLevel.ALL:
             print("Opening websocket connection.")
@@ -111,7 +108,7 @@ def open(self):
 
     def send(self, data):
         """
-        Send data via websocket connection.
+        Sends data via websocket connection.
 
         Raises a *WebSocketConnectionClosedException* when no connection is present.
         """
@@ -139,9 +136,9 @@ def send(self, data):
 
     def close(self):
         """
-        Close websocket connection.
+        Closes websocket connection.
 
-        This function can still be used when no connection is present.
+        This function can still be used when no connection is present. In this case, nothing will happen.
         """
         if self.verbosity == VerbosityLevel.ALL:
             print("Closing connection.")
@@ -163,13 +160,13 @@ def construct_package(self, payload_data):
 
 
     def set_timeout(self, timeout=10):
-        self.timeout = 3
+        self.timeout = 2.5
         if timeout > 0:
             self.timeout = timeout
         setdefaulttimeout(self.timeout)
 
 
-    # Functions used by the websocket thread:
+    ## Functions used by the websocket thread ##
 
     def _on_open(self, ws: WebSocketApp):
         """
@@ -197,12 +194,12 @@ def _on_close(self, ws: WebSocketApp, close_status_code, close_msg):
         ----------------
         Developer notes:
 
-        When the websocket thread has been started, **on_close** will always be called, even when an error accured upon
-        opening the connection. This is a result of the **teardown()** function in WebSocketApp.
+        When the websocket thread has been started, `_on_close()` will always be called, even when an error occured upon
+        opening the connection. This is a result of the `teardown()` function in WebSocketApp.
 
-        So its possible that **on_close()** will be called even when **on_open()** hasn't been called yet.
+        So its possible that `_on_close()` will be called even when `_on_open()` hasn't been called yet.
         
-        For further invastigation, check the developer notes in **on_error()**.
+        For further invastigation, check the developer notes in `_on_error()`.
         """
         if self.verbosity == VerbosityLevel.ALL:
             print("Connection closed.")
@@ -216,23 +213,23 @@ def _on_error(self, ws: WebSocketApp, err: Exception):
 
         This function will save the **exception** and set the flag **error** to *True*.
 
-        This function also sets the flag **connected** to *True* to avoid blocking of **open** when an error accured
+        This function also sets the flag **connected** to *True* to avoid blocking of **open** when an error occured
         upon opening the connection.
         
         ----------------
         Developer notes:
 
-        This method is used by WebSocketApp as callback function. The intend is to signal that an error accured in
+        This method is used by WebSocketApp as callback function. The intend is to signal that an error occured in
         WebSocketApp and to allow further error handeling outside of WebSocketApp.
 
-        Because we use **run_forever()** without a parameter for **reconnect()**, we use the standard of *0* from the
+        Because we use `run_forever()` without a parameter for `reconnect()`, we use the standard of *0* from the
         websocket-client library. This will always force a teardown of the connection without an attempt to reconnect
         upon error. 
         
-        A teardown of the connection will also call the **_on_close()** callback function, even when **_on_error()**
-        has been the called. **_on_close()** will even be called when an error accured on the attempt to open the 
+        A teardown of the connection will also call the `_on_close()` callback function, even when `_on_error()`
+        has been the called. `_on_close()` will even be called when an error occured on the attempt to open the 
         websocket.
-        Meaning, **_on_close()** can be called even when **_on_open()** hasn't been called yet.
+        Meaning, `_on_close()` can be called even when `_on_open()` hasn't been called yet.
 
         Do not raise an exception here!
         --------------------------------

pyghthouse/data/canvas.py

@@ -15,11 +15,19 @@ def __init__(self, initial_image=None):
 
 
     def set_image(self, new_image: list) -> True:
-        
+        """
+        Set the canvas to the **new_image**.
+
+        Throws exeptions when an invalid image object has been given.
+
+        This function is thread-safe.
+        """
+        # Catch invalid image objects
         self._check_size(new_image)
         self._check_cells(new_image)
         self._check_values(new_image)
 
+        # Setting the image
         with self.lock:
 
             for y in range(self.IMAGE_SHAPE[0]):
@@ -32,7 +40,11 @@ def set_image(self, new_image: list) -> True:
 
 
     def get_bytes_image(self):
-        
+        """
+        Returns the currently saved image in a bytearray.
+
+        This function is thread-safe.
+        """
         image_bytes = b''
 
         with self.lock:
@@ -46,7 +58,11 @@ def get_bytes_image(self):
 
 
     def copy_image(self):
+        """
+        Returns a copy of the currently saved image.
 
+        This function is thread-safe.
+        """
         image_copy = [[[0 for k in range(self.IMAGE_SHAPE[2])] for j in range(self.IMAGE_SHAPE[1])] for i in range(self.IMAGE_SHAPE[0])]
 
         with self.lock:
@@ -60,8 +76,12 @@ def copy_image(self):
         return image_copy
 
 
-    def _check_size(self, other: list):
+    ## Internal error checking functions ##
 
+    def _check_size(self, other: list):
+        """
+        Check if we received a 3-dimensional list with the correct sizes.
+        """
         try:
             other_size = (len(other), len(other[0]), len(other[0][0]))
 
@@ -76,8 +96,12 @@ def _check_size(self, other: list):
 
 
     def _check_cells(self, other: list):
-        
-        # Catch objects like [[[0,1,2],[0,1,2,3,4,5],[1]],1]
+        """
+        Check for the existence of all expected cells in our image object. Also catches if we have too many cells.
+
+        We need this additional check because `_check_size()` only ensures that we received a 3-dimensional list.
+        """
+        # Catch objects like [[[0,1,2],[0,1,2,3,4,5],[1]],1,...]
         for y in range(self.IMAGE_SHAPE[0]):
             try:
 
@@ -99,7 +123,9 @@ def _check_cells(self, other: list):
 
 
     def _check_values(self, other: list):
-        
+        """
+        Check if all cells have valid numbers.
+        """
         for y in range(self.IMAGE_SHAPE[0]):
             for x in range(self.IMAGE_SHAPE[1]):
                 for rgb in range(self.IMAGE_SHAPE[2]):