Merge pull request #234 from matrx-software/continuous_bug_fixing

Continuous bug fixing

docs/source/conf.py

@@ -63,6 +63,7 @@
 autoapi_options = ['members', 'inherited-members', 'show-inheritance']
 autoapi_add_toctree_entry = False
 autoapi_python_class_content = "class"
+autoclass_content = 'both'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -114,4 +115,4 @@ def setup(app):
     app.add_stylesheet("css/theme_overrides.css")
 
 
-numpydoc_xref_aliases
+# numpydoc_xref_aliases

docs/source/sections/api.rst

@@ -4,8 +4,10 @@
 API
 =======
 
+The API connects a frontend to MATRX core. By default, the MATRX visualizer is used. Click below to view the various
+API functions and their documentation.
 
 .. autosummary::
    :toctree: _generated_autodoc
 
-    matrx.api
+    matrx.api.api

matrx/__version__.py

@@ -12,7 +12,7 @@
 __url__ = 'https://matrx-software.com'
 __doc_url__ = 'http://docs.matrx-software.com/en/latest/'
 __source_url__ = 'https://github.com/matrx-software/matrx'
-__version__ = '2.0.2'
+__version__ = '2.0.3'
 __author__ = 'MATRX Team at TNO.nl'
 __author_email__ = '[email protected]'
 __license__ = 'MIT License'

matrx/actions/object_actions.py

@@ -174,7 +174,7 @@ class RemoveObjectResult(ActionResult):
 
     See Also
     --------
-    RemoveObjectAction
+    :class:`matrx.actions.object_actions.RemoveObjectAction`
 
     """
 

matrx/agents/agent_utils/navigator.py

@@ -8,6 +8,21 @@
 
 
 class Navigator:
+    """ A navigator object that can be used for path planning and navigation
+
+    Parameters
+    ----------
+    agent_id: string.
+        ID of the agent that wants to navigate
+    action_set: list
+        List of actions the agent can perform
+    algorithm: string. Optional, default "a_star"
+        The pathplanning algorithm to use. As of now only a_star is supported.
+    is_circular: Boolean. Optional, default=False.
+        Whether to continuously navigate from point A to B, and back, until infinity.
+    """
+
+
     A_STAR_ALGORITHM = "a_star"
 
     def __init__(self, agent_id, action_set, algorithm=A_STAR_ALGORITHM, is_circular=False):

matrx/api/api.py

@@ -254,7 +254,8 @@ def get_latest_state(agent_ids):
 
 @app.route('/get_filtered_latest_state/<agent_ids>', methods=['POST'])
 def get_filtered_latest_state(agent_ids):
-    """ Return a state from a set of agent IDs, filtered to only return the specified properties """
+    """ Return a state for a set of agent IDs, filtered to only return the specified properties
+    """
 
     # check for validity and return an error if not valid
     api_call_valid, error = check_states_API_request(tick=current_tick)
@@ -551,7 +552,7 @@ def send_message_pickled():
     The pre-formatted CustomMessage instance can be jsonpickled and sent via the API.
     This API call can handle that request and send the CustomMessage to the MATRX agent
 
-        Returns
+    Returns
     -------
         Error if api call invalid, or True if valid.
     """
@@ -812,7 +813,22 @@ def check_states_API_request(tick=None, ids=None, ids_required=False):
 
 
 def check_input(tick=None, ids=None):
-    # check if tick is a valid format
+    """
+    Checks if the passed parameters are valid.
+
+    Parameters
+    ----------
+    tick: integer. Optional
+        Tick for which to fetch a state or message. Checks for existence.
+    ids: List. Optional
+        Agent IDs to check.
+
+    Returns
+    -------
+    Validity: Boolean.
+        Whether the tick and/or agent IDs are valid
+    """
+
     if tick is not None:
         try:
             tick = int(tick)
@@ -987,7 +1003,6 @@ def add_state(agent_id, state, agent_inheritence_chain, world_settings):
         This object contains all information on the MATRX world, such as tick and grid_size. Some agents might filter
         these out of their state, as such it is sent along seperatly to make sure the world settings, required by the
         visualization, are passed along.
-    -------
     """
     # save the new general info on the MATRX World (once)
     global next_tick_info
@@ -1006,7 +1021,6 @@ def add_state(agent_id, state, agent_inheritence_chain, world_settings):
 
 def next_tick():
     """ Proceed to the next tick, publicizing data of the new tick via the api (the new states).
-    -------
     """
     # save the new general info
     global MATRX_info, next_tick_info, states
@@ -1073,7 +1087,6 @@ def register_world(world_id):
     ----------
     world_id
         The ID of the world
-    -------
     """
     global current_world_ID
     current_world_ID = world_id
@@ -1085,7 +1098,6 @@ def register_world(world_id):
 
 def flask_thread():
     """ Starts the Flask server on localhost:3001
-    -------
     """
     if not debug:
         log = logging.getLogger('werkzeug')
@@ -1097,8 +1109,8 @@ def flask_thread():
 def run_api(verbose=False):
     """ Creates a separate Python thread in which the api (Flask) is started
     Returns
-        MATRX api Python thread
     -------
+        MATRX api Python thread
     """
     print("Starting background api server")
     global debug

matrx/objects/agent_body.py

@@ -4,90 +4,112 @@
 
 
 class AgentBody(EnvObject):
-
-    def __init__(self, location, possible_actions, sense_capability, class_callable,
-                 callback_agent_get_action, callback_agent_set_action_result, callback_agent_observe,
-                 callback_agent_get_messages, callback_agent_set_messages, callback_agent_initialize,
-                 callback_agent_log, callback_create_context_menu_for_other, callback_create_context_menu_for_self,
-                 visualize_size, visualize_shape, visualize_colour, visualize_depth, visualize_opacity,
-                 visualize_when_busy, is_traversable, team, name, is_movable,
-                 is_human_agent, customizable_properties,
-                 **custom_properties):
-        """
-        This class is a representation of an agent's body in the GridWorld.
-
-        It is used as a measure to keep the AgentBrain code and Environment code separate. This AgentBody is used by
-        the environment to update the GUI, perform actions, and update properties. It is kept in sync with the Agent's
-        brain every iteration.
-
-        It inherits from EnvObject which allows you set any custom properties you want. In addition it also has all the
-        mandatory properties of an EnvObject plus a few extra. Which is the team name the agent is part of (if any) and
-        what the Agent's body is carrying.
-
-        In addition the Agent's body keeps a set of callbacks to methods inside the Agent. This forms the connection
-        between the GridWorld (that calls them) and the Agent (that defined them).
-
-        :param location: List or tuple of length two. Mandatory. The location of the Agent's body in the grid world.
-        :param possible_actions: The list of Action class names this agent may be able to perform. This allows you to
-        create agents that can only perform a couple of the available actions.
-        :param sense_capability: The SenseCapability object.
-        :param class_callable: The Agent class; in other words, the class of the agent's brain. This is stored here so
-        that the Visualizer (which visualizes an agent based on this Agent's body object) and agents knows what kind of agent
+    """This class is a representation of an agent's body in the GridWorld.
+
+    It is used as a measure to keep the AgentBrain code and Environment code separate. This AgentBody is used by
+    the environment to update the GUI, perform actions, and update properties. It is kept in sync with the Agent's
+    brain every iteration.
+
+    It inherits from EnvObject which allows you set any custom properties you want. In addition it also has all the
+    mandatory properties of an EnvObject plus a few extra. Which is the team name the agent is part of (if any) and
+    what the Agent's body is carrying.
+
+    In addition the Agent's body keeps a set of callbacks to methods inside the Agent. This forms the connection
+    between the GridWorld (that calls them) and the Agent (that defined them).
+
+    Parameters
+    ----------
+    location: List or tuple of length two.
+        The location of the Agent's body in the grid world.
+    possible_actions: list
+        The list of Action class names this agent may be able to perform. This allows you to create agents that can
+        only perform a couple of the available actions.
+    sense_capability: The SenseCapability object.
+    class_callable: Agent class
+        The Agent class; in other words, the class of the agent's brain. This is stored here so that the Visualizer
+        (which visualizes an agent based on this Agent's body object) and agents knows what kind of agent
         it is. Allows you to visualize certain agent types in a certain way.
 
-        :param callback_agent_get_action: The callback function as defined by the Agent instance of which this is an
-        Agent's body of. It is called each tick by the GridWorld. As such the GridWorld determines when the Agent can
+    callback_agent_get_action: function
+        The callback function as defined by the Agent instance of which this is an Agent's body of. It is called each
+        tick by the GridWorld. As such the GridWorld determines when the Agent can
         perform an action by calling this function which is stored in the Agent's Agent's body.
-        :param callback_agent_set_action_result: Same as the callback_get_action but is used by GridWorld to set the
+    callback_agent_set_action_result: function
+        Same as the callback_get_action but is used by GridWorld to set the
         ActionResult object in the Agent after performing the action. This allows the Agent to know how its planned
         action went.
-        :param callback_agent_observe: Similar to callback_agent_get_action, is used by GridWorld to obtain the
+    callback_agent_observe: function
+        Similar to callback_agent_get_action, is used by GridWorld to obtain the
         processed state dictionary of the Agent. As the GridWorld does not know exactly what the Agent is allowed to
         see or not, the 'observe' preprocesses the given state further. But to accurately visualize what the agent sees
         we have to obtain that pre-processed state, which is done through this callback.
-        :param callback_agent_initialize: Call the initialize function in an Agent's Brain. Is done at the initialize
+    callback_agent_initialize: function
+        Call the initialize function in an Agent's Brain. Is done at the initialize
         of a GridWorld.
 
-        :param callback_agent_get_messages: A callback function that allows the GridWorld to obtain the agent's messages
+    callback_agent_get_messages: function
+        A callback function that allows the GridWorld to obtain the agent's messages
         that need to be send to different agents.
-        :param callback_agent_set_messages: A callback function that allows the GridWorld to set any message send by
+    callback_agent_set_messages: function
+        A callback function that allows the GridWorld to set any message send by
         some agent to a list of received messages in an agent.
 
-        :param callback_create_context_menu_for_other: A callback function that allows the gridworld or API to call the
+    callback_create_context_menu_for_other: function
+        A callback function that allows the gridworld or API to call the
         subsequent agent function that generates the menu options of an agent for a context menu opened by a user not
         controlling that specific agent.
-        :param callback_create_context_menu_for_self: A callback function that allows the gridworld or API to call the
+    callback_create_context_menu_for_self: function
+        A callback function that allows the gridworld or API to call the
         subsequent agent function that generates the menu options for a context menu opened by the user controlling
         the current human agent. If this is not a human agent, it is set to None.
 
-
-        :param name: String Defaults to "Agent". The name of the agent, does not need to be unique.
-        :param is_human_agent: Boolean. Defaults to False. Boolean to signal that the agent represented by this Agent's
+    name: string. Optional, default="Agent"
+        Defaults to "Agent". The name of the agent, does not need to be unique.
+    is_human_agent: Boolean. Optional, default=False.
+        Boolean to signal that the agent represented by this Agent's
         body is a human controlled agent.
-        :param customizable_properties: List. Optional, default obtained from defaults.py. The list of attribute names
+    customizable_properties: List. Optional, default=obtained from defaults.py.
+        The list of attribute names
         that can be customized by other objects (including Agent's body and as an extension any Agent).
-        :param is_traversable: Boolean. Optional, default obtained from defaults.py. Signals whether other objects can
-        be placed on top of this object.
-        :param carried_by: List. Optional, default obtained from defaults.py. A list of who is carrying this object.
-        :param team: The team name the agent is part of. Defaults to the team name similar to the Agent's body unique
+    is_traversable: Boolean. Optional, default obtained from defaults.py.
+        Signals whether other objects can be placed on top of this object.
+    carried_by: List. Optional, default obtained from defaults.py.
+        A list of who is carrying this object.
+    team: string. Optional, default is ID of agent
+        The team name the agent is part of.
+        Defaults to the team name similar to the Agent's body unique
         ID, as such denoting that by default each Agent's body belongs to its own team and as an extension so does its
         "brain" the Agent.
 
-        :param visualize_size: Float. Optional, default obtained from defaults.py. A visualization property used by
+    visualize_size: Float. Optional, default obtained from defaults.py.
+        A visualization property used by
         the Visualizer. Denotes the size of the object, its unit is a single grid square in the visualization (e.g. a
         value of 0.5 is half of a square, object is in the center, a value of 2 is twice the square's size centered on
         its location.)
-        :param visualize_shape: Int. Optional, default obtained from defaults.py. A visualization property used by the
+    visualize_shape: Int. Optional, default obtained from defaults.py.
+        A visualization property used by the
         Visualizer. Denotes the shape of the object in the visualization.
-        :param visualize_colour: Hexcode string. Optional, default obtained from defaults.py. A visualization property
-        used by the Visualizer. Denotes the
-        :param visualize_depth: Integer. Optional, default obtained from defaults.py. A visualization property that
-        is used by the Visualizer to draw objects in layers.
-        :param visualize_opacity: Integer. Opacity of object. Between 0.0 and 1.0.
-        :param visualize_when_busy: Boolean. Whether to show a loading icon when the agent is busy (performing an action).
-        :param **custom_properties: Optional. Any other keyword arguments. All these are treated as custom attributes.
+    visualize_colour: Hexcode string. Optional, default obtained from defaults.py.
+        A visualization property used by the Visualizer. Denotes the
+    visualize_depth: Integer. Optional, default obtained from defaults.py.
+        A visualization property that s used by the Visualizer to draw objects in layers.
+    visualize_opacity: Integer.
+        Opacity of object. Between 0.0 and 1.0.
+    visualize_when_busy: Boolean.
+        Whether to show a loading icon when the agent is busy (performing an action).
+    **custom_properties: dict, optional
+        Any other keyword arguments. All these are treated as custom attributes.
         For example the property 'heat'=2.4 of an EnvObject representing a fire.
-        """
+    """
+
+    def __init__(self, location, possible_actions, sense_capability, class_callable,
+                 callback_agent_get_action, callback_agent_set_action_result, callback_agent_observe,
+                 callback_agent_get_messages, callback_agent_set_messages, callback_agent_initialize,
+                 callback_agent_log, callback_create_context_menu_for_other, callback_create_context_menu_for_self,
+                 visualize_size, visualize_shape, visualize_colour, visualize_depth, visualize_opacity,
+                 visualize_when_busy, is_traversable, team, name, is_movable,
+                 is_human_agent, customizable_properties,
+                 **custom_properties):
 
         # A list of EnvObjects or any class that inherits from it. Denotes all objects the Agent's body is currently
         # carrying. Note that these objects do not exist on the WorldGrid anymore, so removing them in this list deletes
@@ -226,9 +248,17 @@ def _set_agent_changed_properties(self, props: dict):
     def change_property(self, property_name, property_value):
         """
         Changes the value of an existing (!) property.
-        :param property_name: The name of the property.
-        :param property_value:  The value of the property.
-        :return: The new properties.
+
+        Parameters
+        ----------
+        property_name: string
+            The name of the property.
+        property_value:
+            The value of the property.
+
+        Returns
+        ----------
+        The new properties
         """
 
         # We check if it is a custom property and if so change it simply in the dictionary
@@ -288,8 +318,12 @@ def change_property(self, property_name, property_value):
     @property
     def location(self):
         """
-        We override the location pythonic property here so we can override its setter.
-        :return: The location tuple of the form; (x, y).
+        We override the location. Pythonic property here so we can override its setter.
+
+        Returns
+        -------
+        Location: tuple
+            The location tuple of the form; (x, y).
         """
         return tuple(self.__location)
 
@@ -298,8 +332,10 @@ def location(self, loc):
         """
         Overrides the setter of the location (pythonic) property so we can transfer also all carried objects with us
         on any location change made anywhere.
-        :param loc:
-        :return:
+        Parameters
+        ----------
+        loc: tuple
+            The new location
         """
         assert isinstance(loc, list) or isinstance(loc, tuple)
         assert len(loc) == 2
@@ -329,7 +365,10 @@ def properties(self):
 
         In the case we return the properties of a class that inherits from EnvObject, we check if that class has
 
-        :return: All mandatory and custom properties in a dictionary.
+        Returns
+        -------
+        Properties: dict
+            All mandatory and custom properties in a dictionary.
         """
 
         # Copy the custom properties