Improved documentation (#3921)

* Added documentation to the inventory

* Added documentation to the inventory

* Added/improved documentation

pokemongo_bot/cell_workers/recycle_items.py

@@ -12,8 +12,6 @@
 DEFAULT_MIN_EMPTY_SPACE = 6
 
 class RecycleItems(BaseTask):
-    SUPPORTED_TASK_API_VERSION = 1
-
     """
     Recycle undesired items if there is less than five space in inventory.
     You can use either item's name or id. For the full list of items see ../../data/items.json
@@ -40,6 +38,8 @@ class RecycleItems(BaseTask):
       }
     }
     """
+    SUPPORTED_TASK_API_VERSION = 1
+
 
     def initialize(self):
         self.items_filter = self.config.get('item_filter', {})
@@ -73,42 +73,41 @@ def should_run(self):
 
     def work(self):
         """
-        Discard items if necessary.
-        :return: Returns wether or not the task went well
+        Start the process of recycling items if necessary.
+        :return: Returns whether or not the task went well
         :rtype: WorkerResult
         """
-        # TODO: Use new inventory everywhere and then remove the inventory update
-        # Updating inventory
+
+        # TODO: Use new inventory everywhere and then remove this inventory update
         inventory.refresh_inventory()
+
         worker_result = WorkerResult.SUCCESS
         if self.should_run():
 
-            # For each user's item in inventory recycle it if needed
             for item_in_inventory in inventory.items().all():
-                amount_to_recycle = self.get_amount_to_recycle(item_in_inventory)
 
-                if self.item_should_be_recycled(item_in_inventory, amount_to_recycle):
+                if self.item_should_be_recycled(item_in_inventory):
+                    # Make the bot appears more human
                     action_delay(self.bot.config.action_wait_min, self.bot.config.action_wait_max)
-                    if ItemRecycler(self.bot, item_in_inventory, amount_to_recycle).work() == WorkerResult.ERROR:
+                    # If at any recycling process call we got an error, we consider that the result of this task is error too.
+                    if ItemRecycler(self.bot, item_in_inventory, self.get_amount_to_recycle(item_in_inventory)).work() == WorkerResult.ERROR:
                         worker_result = WorkerResult.ERROR
 
         return worker_result
 
-    def item_should_be_recycled(self, item, amount_to_recycle):
+    def item_should_be_recycled(self, item):
         """
         Returns a value indicating whether the item should be recycled.
-        :param amount_to_recycle:
-        :param item:
+        :param item: The Item to test
         :return: True if the title should be recycled; otherwise, False.
         :rtype: bool
         """
-        return (item.name in self.items_filter or str(
-            item.id) in self.items_filter) and amount_to_recycle > 0
+        return (item.name in self.items_filter or str(item.id) in self.items_filter) and self.get_amount_to_recycle(item) > 0
 
     def get_amount_to_recycle(self, item):
         """
         Determine the amount to recycle accordingly to user config
-        :param item: Item to determine the amount to recycle
+        :param item: Item to determine the amount to recycle.
         :return: The amount to recycle
         :rtype: int
         """

pokemongo_bot/inventory.py

@@ -106,18 +106,46 @@ def captured(self, pokemon_id):
             return False
         return self._data[pokemon_id]['times_captured'] > 0
 
+
 class Item(object):
+    """
+    Representation of an item.
+    """
     def __init__(self, item_id, item_count):
+        """
+        Initialise an instance of an item
+        :param item_id: ID of the item
+        :type item_id: int
+        :param item_count: Quantity of the item
+        :type item_count: int
+        :return: An item
+        :rtype: Item
+        """
         self.id = item_id
         self.name = Items.name_for(self.id)
         self.count = item_count
 
     def remove(self, amount):
+        """
+        Remove a specified amount of an item from the cached inventory.
+        Note that it does **NOT** removes it in the server, it only removes it from the local cached inventory.
+        :param amount: Amount to remove
+        :type amount: int
+        :return: Nothing
+        :rtype: None
+        """
         if self.count < amount:
             raise Exception('Tried to remove more {} than you have'.format(self.name))
         self.count -= amount
 
     def add(self, amount):
+        """
+        Add a specified amount of the item to the local cached inventory
+        :param amount: Amount to add
+        :type amount: int
+        :return: Nothing.
+        :rtype: None
+        """
         if amount < 0:
             raise Exception('Must add positive amount of {}'.format(self.name))
         self.count += amount
@@ -132,15 +160,41 @@ class Items(_BaseInventoryComponent):
     STATIC_DATA_FILE = os.path.join(_base_dir, 'data', 'items.json')
 
     def parse(self, item_data):
+        """
+        Make an instance of an Item from raw item data.
+        :param item_data: Item data to make an item from
+        :return: Instance of the Item.
+        :rtype: Item
+        """
         item_id = item_data.get(Items.ID_FIELD, None)
         item_count = item_data['count'] if 'count' in item_data else 0
         return Item(item_id, item_count)
 
+    def all(self):
+        """
+        Get EVERY Item from the cached inventory.
+        :return: List of evey item in the cached inventory
+        :rtype: list of Item
+        """
+        return list(self._data.values())
+
     def get(self, item_id):
+        """
+        Get ONE Item from the cached inventory.
+        :param item_id: Item's ID to search for.
+        :return: Instance of the item from the cached inventory
+        :rtype: Item
+        """
         return self._data.setdefault(item_id, Item(item_id, 0))
 
     @classmethod
     def name_for(cls, item_id):
+        """
+        Search the name for an item from its ID.
+        :param item_id: Item's ID to search for.
+        :return: Item's name.
+        :rtype: str
+        """
         return cls.STATIC_DATA[str(item_id)]
 
     @classmethod
@@ -178,6 +232,7 @@ def has_space_for_loot(cls):
         return cls.get_space_left() >= max_number_of_items_looted_at_stop
 
 
+
 class Pokemons(_BaseInventoryComponent):
     TYPE = 'pokemon_data'
     ID_FIELD = 'id'
@@ -1093,55 +1148,111 @@ def _calc_cp(base_attack, base_defense, base_stamina,
 
 #
 # Usage helpers
+# TODO : Complete the doc
+# Only type return have been filled for now. It helps the IDE to suggest methods of the class.
 
 def init_inventory(bot):
+    """
+    Initialises the cached inventory, retrieves data from the server.
+    :param bot: Instance of the bot.
+    :type bot: pokemongo_bot.PokemonGoBot
+    :return: Nothing.
+    :rtype: None
+    """
     global _inventory
     _inventory = Inventory(bot)
 
 
 def refresh_inventory():
+    """
+    Refreshes the cached inventory, retrieves data from the server.
+    :return: Nothing.
+    :rtype: None
+    """
     _inventory.refresh()
 
 def get_item_inventory_size():
+    """
+    Access to the Item inventory size.
+    :return: Item inventory size.
+    :rtype: int
+    """
     _inventory.retrieve_item_inventory_size()
     return _inventory.item_inventory_size
 
 def pokedex():
+    """
+
+    :return:
+    :rtype: Pokedex
+    """
     return _inventory.pokedex
 
 
 def candies(refresh=False):
+    """
+
+    :param refresh:
+    :return:
+    :rtype: Candies
+    """
     if refresh:
         refresh_inventory()
     return _inventory.candy
 
 
 def pokemons(refresh=False):
+    """
+
+    :param refresh:
+    :return:
+    :rtype: Pokemons
+    """
     if refresh:
         refresh_inventory()
     return _inventory.pokemons
 
 
 def items():
     """
-    Access to the cached item inventory
-    :return: Instance of the cached item inventory
+    Access to the cached item inventory.
+    :return: Instance of the cached item inventory.
     :rtype: Items
     """
     return _inventory.items
 
 
 def types_data():
+    """
+
+    :return:
+    :rtype: Types
+    """
     return Types
 
 
 def levels_to_cpm():
+    """
+
+    :return:
+    :rtype: LevelToCPm
+    """
     return LevelToCPm
 
 
 def fast_attacks():
+    """
+
+    :return:
+    :rtype: FastAttacks
+    """
     return FastAttacks
 
 
 def charged_attacks():
+    """
+
+    :return:
+    :rtype: ChargedAttack
+    """
     return ChargedAttacks

pokemongo_bot/services/item_recycle_worker.py

@@ -5,16 +5,16 @@
 
 RECYCLE_REQUEST_RESPONSE_SUCCESS = 1
 class ItemRecycler(BaseTask):
-    SUPPORTED_TASK_API_VERSION = 1
     """
     This class contains details of recycling process.
     """
+    SUPPORTED_TASK_API_VERSION = 1
     def __init__(self, bot, item_to_recycle, amount_to_recycle):
         """
         Initialise an instance of ItemRecycler
         :param bot: The instance of the Bot
         :param item_to_recycle: The item to recycle
-        :type item_to_recycle: Item
+        :type item_to_recycle: inventory.Item
         :param amount_to_recycle: The amount to recycle
         :type amount_to_recycle: int
         :return: Nothing.
@@ -27,8 +27,8 @@ def __init__(self, bot, item_to_recycle, amount_to_recycle):
 
     def work(self):
         """
-        Recycle an item
-        :return: Returns wether or not the task went well
+        Start the recycling process
+        :return: Returns whether or not the task went well
         :rtype: WorkerResult
         """
         if self.should_run():
@@ -43,7 +43,7 @@ def work(self):
 
     def should_run(self):
         """
-        Returns a value indicating whether or mot the recycler should be run.
+        Returns a value indicating whether or not the recycler should be run.
         :return: True if the recycler should be run; otherwise, False.
         :rtype: bool
         """