Merge pull request #21 from Code-Partners/feat-docstrings

Feat docstrings

Author: SergeyCP

common/context/binary_context.py

@@ -5,19 +5,54 @@
 
 
 class BinaryContext(ViewerContext):
+    """
+    This is the base class for all viewer contexts, which deal with
+    binary data. A viewer context is the library-side representation
+    of a viewer in the Console.
+
+    .. note::
+       This class is not guaranteed to be threadsafe.
+    """
+
     def __init__(self, viewer_id: ViewerId):
+        """
+        Initializes a BinaryContext instance.
+
+        :param viewer_id: The viewer ID to use.
+        """
         super().__init__(viewer_id)
         self.__data: BytesIO = BytesIO()
 
     @property
-    def viewer_data(self):
+    def viewer_data(self) -> bytes:
+        """
+        Overridden. Returns the actual binary data which will be
+        displayed in the viewer specified by the ViewerId.
+
+        :rtype: binary
+        """
         return self.__data.getvalue()
 
     def reset_data(self):
+        """
+        Resets the internal data stream.
+
+        .. note::
+            This method is intended to reset the internal data stream
+            if custom handling of data is needed by derived classes.
+        """
+
         self.__data.seek(0)
         self.__data.truncate()
 
     def load_from_file(self, filename: str):
+        """
+        Loads the binary data from a file.
+
+        :param filename: The name of the file to load the binary data from.
+        :raises ValueError: The filename string is empty.
+        """
+
         if filename == "":
             raise ValueError("filename not provided")
         else:
@@ -27,6 +62,17 @@ def load_from_file(self, filename: str):
                 self.__data.write(content)
 
     def append_bytes(self, bytestring: (bytes, bytearray), offset: int = 0, length: int = 0):
+        """
+        Overloaded. Appends a buffer. Lets you specify the offset in
+        the buffer and the amount of bytes to append.
+
+        :param bytestring: The buffer to append.
+        :param offset: The offset at which to begin appending.
+        :param length: The number of bytes to append.
+
+        :raises TypeError: if type requirements are not met by the arguments
+        """
+
         if not isinstance(bytestring, bytes) and \
                 not isinstance(bytestring, bytes):
             raise TypeError("bytestring must be bytes sequence")
@@ -41,6 +87,10 @@ def append_bytes(self, bytestring: (bytes, bytearray), offset: int = 0, length:
         self.__data.write(bytestring[offset: offset + length])
 
     def close(self) -> None:
+        """
+        Overridden. Releases any resources.
+        """
+
         if not self.__data.closed:
             try:
                 self.__data.close()
@@ -49,5 +99,11 @@ def close(self) -> None:
         # we are not expecting an exception
 
     def load_from_stream(self, stream):
+        """
+            Loads the binary data from a stream.
+
+            :param stream: The stream to load the binary data from.
+        """
+
         self.reset_data()
         self.__data.write(stream)

common/context/binary_viewer_context.py

@@ -3,6 +3,23 @@
 
 
 class BinaryViewerContext(BinaryContext):
+    """Represents the binary viewer in the Console which can display binary
+       data in a read-only hex editor.
 
+       .. note::
+
+           The binary viewer in the Console interprets the data of a Log Entry as binary data
+           and displays it in a read-only hex editor.
+
+           You can use the BinaryViewerContext class for creating custom log
+           methods around for sending custom binary data.
+
+       .. note::
+
+           This class is not guaranteed to be threadsafe.
+    """
     def __init__(self):
+        """
+        Initializes a BinaryViewerContext instance.
+        """
         super().__init__(ViewerId.BINARY)

common/context/data_viewer_context.py

@@ -3,5 +3,24 @@
 
 
 class DataViewerContext(TextContext):
+    """
+    Represents the data viewer in the Console which can display simple
+    and unformatted text.
+
+    .. note::
+       The data viewer in the Console interprets the data of a Log Entry as text and displays it in a read-only text
+       field.
+
+       You can use the DataViewerContext class for creating custom log
+       methods around LogCustomContext for
+       sending custom text data.
+
+    .. note::
+      This class is not guaranteed to be threadsafe.
+    """
+
     def __init__(self):
+        """
+        Initializes a DataViewerContext instance.
+        """
         super().__init__(ViewerId.DATA)

common/context/inspector_viewer_context.py

@@ -3,14 +3,50 @@
 
 
 class InspectorViewerContext(ValueListViewerContext):
+    """
+    Represents the inspector viewer in the Console which displays
+    key/value pairs in an object inspector control.
+
+    The inspector viewer in the Console interprets the
+    `data of a Log Entry <LogEntry.data>` as a key/value list with
+    group support like object inspectors from popular IDEs. This class
+    takes care of the necessary formatting and escaping required by the
+    corresponding inspector viewer in the Console.
+
+    You can use the InspectorViewerContext class for creating custom
+    log methods around Session.log_custom_context
+    for sending custom data organized as grouped key/value pairs.
+
+    .. note::
+       This class is not guaranteed to be threadsafe.
+    """
+
     def __init__(self):
+        """
+        Initializes an InspectorViewerContext instance.
+        """
         super().__init__(ViewerId.INSPECTOR)
 
     def start_group(self, group: str):
+        """
+        Starts a new group.
+
+        :param group: The name of the group to use.
+        """
         if isinstance(group, str):
             self.append_text("[")
             self.append_text(self.escape_item(group))
             self.append_text("]\r\n")
 
     def escape_item(self, item: str) -> str:
+        """
+        Overridden. Escapes a key or a value.
+
+        This method ensures that the escaped key or value does not contain any newline characters,
+        such as the carriage return or linefeed characters.
+        Furthermore, it escapes the '\\', '=', '[' and ']' characters.
+
+        :param item: The key or value to escape.
+        :returns: The escaped key or value.
+        """
         return self.escape_line(item, "\\=[]")

common/context/list_viewer_context.py

@@ -3,11 +3,47 @@
 
 
 class ListViewerContext(TextContext):
+    """
+    Represents the list viewer in the Console which can display simple lists of text data.
+
+    The list viewer in the Console interprets the data of a Log Entry as a list. Every line in the text data
+    is interpreted as one item of the list. This class takes care of the necessary formatting and escaping required
+    by the corresponding list viewer in the Console.
+
+    You can use the ListViewerContext class for creating custom log methods around LogCustomContext for sending
+    custom data organized as simple lists.
+
+    .. note::
+       This class is not guaranteed to be threadsafe.
+    """
+
     def __init__(self, viewer_id: ViewerId = ViewerId.LIST) -> None:
+        """
+        Initializes a ListViewerContext instance using a viewer ID.
+
+        This constructor is intended for derived classes, such as the ValueListViewerContext class,
+        which extend the capabilities of this class and use a different viewer ID.
+
+        :param viewer_id: The viewer ID to use.
+        """
         super().__init__(viewer_id)
 
     @staticmethod
     def escape_line(line: str = "", escape_chars: str = "") -> str:
+
+        """
+        Escapes a line.
+
+        This method ensures that the escaped line does not
+        contain characters listed in the escape_chars parameter plus
+        any newline characters, such as the carriage return or
+        linefeed characters.
+
+        :param line: The line to escape.
+        :param escape_chars: A string of characters which should be escaped in addition to the newline characters.
+        Can be empty.
+        :returns: The escaped line.
+        """
         if (
                 not isinstance(line, str) or
                 not isinstance(escape_chars, str)

common/context/tableviewercontext.py

@@ -3,15 +3,45 @@
 
 
 class TableViewerContext(ListViewerContext):
+    """
+    Represents the table viewer in the Console which can display text
+    data as a table.
+
+    The table viewer in the Console interprets the
+    data of a Log Entry as a table. This class
+    takes care of the necessary formatting and escaping required by
+    the corresponding table viewer in the Console.
+
+    You can use the TableViewerContext class for creating custom
+    log methods around Session.log_custom_context
+    for sending custom data organized as tables.
+
+    .. note::
+       This class is not guaranteed to be threadsafe.
+    """
+
     def __init__(self) -> None:
+        """
+        Initializes a TableViewerContext instance.
+        """
         super().__init__(ViewerId.TABLE)
         self.__line_start: bool = True
 
     def append_header(self, header: str) -> None:
+        """
+        Appends a header to the text data.
+      
+        :param header: The header to append."""
+
         self.append_line(header)
         self.append_line("")
 
     def add_row_entry(self, entry: str) -> None:
+        """
+            Adds a string entry to the current row.
+
+            :param entry: The string entry to add.
+        """
         if self.__line_start:
             self.__line_start = False
         else:
@@ -42,7 +72,9 @@ def __escape_csv_entry(entry: str) -> str:
         return "".join(result)
 
     def begin_row(self) -> None:
+        """Begins a new row."""
         self.__line_start = True
 
     def end_row(self) -> None:
+        """Ends the current row."""
         self.append_line("")