From 3a46ed197a1e700cf4cd66ec3accd96431873772 Mon Sep 17 00:00:00 2001
From: Artur Borecki <me@pufereq.pl>
Date: Tue, 23 Sep 2025 23:36:21 +0200
Subject: [PATCH] docs(connector.py): add docstrings

---
 src/judas_client/connector.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/judas_client/connector.py b/src/judas_client/connector.py
index 67957cd..b9b7738 100644
--- a/src/judas_client/connector.py
+++ b/src/judas_client/connector.py
@@ -11,6 +11,8 @@ from judas_protocol import Message
 
 
 class Connector:
+    """Connector class for managing TCP connection and message exchange."""
+
     def __init__(
         self,
         mac_address: str,
@@ -19,6 +21,14 @@ class Connector:
         *,
         on_message: Callable[[Message], None],
     ) -> None:
+        """Initialize the Connector.
+
+        Args:
+            mac_address (str): The MAC address of the client.
+            host (str): The server host address.
+            port (int): The server port number.
+            on_message (Callable[[Message], None]): Callback for handling incoming messages.
+        """
         self.logger: lg.Logger = lg.getLogger(
             f"{__name__}.{self.__class__.__name__}"
         )
@@ -47,6 +57,7 @@ class Connector:
         self.on_message: Callable[[Message], None] = on_message
 
     def _send_outbound(self) -> None:
+        """Send data from the outbound buffer."""
         while self.outbound_buffer:
             try:
                 sent = self.socket.send(self.outbound_buffer)
@@ -63,6 +74,7 @@ class Connector:
                 break
 
     def _receive_inbound(self) -> None:
+        """Receive data into the inbound buffer."""
         try:
             data: bytes = self.socket.recv(4096)
             if data:
@@ -76,18 +88,21 @@ class Connector:
             self.reconnect()
 
     def send_hello(self) -> None:
+        """Send a HELLO message to the server."""
         self.logger.debug("[*] Sending HELLO message...")
         hello_message: bytes = Message.hello(self.mac_address).to_bytes()
         self.outbound_buffer += hello_message
         self._send_outbound()
 
     def close(self) -> None:
+        """Close the connection and clean up resources."""
         self.logger.debug("[*] Closing connection...")
         self.selector.unregister(self.socket)
         self.socket.close()
         self.logger.debug("[.] Connection closed.")
 
     def reconnect(self) -> None:
+        """Reconnect to the server."""
         self.logger.debug("[*] Reconnecting...")
         self.close()
 
@@ -102,6 +117,7 @@ class Connector:
         self.connect()
 
     def connect(self) -> None:
+        """Establish a connection to the server."""
         self.logger.debug(f"Connecting to {self.host}:{self.port}...")
         connected: bool = False
         delay: float = 1.0
@@ -122,6 +138,7 @@ class Connector:
         self.send_hello()
 
     def run(self) -> None:
+        """Run the main event loop."""
         self.connect()
         try:
             while True: