More review changes from PR # 580

1. Add note about lack of stability wrt pid ordering to replace
commented shuffle code.
2. Improved docstring for bake_future_focus, to clarify usage of update.
3. Fixed bake_future_focus and made it remove current planet from raw
planets after updating meters.
4. Made all docstrings use """ not '''.

default/AI/ResourcesAI.py

@@ -7,6 +7,8 @@
 transfers the planet from the raw list to the baked list, until all planets
 have their future focus decided.
 """
+#Note: The algorithm is not stable with respect to pid order.  i.e. Two empire with
+#      exactly the same colonies, but different pids may make different choices.
 
 import freeOrionAIInterface as fo  # pylint: disable=import-error
 import FreeOrionAI as foAI
@@ -67,16 +69,11 @@ def __init__(self):
         resource_timer.start("getPlanets")
         planet_ids = list(PlanetUtilsAI.get_owned_planets_by_empire(universe.planetIDs))
 
-        # resource_timer.start("Shuffle")
-        # shuffle(generalPlanetIDs)
-
         resource_timer.start("Targets")
-        planet_infos = [PlanetFocusInfo(universe.getPlanet(pid)) for pid in  planet_ids]
-        self.all_planet_info = {}
-        self.all_planet_info.update(zip(planet_ids, planet_infos))
+        self.all_planet_info = {pid : PlanetFocusInfo(universe.getPlanet(pid)) for pid in  planet_ids}
 
         self.raw_planet_info = dict(self.all_planet_info)
-        self.baked_planet_info = dict()
+        self.baked_planet_info = {}
 
         for pid, pinfo in self.raw_planet_info.items():
             if not pinfo.can_change_focus():
@@ -85,24 +82,29 @@ def __init__(self):
 
     def bake_future_focus(self, pid, focus, update=True):
         """Set the focus and moves it from the raw list to the baked list of planets
+
+        pid -- pid
+        focus -- future focus to use
+        update -- If update is True then the meters of the raw planets will be updated.
+                  If the planet's change of focus will have a global effect (growth,
+                  production or research special), then update should be True.
         Return success or failure
         """
         pinfo = self.raw_planet_info.get(pid)
-        success = (pinfo is not None and
+        success = bool(pinfo is not None and
                    (pinfo.current_focus == focus
                     or (focus in pinfo.planet.availableFoci
                         and fo.issueChangeFocusOrder(pid, focus))))
         if success:
-            pinfo.future_focus = focus
-            self.baked_planet_info[pid] = self.raw_planet_info.pop(pid)
-
             if update and pinfo.current_focus != focus:
-                # TODO determine if this should update all planets (for reporting) or just the remaining unplaced planets
                 universe = fo.getUniverse()
                 universe.updateMeterEstimates(self.raw_planet_info.keys())
                 itarget = pinfo.planet.currentMeterValue(fo.meterType.targetIndustry)
                 rtarget = pinfo.planet.currentMeterValue(fo.meterType.targetResearch)
                 pinfo.possible_output[focus] = (itarget, rtarget)
+
+            pinfo.future_focus = focus
+            self.baked_planet_info[pid] = self.raw_planet_info.pop(pid)
         return success
 
 
@@ -392,7 +394,7 @@ def assess_protection_focus(pid, pinfo):
 
 
 def use_planet_growth_specials(focus_manager):
-    '''set resource foci of planets with potentially useful growth factors. Remove planets from list of candidates.'''
+    """set resource foci of planets with potentially useful growth factors. Remove planets from list of candidates."""
     if useGrowth:
         # TODO: also consider potential future benefit re currently unpopulated planets
         for metab, metabIncPop in ColonisationAI.empire_metabolisms.items():
@@ -427,7 +429,7 @@ def use_planet_growth_specials(focus_manager):
 
 
 def use_planet_production_and_research_specials(focus_manager):
-    '''Use production and research specials as appropriate.  Remove planets from list of candidates.'''
+    """Use production and research specials as appropriate.  Remove planets from list of candidates."""
     #TODO remove reliance on rules knowledge.  Just scan for specials with production
     #and research bonuses and use what you find. Perhaps maintain a list
     # of know types of specials
@@ -462,7 +464,7 @@ def use_planet_production_and_research_specials(focus_manager):
 
 
 def set_planet_protection_foci(focus_manager):
-    '''Assess and set protection foci'''
+    """Assess and set protection foci"""
     universe = fo.getUniverse()
     for pid, pinfo in focus_manager.raw_planet_info.items():
         planet = pinfo.planet