chore: merge from main

Author: u-chaCP

__init__.py

@@ -0,0 +1,3 @@
+from smartinspect import SmartInspect # noqa
+from smartinspect_handler.smartinspect_handler import SmartInspectHandler # noqa
+from connections.builders import ConnectionStringBuilder # noqa

common/clock.py

@@ -5,7 +5,7 @@
 class Clock:
     @staticmethod
     def now() -> int:
-        current_time_millis = time.time() * 1000
-        local_timezone_offset_millis = datetime.now(timezone.utc).astimezone().utcoffset().total_seconds() * 1000
-        current_time_micros = int((current_time_millis + local_timezone_offset_millis) * 1000)
+        current_time_micros = time.time_ns() / 1e3
+        local_timezone_offset_micros = datetime.now(timezone.utc).astimezone().utcoffset().total_seconds() * 1e6
+        current_time_micros = int(current_time_micros + local_timezone_offset_micros)
         return current_time_micros

common/clock_resolution.py

@@ -20,17 +20,13 @@ class Color(Enum):
     # additional colors can be added, syntax is <<colorname>> = RGBAColor(r, g, b)
 
     def get_red(self):
-        return self.value.red
+        return self.value.get_red()
 
     def get_green(self):
-        return self.value.green
+        return self.value.get_green()
 
     def get_blue(self):
-        return self.value.blue
+        return self.value.get_blue()
 
     def get_alpha(self):
-        return self.value.alpha
-
-
-
-
+        return self.value.get_alpha()

common/color/color.py

@@ -4,20 +4,16 @@ def __init__(self, r: int, g: int, b: int, a: int = 0x00):
         value = (a & 255) << 24 | (r & 255) << 16 | (g & 255) << 8 | (b & 255) << 0
         self.__value = value
 
-    @property
-    def red(self):
+    def get_red(self):
         return self.__value >> 16 & 255
 
-    @property
-    def green(self):
+    def get_green(self):
         return self.__value >> 8 & 255
 
-    @property
-    def blue(self):
+    def get_blue(self):
         return self.__value >> 0 & 255
 
-    @property
-    def alpha(self):
+    def get_alpha(self):
         return self.__value >> 24 & 255
 
     @staticmethod

common/color/rgbacolor.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_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/binary_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/data_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/inspector_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)