Merge pull request #221 from mathsman5133/feature/custom-classes

Feature/custom classes

Author: MagicTheDev

coc/__init__.py

@@ -22,7 +22,7 @@
 SOFTWARE.
 """
 
-__version__ = "3.1.0"
+__version__ = "3.2.0"
 
 from .abc import BasePlayer, BaseClan
 from .clans import RankedClan, Clan
@@ -54,7 +54,7 @@
     GatewayError,
     PrivateWarLog,
 )
-from .hero import Hero, Pet
+from .hero import Equipment, Hero, Pet
 from .http import BasicThrottler, BatchThrottler, HTTPClient
 from .iterators import (
     ClanIterator,

coc/war_clans.py

@@ -66,6 +66,11 @@ class WarClan(BaseClan):
         :class:`int`: Total attacks used by clan this war.
     max_stars:
         :class:`int`: Total possible stars achievable.
+    total_attacks:
+        :class:`int`: Total possible number of attacks usable by clan this war
+    member_cls: :class:`coc.ClanMember`
+        The type which the members found in :attr:`Clan.members` will be of.
+        Ensure any overriding of this inherits from :class:`coc.ClanMember`.
     """
 
     __slots__ = (
@@ -76,6 +81,7 @@ class WarClan(BaseClan):
         "exp_earned",
         "max_stars",
         "total_attacks",
+        "member_cls",
         "_war",
         "_client",
 
@@ -86,9 +92,10 @@ class WarClan(BaseClan):
         "_cs_members",
     )
 
-    def __init__(self, *, data, client, war):
+    def __init__(self, *, data, client, war, **kwargs):
         self._war = war
         self._members = {}
+        self.member_cls = kwargs.pop('member_cls', ClanWarMember)
 
         super().__init__(data=data, client=client)
         self._from_data(data)
@@ -110,7 +117,7 @@ def _from_data(self, data: dict) -> None:
             self.total_attacks: int = (data_get("teamSize") or 0) * 3
 
         self._iter_members = (
-            ClanWarMember(data=mdata, client=self._client, war=self._war, clan=self)
+            self.member_cls(data=mdata, client=self._client, war=self._war, clan=self)
             for mdata in data_get("members", [])
         )
 

coc/war_members.py

@@ -52,6 +52,9 @@ class ClanWarMember(BasePlayer):
         :class:`ClanWar`: The current war this member is in.
     clan:
         :class:`WarClan`: The member's clan.
+    attack_cls: :class:`coc.WarAttack`
+        The type which the attacks in :attr:`ClanWarMember.attacks` will be of.
+        Ensure any overriding of this inherits from :class:`coc.WarAttack`.
     """
 
     __slots__ = (
@@ -65,16 +68,18 @@ class ClanWarMember(BasePlayer):
         "map_position",
         "war",
         "clan",
+        "attack_cls",
         "_client",
         "_attacks",
     )
 
-    def __init__(self, *, data, client, war, clan):
+    def __init__(self, *, data, client, war, clan, **kwargs):
         super().__init__(data=data, client=client)
         self._client = client
         self._attacks = []
         self.war = war  # type: ClanWar
         self.clan = clan  # type: WarClan
+        self.attack_cls = kwargs.pop('attack_cls', WarAttack)
         self._from_data(data)
 
     def _from_data(self, data):
@@ -87,7 +92,7 @@ def _from_data(self, data):
         self.defense_count: int = data_get("opponentAttacks")
 
         self.__iter_attacks = (
-            WarAttack(data=adata, client=self._client, war=self.war) for adata in data_get("attacks", [])
+            self.attack_cls(data=adata, client=self._client, war=self.war) for adata in data_get("attacks", [])
         )
 
         self._best_opponent_attacker: str = data_get("bestOpponentAttack", {}).get("attackerTag")

coc/wars.py

@@ -66,6 +66,9 @@ class ClanWar:
         :class:`ClanWarLeagueGroup`: The war's league group. This is ``None`` unless this is a Clan League War.
     attacks_per_member:
         :class:`int`: The number of attacks each member has this war.
+    clan_cls: :class:`WarClan`
+        the type `war.clan` and `war.opponent` will be of.
+        Ensure any overriding of this inherits from :class:`coc.WarClan`.
     """
 
     __slots__ = (
@@ -81,6 +84,7 @@ class ClanWar:
         "opponent",
         "league_group",
         "attacks_per_member",
+        "clan_cls",
         "_response_retry",
         "_raw_data"
     )
@@ -90,6 +94,7 @@ def __init__(self, *, data, client, **kwargs):
         self._client = client
         self._raw_data = data if client and client.raw_attribute else None
         self.clan_tag = kwargs.pop("clan_tag", None)
+        self.clan_cls = kwargs.pop('clan_cls', WarClan)
         self._from_data(data)
 
         self.clan_tag = self.clan and self.clan.tag or self.clan_tag
@@ -117,14 +122,14 @@ def _from_data(self, data: dict) -> None:
         # depending on the way the game stores it internally. This isn't very helpful as we always want it
         # from the perspective of the tag we provided, so switch them around if it isn't correct.
         if clan_data and clan_data.get("tag", self.clan_tag) == self.clan_tag:
-            self.clan = try_enum(WarClan, data=clan_data, client=self._client,
+            self.clan = try_enum(self.clan_cls, data=clan_data, client=self._client,
                                  war=self)
-            self.opponent = try_enum(WarClan, data=data_get("opponent"),
+            self.opponent = try_enum(self.clan_cls, data=data_get("opponent"),
                                      client=self._client, war=self)
         else:
-            self.clan = try_enum(WarClan, data=data_get("opponent"),
+            self.clan = try_enum(self.clan_cls, data=data_get("opponent"),
                                  client=self._client, war=self)
-            self.opponent = try_enum(WarClan, data=clan_data,
+            self.opponent = try_enum(self.clan_cls, data=clan_data,
                                      client=self._client, war=self)
 
     @property

docs/conf.py

@@ -15,7 +15,7 @@
 project = 'coc'
 copyright = '2022, mathsman5133'
 author = 'mathsman5133'
-release = '3.1.0'
+release = '3.2.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/miscellaneous/changelog.rst

@@ -7,6 +7,21 @@ Changelog
 This page keeps a fairly detailed, human readable version
 of what has changed, and whats new for each version of the lib.
 
+v3.2.0
+------
+
+Additions:
+~~~~~~~~~~
+- Added custom class support to a few more classes:
+
+  - :class:`ClanWarMember` now supports the :attr:`attack_cls` attribute to customize the type returned in
+    :func:`ClanWarMember.attacks` (and, by extension also :func:`WarClan.attacks` and :func:`ClanWar.attacks`)
+  - :class:`WarClan` now supports the :attr:`member_cls` attribute to customize the type returned in
+    :func:`WarClan.members` (and, by extension also :func:`ClanWar.members`)
+  - :class:`ClanWar` now supports the :attr:`clan_cls` attribute to customize the types of
+    :func:`ClanWar.clan` and :func:`ClanWar.opponent`
+  - the :class:`Equipment` class can now be imported as ``coc.Equipment``
+
 v3.1.0
 ------
 

pyproject.toml

@@ -7,7 +7,7 @@ name = "coc.py"
 authors = [{ name = "mathsman5133" }]
 maintainers = [{ name = "majordoobie" }, { name = "MagicTheDev" }, { name = "Kuchenmampfer" },
     { name = "lukasthaler"}, { name = "doluk"}]
-version = "3.1.0"
+version = "3.2.0"
 description = "A python wrapper for the Clash of Clans API"
 requires-python = ">=3.7.3"
 readme = "README.rst"