add get_clan_games_[start|end] utils and a few event examples

Author: Kuchenmampfer

coc/events.py

@@ -35,7 +35,7 @@
 from .players import Player
 from .wars import ClanWar
 from .errors import Maintenance, PrivateWarLog
-from .utils import correct_tag, get_season_end
+from .utils import correct_tag, get_season_end, get_clan_games_start, get_clan_games_end
 
 LOG = logging.getLogger(__name__)
 DEFAULT_SLEEP = 10
@@ -787,21 +787,21 @@ async def _raid_poller(self):
             age = 0
             while self.loop.is_running():
                 try:
-                    [raidlog_entry] = await self.get_raidlog("#2PP", limit=1)
-                    raidlog_entry: coc.raid.RaidLogEntry
+                    [raid_log_entry] = await self.get_raidlog("#2PP", limit=1)
+                    raid_log_entry: coc.raid.RaidLogEntry
                 except Maintenance:
                     await asyncio.sleep(15)
                 except Exception:
                     await asyncio.sleep(DEFAULT_SLEEP)
                 else:
-                    if raidlog_entry.start_time.seconds_until + age > 0 and raidlog_entry.end_time.seconds_until > 0:
+                    if raid_log_entry.start_time.seconds_until + age > 0 and raid_log_entry.end_time.seconds_until > 0:
                         # raid started
                         self.dispatch("raid_weekend_start")
-                    elif raidlog_entry.end_time.seconds_until + age > 0 > raidlog_entry.end_time.seconds_until:
+                    elif raid_log_entry.end_time.seconds_until + age > 0 > raid_log_entry.end_time.seconds_until:
                         # raid ended
                         self.dispatch("raid_weekend_end")
                     # sleep for response_retry + 1
-                    age = raidlog_entry._response_retry + 1
+                    age = raid_log_entry._response_retry + 1
                     await asyncio.sleep(age)
         except asyncio.CancelledError:
             pass
@@ -825,18 +825,16 @@ async def _end_of_season_poller(self):
     async def _clan_games_poller(self):
         try:
             while self.loop.is_running():
-                mute = now = datetime.utcnow()
-                if now.day > 28 or (now.day == 28 and now.hour > 8):
-                    mute += timedelta(days=7)
-                    mute = datetime(year=mute.year, month=mute.month, day=22, hour=8, minute=0, second=0)
+                clan_games_start = get_clan_games_start()
+                clan_games_end = get_clan_games_end()
+                now = datetime.utcnow()
+                if now < clan_games_start:
                     event = "clan_games_start"
-                elif now.day > 22 or (now.day == 22 and now.hour > 8):
-                    mute = datetime(year=now.year, month=now.month, day=28, hour=8, minute=0, second=0)
-                    event = "clan_games_end"
+                    mute_time = clan_games_start - now
                 else:
-                    mute = datetime(year=now.year, month=now.month, day=22, hour=8, minute=0, second=0)
-                    event = "clan_games_start"
-                await asyncio.sleep((mute - now).total_seconds())
+                    event = "clan_games_end"
+                    mute_time = clan_games_end - now
+                await asyncio.sleep(mute_time.total_seconds())
                 self.dispatch(event)
         except asyncio.CancelledError:
             pass

coc/utils.py

@@ -367,10 +367,68 @@ def get_season_end(month: Optional[int] = None, year: Optional[int] = None) -> d
     return get_season_start(month, year)
 
 
+def get_clan_games_start(time: Optional[datetime] = None) -> datetime:
+    """Get the datetime that the next clan games will start.
+
+    This goes by the assumption that clan games start at 8am UTC at the 22nd of each month.
+
+    .. note::
+
+        If you want the start of the next or running clan games, do not pass any parameters in,
+        for any other pass a datetime in the month before.
+
+    Parameters
+    ----------
+    time: Optional[datetime]
+        Some time in the month before the clan games you want the start of.
+
+    Returns
+    -------
+    clan_games_start: :class:`datetime.datetime`
+        The start of the next or running clan games.
+    """
+    if time is None:
+        time = datetime.utcnow()
+    month = time.month
+    this_months_cg_end = datetime(year=time.year, month=time.month, day=28, hour=8, minute=0, second=0)
+    if time > this_months_cg_end:
+        month += 1
+    return datetime(year=time.year, month=month, day=22, hour=8, minute=0, second=0)
+
+
+def get_clan_games_end(time: Optional[datetime] = None) -> datetime:
+    """Get the datetime that the next clan games will end.
+
+    This goes by the assumption that clan games end at 8am UTC at the 28th of each month.
+
+    .. note::
+
+        If you want the end of the next or running clan games, do not pass any parameters in,
+        for any other pass a datetime in the month before.
+
+    Parameters
+    ----------
+    time: Optional[datetime]
+        Some time in the month before the clan games you want the end of.
+
+    Returns
+    -------
+    clan_games_end: :class:`datetime.datetime`
+        The end of the next or running clan games.
+    """
+    if time is None:
+        time = datetime.utcnow()
+    month = time.month
+    this_months_cg_end = datetime(year=time.year, month=time.month, day=28, hour=8, minute=0, second=0)
+    if time > this_months_cg_end:
+        month += 1
+    return datetime(year=time.year, month=month, day=28, hour=8, minute=0, second=0)
+
+
 def get_raid_weekend_start(time: Optional[datetime] = None) -> datetime:
     """Get the datetime that the raid weekend will start.
 
-    This goes by the assumption that raid weekends start at friday 7 UTC.
+    This goes by the assumption that raid weekends start at friday 7am UTC.
 
     .. note::
 
@@ -384,10 +442,9 @@ def get_raid_weekend_start(time: Optional[datetime] = None) -> datetime:
 
     Returns
     -------
-    raid_weekend_end: :class:`datetime.datetime`
-        The end of the raid weekend.
+    raid_weekend_start: :class:`datetime.datetime`
+        The start of the raid weekend.
     """
-    # Shift the time so that we can pretend the raid ends just after midnight
     if time is None:
         time = datetime.utcnow()
     time = get_raid_weekend_end(time)
@@ -398,7 +455,7 @@ def get_raid_weekend_start(time: Optional[datetime] = None) -> datetime:
 def get_raid_weekend_end(time: Optional[datetime] = None) -> datetime:
     """Get the datetime that the raid weekend will end.
 
-    This goes by the assumption that raid weekends end at monday 7 UTC.
+    This goes by the assumption that raid weekends end at monday 7am UTC.
 
     .. note::
 

docs/advanced/utils.rst

@@ -17,6 +17,10 @@ Utility Functions
 
 .. autofunction:: coc.utils.get_season_end
 
+.. autofunction:: coc.utils.get_clan_games_start
+
+.. autofunction:: coc.utils.get_clan_games_end
+
 .. autofunction:: coc.utils.get_raid_weekend_start
 
 .. autofunction:: coc.utils.get_raid_weekend_end

docs/miscellaneous/changelog.rst

@@ -13,10 +13,11 @@ Additions:
 ~~~~~~~~~~
 
 - Added new events :func:`ClientEvents.raid_weekend_start`, :func:`ClientEvents.raid_weekend_end`,
-  :func:`ClientEvents.clangames_start`, :func:`ClientEvents.clangames_end`,
+  :func:`ClientEvents.clan_games_start`, :func:`ClientEvents.clan_games_end`,
   :func:`WarEvents.new_war` and :func:`ClanEvents.member_versus_rank`
 
-- Added utility functions :func:`utils.get_raid_weekend_start`, :func:`utils.get_raid_weekend_end`
+- Added utility functions :func:`utils.get_clan_games_start`, :func:`utils.get_clan_games_end`
+  :func:`utils.get_raid_weekend_start` and :func:`utils.get_raid_weekend_end`
 
 - Added clan capital leaderboards
 

examples/events_example.py

@@ -56,6 +56,11 @@ async def current_war_stats(attack, war):
         f"attacked ({attack.defender.map_position}).{attack.defender} of {attack.defender.clan}")
 
 
+@coc.WarEvents.new_war()
+async def new_war(war):
+    log.info(f"New war against {war.opponent.name} detected.")
+
+
 """Player Events"""
 
 
@@ -95,13 +100,22 @@ async def on_maintenance():
 
 @coc.ClientEvents.maintenance_completion()
 async def on_maintenance_completion(time_started):
-    log.info("Maintenace Ended; started at %s", time_started)
+    log.info(f"Maintenace Ended; started at {time_started}")
 
 
 @coc.ClientEvents.new_season_start()
 async def season_started():
-    log.info("New season started, and will finish at %s",
-             str(utils.get_season_end()))
+    log.info(f"New season started, and will finish at {str(utils.get_season_end())}")
+
+
+@coc.ClientEvents.clan_games_end()
+async def clan_games_ended():
+    log.info(f"Clan games have ended. The next ones will start at {str(utils.get_clan_games_start())}")
+
+
+@coc.ClientEvents.raid_weekend_start()
+async def raid_weekend_started():
+    log.info(f"A new Raid Weekend started. It will last until {str(utils.get_raid_weekend_end())}")
 
 
 async def main() -> None:
@@ -150,7 +164,7 @@ def emit(self, record) -> None:
                 sys.exit(0)
 
         log.addHandler(Handler())
-        # we don't wanna wait forever for an event, so if
+        # we don't want to wait forever for an event, so if
         # it sets up OK lets call it quits.
         await asyncio.sleep(20)
         _loop = asyncio.get_event_loop()