Merge remote-tracking branch 'cocpy_main/g7_2.2.4_candidate' into g7_2.2.4_candidate

# Conflicts:
#	coc/abc.py
#	coc/client.py
#	coc/events.py
#	coc/events.pyi
#	coc/ext/fullwarapi/__init__.py
#	coc/players.py
#	coc/utils.py
#	docs/advanced/event.rst
#	docs/miscellaneous/changelog.rst

Author: Kuchenmampfer

coc/__init__.py

@@ -35,7 +35,7 @@
     ACHIEVEMENT_ORDER,
     BUILDER_TROOPS_ORDER,
     HERO_ORDER,
-    HERO_PETS_ORDER,
+    PETS_ORDER,
     HOME_TROOP_ORDER,
     SIEGE_MACHINE_ORDER,
     SPELL_ORDER,

coc/abc.py

@@ -25,8 +25,7 @@
 from pathlib import Path
 from typing import AsyncIterator, Any, Dict, Type, Optional, TYPE_CHECKING
 
-import coc
-from .enums import Resource
+from .enums import PETS_ORDER, Resource
 from .miscmodels import try_enum, Badge, TimeDelta
 from .iterators import PlayerIterator
 from .utils import CaseInsensitiveDict, UnitStat, _get_maybe_first
@@ -205,7 +204,7 @@ def _load_json_meta(cls, troop_meta, id, name, lab_to_townhall):
             cls.is_elixir_spell = True
         elif production_building == "Mini Spell Factory":
             cls.is_dark_spell = True
-        elif name in coc.HERO_PETS_ORDER:
+        elif name in PETS_ORDER:
             production_building = "Pet Shop"
 
         # load buildings
@@ -218,8 +217,8 @@ def _load_json_meta(cls, troop_meta, id, name, lab_to_townhall):
         else:
             # it is a troop or spell or siege
             prod_unit = buildings.get(production_building)
-            if "barrack" in production_building.lower() or "Spell Forge" == production_building or \
-                    "SiegeWorkshop" == production_building or "Mini Spell Factory" == production_building:
+            if production_building in ("SiegeWorkshop", "Spell Forge", "Mini Spell Factory",
+                                       "Dark Elixir Barrack", "Barrack", "Barrack2"):
                 min_prod_unit_level = troop_meta.get("BarrackLevel", [None, ])[0]
                 # there are some special troops, which have no BarrackLevel attribute
                 if not min_prod_unit_level:
@@ -259,8 +258,7 @@ def _load_json_meta(cls, troop_meta, id, name, lab_to_townhall):
                 return
 
         cls.lab_level = try_enum(UnitStat, laboratory_levels)
-        cls.housing_space = _get_maybe_first(troop_meta, "HousingSpace",
-                                             default=0)
+        cls.housing_space = _get_maybe_first(troop_meta, "HousingSpace", default=0)
         cls.speed = try_enum(UnitStat, troop_meta.get("Speed"))
         cls.level = cls.dps and UnitStat(range(1, len(cls.dps) + 1))
 
@@ -332,7 +330,7 @@ def _load_json(self, object_ids, english_aliases, lab_to_townhall):
         with open(self.FILE_PATH) as fp:
             data = ujson.load(fp)
 
-        for supercell_name, meta in data.items():
+        for c, [supercell_name, meta] in enumerate(data.items()):
             # Not interested if it doesn't have a TID, since it likely isn't a real troop.
             if not meta.get("TID"):
                 continue
@@ -352,7 +350,7 @@ def _load_json(self, object_ids, english_aliases, lab_to_townhall):
                             dict(self.data_object.__dict__))
             new_item._load_json_meta(
                 meta,
-                id=object_ids.get(supercell_name, 0),
+                id=object_ids.get(supercell_name, c),
                 name=english_aliases[meta["TID"][0]][0],
                 lab_to_townhall=lab_to_townhall,
             )
@@ -363,9 +361,8 @@ def _load_json(self, object_ids, english_aliases, lab_to_townhall):
         self.loaded = True
 
     def load(
-            self, data, townhall: int, default: Type[DataContainer] = None,
-            load_game_data: bool = True
-    ) -> DataContainer:
+            self, data: dict, townhall: int, default: Type[DataContainer] = None,
+            load_game_data: bool = True) -> DataContainer:
         if load_game_data is True:
             try:
                 item = self.item_lookup[data["name"]]

coc/enums.py

@@ -149,7 +149,7 @@ class Resource(Enum):
 
 HERO_ORDER = ["Barbarian King", "Archer Queen", "Grand Warden", "Royal Champion", "Battle Machine"]
 
-HERO_PETS_ORDER = [
+PETS_ORDER = [
     "L.A.S.S.I",
     "Electro Owl",
     "Mighty Yak",

coc/ext/fullwarapi/__init__.py

@@ -7,18 +7,18 @@
 
 from collections import namedtuple
 from datetime import datetime
-from typing import List, Optional, Union, Any, Generator
+from typing import Generator, List, Optional, Union
 
 import aiohttp
 
-from ... import ClanWar
+import coc
 from ...http import json_or_text
 from ...utils import correct_tag
 from ...wars import ClanWar
 
 LOG = logging.getLogger(__name__)
 
-AccessToken = namedtuple("AccessToken", ["token", "expires_at"])
+FWAccessToken = namedtuple("FWAccessToken", ["token", "expires_at"])
 
 
 def extract_expiry_from_jwt_token(token: Union[str, bytes]) -> Optional[datetime]:
@@ -46,7 +46,7 @@ def extract_expiry_from_jwt_token(token: Union[str, bytes]) -> Optional[datetime
         return None
 
 
-async def login(username: str, password: str, coc_client) -> "FullWarClient":
+async def login(username: str, password: str, coc_client: Union[coc.Client, coc.EventsClient]) -> "FullWarClient":
     """Eases logging into the API client.
 
     For more information on this project, please join the discord server - <discord.gg/Eaja7gJ>
@@ -60,16 +60,15 @@ async def login(username: str, password: str, coc_client) -> "FullWarClient":
         Your username as given on the discord server.
     password : str
         Your password as given on the discord server
-    coc_client: coc.Client
-        Client to use
+    coc_client : Union[coc.Client, coc.EventsClient]
+        A coc_client to grap the loop from and create the response objects with
     """
     if not isinstance(username, str) or not isinstance(password, str):
         raise TypeError("username and password must both be a string")
     if not username or not password:
         raise ValueError("username or password must not be an empty string.")
 
-    loop = asyncio.get_running_loop()
-    return FullWarClient(username, password, coc_client, loop)
+    return FullWarClient(username, password, coc_client)
 
 
 class FullWarClient:
@@ -86,9 +85,8 @@ class FullWarClient:
         Your username as given on the discord server.
     password : str
         Your password as given on the discord server
-    coc_client: coc.Client
+    coc_client: Union[coc.Client, coc.EventClient]
         Client to use
-
     loop : Optional[:class:`asyncio.AbstractEventLoop`]
         The :class:`asyncio.AbstractEventLoop` to use for HTTP requests.
         An :func:`asyncio.get_event_loop()` will be used if ``None`` is passed
@@ -99,12 +97,13 @@ class FullWarClient:
 
     __slots__ = ("username", "password", "coc_client", "loop", "key", "http_session")
 
-    def __init__(self, username: str, password: str, coc_client, loop: asyncio.AbstractEventLoop = None):
+    def __init__(self, username: str, password: str, coc_client: Union[coc.Client, coc.EventsClient],
+                 loop: asyncio.AbstractEventLoop = None):
         self.username = username
         self.password = password
         self.coc_client = coc_client
 
-        self.loop = loop or asyncio.get_event_loop()
+        self.loop = coc_client.loop or asyncio.get_event_loop()
         self.key = None  # set in get_key()
 
         self.http_session = aiohttp.ClientSession(loop=self.loop)
@@ -136,7 +135,7 @@ async def _request(self, method, url, *, token_request: bool = False, **kwargs):
                 return await self._request(method, url, **kwargs)
 
     async def _get_key(self):
-        if not self.key or (self.key.expires_at < datetime.utcnow()):
+        if not self.key or (self.key.expires_at and self.key.expires_at < datetime.utcnow()):
             await self._refresh_key()
 
         return self.key.token
@@ -148,9 +147,9 @@ async def _refresh_key(self):
         }
 
         payload = await self._request("POST", "/login", token_request=True, json=data)
-        self.key = AccessToken(payload["access_token"], extract_expiry_from_jwt_token(payload["access_token"]))
+        self.key = FWAccessToken(payload["access_token"], extract_expiry_from_jwt_token(payload["access_token"]))
 
-    async def war_result(self, clan_tag: str, preparation_start: int = 0) -> ClanWar | None:
+    async def war_result(self, clan_tag: str, preparation_start: int = 0) -> Optional[ClanWar]:
         """Get a stored war result.
 
         Parameters
@@ -162,7 +161,6 @@ async def war_result(self, clan_tag: str, preparation_start: int = 0) -> ClanWar
 
         Returns
         --------
-        #NOOOOO idea if this is correct xD
         Optional[:class:`ClanWar`]
             War result, or ``None`` if no war found.
         """
@@ -174,7 +172,7 @@ async def war_result(self, clan_tag: str, preparation_start: int = 0) -> ClanWar
         except (IndexError, KeyError, TypeError, ValueError):
             return None
 
-    async def war_result_log(self, clan_tag: str) -> Generator[ClanWar, Any, None] | None:
+    async def war_result_log(self, clan_tag: str) -> Optional[Generator[ClanWar]]:
         """Get all stored war results for a clan.
 
         Parameters
@@ -184,9 +182,8 @@ async def war_result_log(self, clan_tag: str) -> Generator[ClanWar, Any, None] |
 
         Returns
         --------
-        #NOOOOO idea if this is correct xD
-        Optional[:class:`ClanWar`]
-            List of war results, or ``None`` if no wars found.
+        Optional[Generator[:class:`ClanWar`]]
+            Generator of war results, or ``None`` if no wars found.
         """
         data = await self._request("GET",
                                    f"/war_result_log?clan_tag={correct_tag(clan_tag, '%23')}")
@@ -206,8 +203,9 @@ async def register_war(self, clan_tag: str, preparation_start: int = 0):
         clan_tag : str
             The clan to register a war for
         preparation_start: int
-            Preparation time of the war
+            Preparation time of the war.
         """
         return await self._request("POST",
                                    f"/register_war?clan_tag={correct_tag(clan_tag, '%23')}"
                                    f"&prep_start={str(preparation_start)}")
+

coc/players.py

@@ -35,7 +35,7 @@
     UNRANKED_LEAGUE_DATA,
     ACHIEVEMENT_ORDER,
     SUPER_TROOP_ORDER,
-    HERO_PETS_ORDER,
+    PETS_ORDER,
 )
 from .abc import BasePlayer
 from .hero import Hero, Pet
@@ -237,6 +237,7 @@ class Player(ClanMember):
         "war_opted_in",
         "_achievements",
         "_heroes",
+        "_pets",
         "_labels",
         "_spells",
         "_home_troops",
@@ -262,7 +263,7 @@ class Player(ClanMember):
         "_cs_home_troops",
         "_cs_builder_troops",
         "_cs_siege_machines",
-        "_cs_hero_pets",
+        "_cs_pets",
         "_cs_super_troops",
         "_cs_heroes",
         "_cs_spells",
@@ -281,6 +282,7 @@ def __init__(self, *, data, client, load_game_data=None, **_):
         self._home_troops: dict = {}
         self._builder_troops: dict = {}
         self._super_troops: list = []
+        self._pets = None # type: Optional[dict]
 
         self.achievement_cls = Achievement
         self.hero_cls = Hero
@@ -335,7 +337,7 @@ def _from_data(self, data: dict) -> None:
         if self._game_files_loaded:
             pet_lookup = [p.name for p in self._client._pet_holder.items]
         else:
-            pet_lookup = HERO_PETS_ORDER
+            pet_lookup = PETS_ORDER
 
         self._iter_labels = (label_cls(data=ldata, client=self._client) for ldata in data_get("labels", []))
         self._iter_achievements = (achievement_cls(data=adata) for adata in data_get("achievements", []))
@@ -400,11 +402,12 @@ def load_game_data(self):
         # if self._game_files_loaded:
         #     return True
 
-        holders = (self._client._troop_holder, self._client._hero_holder, self._client._spell_holder)
+        holders = (self._client._troop_holder, self._client._hero_holder, self._client._spell_holder,
+                   self._client._pet_holder)
         if not all(holder.loaded for holder in holders):
             self._client._load_holders()
 
-        for items, holder in zip((self.troops, self.heroes, self.spells), holders):
+        for items, holder in zip((self.troops, self.heroes, self.spells, self.pets), holders):
             for item in items:
                 if not item.is_loaded:
                     if isinstance(item, Troop):
@@ -435,7 +438,7 @@ def achievements(self) -> List[Achievement]:
         return list(sorted_achievements.values())
 
     def get_achievement(self, name: str, default_value=None) -> Optional[Achievement]:
-        """Returns an achievement with the given name.
+        """Gets an achievement with the given name.
 
         Parameters
         -----------
@@ -544,18 +547,42 @@ def siege_machines(self) -> List[Troop]:
         troops = (t for t in self.troops if t.name in SIEGE_MACHINE_ORDER or t.is_siege_machine)
         return list(sorted(troops, key=lambda t: order.get(t.name, 0)))
 
-    @cached_property("_cs_hero_pets")
-    def hero_pets(self) -> List[Pet]:
+    @cached_property("_cs_pets")
+    def pets(self) -> List[Pet]:
         """List[:class:`Pet`]: A :class:`List` of the player's hero pets.
 
         This will return hero pets in the order found in the Pet House in-game.
 
         This includes:
         - Hero pets only.
         """
-        order = {k: v for v, k in enumerate(HERO_PETS_ORDER)}
+        order = {k: v for v, k in enumerate(PETS_ORDER)}
         return list(sorted(self._iter_pets, key=lambda t: order.get(t.name, 0)))
 
+    def get_pet(self, name: str, default_value=None) -> Optional[Pet]:
+        """Gets the pet with the given name.
+
+        Parameters
+        -----------
+        name: :class:`str`
+            The name of a pet as found in-game.
+        default_value:
+            The default value to return if a pet with ``name`` is not found. Defaults to ``None``.
+
+        Returns
+        --------
+        Optional[:class:`Pet`]
+            The returned pet or the ``default_value`` if not found, which defaults to ``None``.
+
+        """
+        if not self._pets:
+            _ = self._pets
+
+        try:
+            return self._pets[name]
+        except KeyError:
+            return default_value
+
     @cached_property("_cs_super_troops")
     def super_troops(self) -> List[Troop]:
         """List[:class:`Troop`]: A :class:`List` of the player's super troops.
@@ -573,7 +600,7 @@ def super_troops(self) -> List[Troop]:
         return list(sorted(self._super_troops, key=lambda t: order.get(t.name, 0)))
 
     def get_troop(self, name: str, is_home_troop=None, default_value=None) -> Optional[Troop]:
-        """Returns a troop with the given name.
+        """Gets a troop with the given name.
 
         Parameters
         -----------
@@ -626,16 +653,19 @@ def heroes(self) -> List[Hero]:
         return list(sorted_heroes.values())
 
     def get_hero(self, name: str, default_value=None) -> Optional[Hero]:
-        """
-        Gets the hero
+        """Gets the hero with the given name.
+
         Parameters
-        ----------
-        name
-        default_value
+        -----------
+        name: :class:`str`
+            The name of a hero as found in-game.
+        default_value:
+            The default value to return if a hero with ``name`` is not found. Defaults to ``None``.
 
         Returns
-        -------
-        Hero
+        --------
+        Optional[:class:`Hero`]
+            The returned hero or the ``default_value`` if not found, which defaults to ``None``.
 
         """
         if not self._heroes:
@@ -661,7 +691,7 @@ def spells(self) -> List[Spell]:
                     key=lambda s: order.get(s.name, 0)))
 
     def get_spell(self, name: str, default_value=None) -> Optional[Spell]:
-        """Returns a spell with the given name.
+        """Gets the spell with the given name.
 
         Parameters
         -----------