lots of docstrings + fix a bug where Agents proxy requests were shared from the base class instead of being created for the subclass

Author: Ademfcan

Alt-Core/src/Alt/Core/Agents/Agent.py

@@ -1,9 +1,3 @@
-# agents, otherwise known as tasks will be long running "processes"
-# lifespan: 1. create 2. run until shutdown/task finished 2.5 possibly shutdown 3. cleanup.
-# For the most part there will be only one agent running for the whole time
-# NOTE: agents will get objects passed into them via the init. There are the "shared" objects across the whole process.
-# For objects pertaining only to agent, create them in the create method
-
 from abc import ABC, abstractmethod
 from logging import Logger
 from typing import Dict, Optional, Any, ClassVar
@@ -24,8 +18,9 @@
 
 
 class Agent(ABC):
-    _proxyRequests: ClassVar[dict[str, ProxyType]] = {}
-
+    """
+    Base class for all agents.
+    """
     DEFAULT_LOOP_TIME: int = 0  # 0 ms
     TIMERS = "timers"
 
@@ -197,6 +192,9 @@ def addProxyRequest(cls, proxyName : str, proxyType: ProxyType) -> None:
         """ Method to request that a stream proxy will be given to this agent to display streams
             NOTE: you must override requestProxies() and add your calls to this there, or else it will not be used!
         """
+        if not hasattr(cls, '_proxyRequests'):
+            cls._proxyRequests = {}
+
         cls._proxyRequests[proxyName] = proxyType
 
     @classmethod

Alt-Core/src/Alt/Core/Agents/__init__.py

@@ -1,2 +1,3 @@
 from .Agent import Agent
-from .AgentExample import AgentExample
+from .AgentExample import AgentExample
+from .PositionLocalizingAgentBase import PositionLocalizingAgentBase

Alt-Core/src/Alt/Core/Constants/AgentConstants.py

@@ -1,7 +1,7 @@
 from abc import abstractmethod
+from enum import Enum
 from typing import Any, Dict, Union
 from functools import partial
-from enum import Enum
 
 
 class ProxyType(Enum):
@@ -15,7 +15,7 @@ def objectName(self):
 
     @staticmethod
     def getProxyRequests(
-        agentClass: Union[partial]
+        agentClass
     ) -> Dict[str, "ProxyType"]:
         if isinstance(agentClass, partial):
             return ProxyType.__getPartialProxyRequests(agentClass)

Alt-Core/src/Alt/Core/Constants/Field.py

@@ -1,4 +1,3 @@
-from enum import Enum
 from ..Units import Types, Conversions
 
 class Field:

Alt-Core/src/Alt/Core/Constants/__init__.py

@@ -1,2 +1,3 @@
 from .Field import Field
-from .Teams import TEAM
+from .Teams import TEAM
+from .AgentConstants import ProxyType, Proxy

Alt-Core/src/Alt/Core/Operators/AgentOperator.py

@@ -1,3 +1,17 @@
+"""AgentOperator.py
+
+This module defines the AgentOperator class, which manages the lifecycle and execution
+of Agent instances, including their initialization, proxy setup, logging, and shutdown.
+It provides mechanisms for running agents in separate processes or threads, handling
+their status, and ensuring proper cleanup.
+
+Classes:
+    AgentOperator: Manages agent processes, proxies, and lifecycle events.
+
+Functions:
+    (All public and private methods of AgentOperator are documented at the class and function level.)
+"""
+
 import logging
 import multiprocessing
 import multiprocessing.managers
@@ -8,7 +22,7 @@
 import time
 from functools import partial
 from concurrent.futures import ProcessPoolExecutor, Future
-from typing import Any, Optional, Callable, Union
+from typing import Optional, Callable, Union
 
 from JXTABLES.XTablesClient import XTablesClient
 
@@ -27,6 +41,16 @@
 
 # subscribes to command request with xtables and then executes when requested
 class AgentOperator:
+    """
+    Manages the lifecycle, execution, and communication of Agent instances.
+
+    Responsibilities include:
+    - Starting and stopping agents, both in the main thread and in subprocesses.
+    - Handling agent proxies for inter-process communication.
+    - Managing agent logging and status reporting.
+    - Ensuring proper cleanup and shutdown of agents.
+    """
+
     STATUS = "status"
     DESCRIPTION = "description"
     ERRORS = "errors"
@@ -37,15 +61,22 @@ class AgentOperator:
     SHUTDOWNTIMER = "shutdown"
     CLOSETIMER = "close"
 
-
-    
     def __init__(
         self,
         manager: multiprocessing.managers.SyncManager,
         shareOp: ShareOperator,
         streamOp: StreamOperator,
         logStreamOp : LogStreamOperator
     ) -> None:
+        """
+        Initializes the AgentOperator.
+
+        Args:
+            manager (multiprocessing.managers.SyncManager): Manager for shared objects.
+            shareOp (ShareOperator): Operator for shared data.
+            streamOp (StreamOperator): Operator for stream proxies.
+            logStreamOp (LogStreamOperator): Operator for log stream proxies.
+        """
         self.__executor: ProcessPoolExecutor = ProcessPoolExecutor()
         self.__stop: threading.Event = manager.Event()  # flag
         self.futures: list[Future] = []
@@ -57,6 +88,12 @@ def __init__(
         self.manager = manager
 
     def __setStop(self, stop: bool):
+        """
+        Sets or clears the stop flag for agent execution.
+
+        Args:
+            stop (bool): If True, sets the stop flag; otherwise, clears it.
+        """
         try:
             if stop:
                 self.__stop.set()
@@ -66,20 +103,34 @@ def __setStop(self, stop: bool):
             pass
 
     def stopAndWait(self) -> None:
-        """Stop all agents but allow them to clean up, and wait for them to finish"""
+        """Stop all agents but allow them to clean up, and wait for them to finish."""
         self.__setStop(True)
         self.waitForAgentsToFinish()
         self.__setStop(False)
 
     def stopPermanent(self) -> None:
-        """Set the stop flag permanently (will not be reset)"""
+        """Set the stop flag permanently (will not be reset)."""
         self.__setStop(True)
 
     def __setMainAgent(self, agent: Agent):
+        """
+        Sets the main agent reference.
+
+        Args:
+            agent (Agent): The agent to set as the main agent.
+        """
         self.mainAgent = agent
 
     def getUniqueAgentName(self, agentClass: Union[partial, type[Agent]]):
-        """Handles duplicate agent names"""
+        """
+        Generates a unique name for an agent, handling duplicates.
+
+        Args:
+            agentClass (Union[partial, type[Agent]]): The agent class or partial.
+
+        Returns:
+            str: A unique agent name.
+        """
         if isinstance(agentClass, partial):
             name = agentClass.func.__name__
         else:
@@ -104,6 +155,17 @@ def initalizeProxies(
         agentName: str,
         proxyDict: multiprocessing.managers.DictProxy,
     ) -> tuple[multiprocessing.managers.DictProxy, queue.Queue]:
+        """
+        Initializes proxies for the agent, including stream and log proxies.
+
+        Args:
+            agentClass (Union[partial, type[Agent]]): The agent class or partial.
+            agentName (str): The unique agent name.
+            proxyDict (multiprocessing.managers.DictProxy): The proxy dictionary.
+
+        Returns:
+            tuple: (proxyDict, logProxy)
+        """
         for requestName, proxyType in ProxyType.getProxyRequests(agentClass).items():
             # TODO add more
             if proxyType is ProxyType.STREAM:
@@ -117,6 +179,13 @@ def initalizeProxies(
         return proxyDict, logProxy
 
     def wakeAgent(self, agentClass: type[Agent], isMainThread: bool) -> None:
+        """
+        Starts an agent, either in the main thread or in a subprocess.
+
+        Args:
+            agentClass (type[Agent]): The agent class to instantiate and run.
+            isMainThread (bool): Whether to run in the main thread.
+        """
         Sentinel.info(f"Waking agent!")
 
         agentName = self.getUniqueAgentName(agentClass)
@@ -173,7 +242,15 @@ def _handleLog(
         newLog: str,
         maxLogLength: int = 3,
     ) -> None:
-
+        """
+        Handles log messages for an agent, maintaining a rolling window of recent logs.
+
+        Args:
+            logProperty (ReadonlyProperty): The property to update with log messages.
+            lastLogs (list): The list of recent log messages.
+            newLog (str): The new log message to add.
+            maxLogLength (int): The maximum number of log messages to keep.
+        """
         lastLogs.append(newLog)
         lastLogs = lastLogs[-maxLogLength:]
 
@@ -189,7 +266,20 @@ def _injectAgent(
         logProxy: queue.Queue,
         isMainThread: bool,
     ) -> Agent:
-
+        """
+        Injects core dependencies and logging into the agent.
+
+        Args:
+            agent (Agent): The agent instance.
+            agentName (str): The agent's unique name.
+            shareOperator (ShareOperator): The shared operator.
+            proxies (DictProxy): The proxy dictionary.
+            logProxy (queue.Queue): The log proxy queue.
+            isMainThread (bool): Whether running in the main thread.
+
+        Returns:
+            Agent: The injected agent.
+        """
         # injecting stuff shared from core
         agent._injectCore(shareOperator, isMainThread, agentName)
         # creating new operators just for this agent and injecting them
@@ -218,7 +308,14 @@ def _injectNewOperators(
         agentName: str,
         logProxy: queue.Queue
     ) -> None:
-        """Since any agent not on main thread will be in its own process, alot of new objects will have to be created"""
+        """
+        Injects new operator instances and logging handlers into the agent.
+
+        Args:
+            agent (Agent): The agent instance.
+            agentName (str): The agent's unique name.
+            logProxy (queue.Queue): The log proxy queue.
+        """
         client = XTablesClient(debug_mode=True)  # one per process
         client.add_client_version_property(f"MATRIX-ALT-{agentName}")
 
@@ -267,6 +364,20 @@ def _startAgentLoop(
         logProxy: queue.Queue,
         runOnCreate: Optional[Callable[[Agent], None]] = None,
     ) -> None:
+        """
+        Main agent loop that manages agent lifecycle, including creation, running,
+        shutdown, and cleanup.
+
+        Args:
+            agentClass (type[Agent]): The agent class to instantiate.
+            agentName (str): The agent's unique name.
+            shareOperator (ShareOperator): The shared operator.
+            isMainThread (bool): Whether running in the main thread.
+            stopflag (threading.Event): The stop flag event.
+            proxies (DictProxy): The proxy dictionary.
+            logProxy (queue.Queue): The log proxy queue.
+            runOnCreate (Optional[Callable[[Agent], None]]): Optional callback to run on agent creation.
+        """
         if not isMainThread:
             signal.signal(signal.SIGINT, signal.SIG_IGN)    
             signal.signal(signal.SIGTERM, signal.SIG_IGN)    
@@ -413,10 +524,19 @@ def __handleException(exception: Exception) -> None:
             agent.isCleanedUp = True
 
     def allFinished(self):
+        """
+        Checks if all agent futures have completed.
+
+        Returns:
+            bool: True if all agents are finished, False otherwise.
+        """
         return all(f.done() for f in self.futures)
 
     def waitForAgentsToFinish(self) -> None:
-        """Thread blocking method that waits for any running agents"""
+        """
+        Thread blocking method that waits for any running agents to finish.
+        Also ensures the main agent is properly shut down and cleaned up.
+        """
         if not self.allFinished():
             Sentinel.info("Waiting for async agent to finish...")
             while True:
@@ -450,6 +570,8 @@ def waitForAgentsToFinish(self) -> None:
             Sentinel.info("Main agent finished")
 
     def shutDownNow(self) -> None:
-        """Threadblocks until executor is finished"""
+        """
+        Blocks the thread until the executor is finished and all agent processes are shut down.
+        """
         self.__executor.shutdown(wait=True, cancel_futures=True)