Add type annotations and mypy type-checking (#2)

* annotate src code

* add ruff rules for annotations etc, fixed related source

* add and configure mypy

* enable mypy in workflow pipeline

* add pytest to pre-commit pipeline

Author: jacklowrie

.github/workflows/pipeline.yml

@@ -80,9 +80,9 @@ jobs:
       if: ${{ inputs.run-lint }}
       run: uv run ruff check --output-format=github .
 
-      # - name: Run typechecker
-      #   if: ${{ inputs.run-typecheck }}
-      #   run: uv run mypy .
+    - name: Run typechecker
+      if: ${{ inputs.run-typecheck }}
+      run: uv run mypy
 
     - name: Run tests
       if: ${{ inputs.run-test }}

.pre-commit-config.yaml

@@ -25,3 +25,19 @@ repos:
         types: [python]
         args: ["run", "ruff", "check", "--fix"]
         always_run: true
+
+    -   id: mypy
+        name: MyPy Type-Checker
+        entry: uv
+        language: system
+        types: [python]
+        args: ["run", "mypy"]
+        always_run: true
+
+    -   id: pytest
+        name: PyTest
+        entry: uv
+        language: system
+        types: [python]
+        args: ["run", "pytest"]
+        always_run: true

pyproject.toml

@@ -73,3 +73,33 @@ pythonpath = [
 testpaths = [
     "tests",
 ]
+
+[tool.ruff]
+line-length = 80
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "ANN", # annotations :)
+    "D", # code documentation :)
+]
+ignore = ["F403", "F405"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+files = ["src", "tests"]
+exclude = [
+    '(^|.*/)__pycache__/',  # matches __pycache__ at any depth
+    '(^|.*/).ruff_cache/',
+    '(^|.*/).mypy_cache/',
+]

src/chordnet/__init__.py

@@ -1,5 +1,6 @@
-from .node import Node
+"""init.py: defines importable classes."""
 from .address import Address
 from .net import _Net
+from .node import Node
 
 __all__=['Node', 'Address', '_Net']

src/chordnet/address.py

@@ -1,10 +1,10 @@
-# address.py
+"""address.py: class that represents a ring address."""
 
 import hashlib
 
+
 class Address:
-    """
-    Represents a network address with a unique key in a distributed system.
+    """Represents a network address with a unique key in a distributed system.
 
     This class encapsulates the network location (IP and port) and a unique
     identifier (key) used for routing and comparison in Chord.
@@ -17,24 +17,28 @@ class Address:
     Provides methods for equality comparison and string representation.
     """
     __slots__= ('key', 'ip', 'port')
-    _M = 16
-    _SPACE = 2 ** _M
+    _M: int = 16
+    _SPACE: int = 2 ** _M
 
 
-    def __init__(self, ip, port):
+    def __init__(self, ip: str, port: int) -> None:
+        """Creates a new Address object.
+
+        Args:
+            ip: ip address of the node.
+            port: port of the node.
+        """
         self.key = self._hash(f"{ip}:{port}")
         self.ip = ip
         self.port = port
 
 
 
-
-    def _hash(self, key):
-        """
-        Generates a consistent hash for identifiers.
+    def _hash(self, key: str) -> int:
+        """Generates a consistent hash for identifiers.
 
         Args:
-            key (str): Input string to hash.
+            key: Input string to hash.
 
         Returns:
             int: Hashed identifier within the hash space.
@@ -43,14 +47,27 @@ def _hash(self, key):
 
 
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
+        """Checks for equality.
+
+        Args:
+            other: other object to check.
+
+        Returns:
+            true if the other address is identical, false otherwise.
+        """
         if not isinstance(other, Address):
-            return False
+            return NotImplemented
         return (self.ip == other.ip and
                 self.port == other.port and
                 self.key == other.key)
 
 
 
-    def __repr__(self):
+    def __repr__(self) -> str:
+        """String representation of this address.
+
+        Returns:
+            String format for this address.
+        """
         return f"{self.key}:{self.ip}:{self.port}"

src/chordnet/net.py

@@ -1,10 +1,24 @@
+"""net.py: Class for handling networking operations for nodes."""
 import socket
 import sys
 import threading
+from typing import Callable, Tuple
+
+from .address import Address
+
+callback = Callable[[str, list[str]], str| Address | None]
 
 class _Net:
 
-    def __init__(self, ip, port, request_handler):
+    _ip: str
+    _port: int
+    _request_handler: callback
+    _running: bool
+    _network_thread: threading.Thread | None
+    server_socket: socket.socket | None
+    network_thread: threading.Thread | None
+
+    def __init__(self, ip: str, port: int, request_handler: callback) -> None:
         self._ip = ip
         self._port = port
         self._request_handler = request_handler
@@ -13,9 +27,8 @@ def __init__(self, ip, port, request_handler):
         self.server_socket = None
         self.network_thread = None
 
-    def start(self):
-        """
-        Starts the Chord node's network listener.
+    def start(self) -> None:
+        """Starts the Chord node's network listener.
 
         Begins accepting incoming network connections in a separate thread.
         """
@@ -33,9 +46,8 @@ def start(self):
 
 
 
-    def stop(self):
-        """
-        Gracefully stops the Chord node's network listener.
+    def stop(self) -> None:
+        """Gracefully stops the Chord node's network listener.
 
         Closes the server socket and waits for the network thread to terminate.
         """
@@ -47,9 +59,10 @@ def stop(self):
 
 
 
-    def send_request(self, dest_node, method, *args):
-        """
-        Sends a network request to a specific node.
+    def send_request(
+        self, dest_node: Address, method: str, *args: object
+    ) -> str | None:
+        """Sends a network request to a specific node.
 
         Args:
             dest_node (Address): The network address to send the request to
@@ -78,7 +91,7 @@ def send_request(self, dest_node, method, *args):
                 sock.send(request.encode())
 
                 # Receive the response
-                response = sock.recv(1024).decode()
+                response: str = sock.recv(1024).decode()
 
                 return response
 
@@ -95,15 +108,19 @@ def send_request(self, dest_node, method, *args):
 
 
 
-    def _listen_for_connections(self):
-        """
-        Continuously listens for incoming network connections.
+    def _listen_for_connections(self) -> None:
+        """Continuously listens for incoming network connections.
 
-        Accepts client connections and spawns a thread to handle each connection.
+        Accepts client connections and spawns a thread to handle
+        each connection.
         """
         while self._running:
             try:
-                client_socket, address = self.server_socket.accept()
+                client_socket: socket.socket | None = None
+                address: Tuple[str, int] | None = None
+
+                if self.server_socket:
+                    client_socket, address = self.server_socket.accept()
                 # Handle each connection in a separate thread
                 threading.Thread(
                     target=self._handle_connection,
@@ -117,16 +134,15 @@ def _listen_for_connections(self):
 
 
 
-    def _handle_connection(self, client_socket):
-        """
-        Processes an individual network connection.
+    def _handle_connection(self, client_socket: socket.socket) -> None:
+        """Processes an individual network connection.
 
         Args:
             client_socket (socket): The socket connection to handle.
         """
         try:
             # Receive request
-            request = client_socket.recv(1024).decode()
+            request: str = client_socket.recv(1024).decode()
 
             # Parse request
             method, *args = request.split(':')