Update documentation docstrings

Author: pockerman

src/spaces/actions.py

@@ -1,29 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The actions module. This module includes
+various actions to be applied by the implemented RL agents
+
+"""
+
 import abc
 import enum
 from typing import List, TypeVar, Any
-
 import numpy as np
 
-from src.utils.hierarchy_base import HierarchyBase
 from src.utils.mixins import WithHierarchyTable
 
 Hierarchy = TypeVar("Hierarchy")
 
 
-def move_next(iterators: List) -> None:
-    """
-    Loop over the iterators and move them
-    to the next item
-    :param iterators: The list of iterators to propagate
-    :return: None
-    """
-    for item in iterators:
-        next(item)
-
-
 class ActionType(enum.IntEnum):
-    """
-    Defines the status of an Action
+    """Defines the status of an Action
     """
 
     INVALID_TYPE = -1
@@ -53,39 +45,71 @@ def restore(self) -> bool:
 
 
 class ActionBase(metaclass=abc.ABCMeta):
-    """
-    Base class for actions
+    """Base class for actions
     """
 
     def __init__(self, column_name: str, action_type: ActionType) -> None:
+        """Constructor
+
+        Parameters
+        ----------
+        column_name : The name of the column this is acting on
+        action_type : The type of the action
+
+        """
         self.column_name = column_name
         self.action_type = action_type
         self.idx = None
         self.key = (self.column_name, self.action_type)
 
     @abc.abstractmethod
     def act(self, **ops) -> Any:
-        """
-        Perform an action
-        :return:
+        """Perform the action
+
+        Parameters
+        ----------
+        ops : The data to distort
+
+        Returns
+        -------
+        Typically the action returns the distorted subset of the data
+
         """
 
 
 class ActionIdentity(ActionBase):
-    """
-    Implements the identity action
+    """Implements the identity action. Use this action
+    to signal that no distortion should be applied.
+
     """
 
     def __init__(self, column_name: str) -> None:
+        """Constructor
+
+        Parameters
+        ----------
+        column_name : The name of the column this is acting on
+
+        """
         super(ActionIdentity, self).__init__(column_name=column_name, action_type=ActionType.IDENTITY)
         self.called = False
 
     def act(self, **ops) -> Any:
+        """Perform the action
+
+        Parameters
+        ----------
+        ops : The data to distort
+
+        Returns
+        -------
+
+        The distorted column
+
         """
-        Perform the action
-        :return:
-        """
+
         self.called = True
+        return ops['data']
 
 
 class ActionRestore(ActionBase, WithHierarchyTable):
@@ -160,20 +184,35 @@ def act(self, **ops) -> None:
 
 
 class ActionStringGeneralize(ActionBase, WithHierarchyTable):
-    """
-    Implements the generalization action. The generalization_table
+    """Implements the generalization action. The generalization_table
     must implement the __getitem__ function
+
     """
 
-    def __init__(self, column_name: str, generalization_table:  Hierarchy):
-        super(ActionStringGeneralize, self).__init__(column_name=column_name, action_type=ActionType.GENERALIZE)
+    def __init__(self, column_name: str, generalization_table:  Hierarchy) -> None:
+        """Constructor
 
-        self.table = generalization_table
+        Parameters
+        ----------
+        column_name : The column name this action is acting on
+        generalization_table : The hierarchy for the generalization
 
-    def act(self, **ops):
         """
-        Perform an action
-        :return:
+        super(ActionStringGeneralize, self).__init__(column_name=column_name, action_type=ActionType.GENERALIZE)
+        self.table = generalization_table
+
+    def act(self, **ops) -> Any:
+        """Performs the action
+
+        Parameters
+        ----------
+        ops : The data to distort
+
+        Returns
+        -------
+
+        The distorted data
+
         """
 
         # get the values of the column
@@ -191,12 +230,33 @@ def act(self, **ops):
         return ops['data']
 
     def add(self, key: Any, value: Any) -> None:
+        """Add a new item in the underlying hierarchy
+
+        Parameters
+        ----------
+        key : The key to use for the new item
+        value : The value of the new item
+
+        Returns
+        -------
+
+        None
+        """
         self.table.add(key, value)
 
 
 class ActionNumericBinGeneralize(ActionBase, WithHierarchyTable):
+    """Generalization Action for numeric columns using bins
+    """
 
     def __init__(self, column_name: str, generalization_table:  Hierarchy):
+        """
+        Constructor
+        Parameters
+        ----------
+        column_name : The name of the column this is acting on
+        generalization_table : The bins to use
+        """
         super(ActionNumericBinGeneralize, self).__init__(column_name=column_name, action_type=ActionType.GENERALIZE)
 
         self.table = generalization_table
@@ -207,10 +267,16 @@ def __init__(self, column_name: str, generalization_table:  Hierarchy):
             self.bins.append((start, self.table[i]))
             start = self.table[i]
 
-    def act(self, **ops):
+    def act(self, **ops) -> Any:
         """
-        Perform an action
-        :return:
+        Perform the action
+        Parameters
+        ----------
+        ops : The data to distort
+
+        Returns
+        -------
+        Typically the action returns the distorted subset of the data
         """
 
         # get the values of the column