Utility Functions

coc.utils.find(predicate: Callable[[T], Any], iterable: Iterable[T]) → Optional[T]

A helper to return the first element found in the sequence that meets the predicate.

For example:

leader = coc.utils.find(lambda m: m.trophies > 5000, clan.members)

would find the first ClanMember who has more than 5000 trophies and return it. If no members have more than 5000 trophies, then None is returned.

Parameters:

predicate – A function that returns a boolean-like result.
iterable (iterable) – The iterable to search through.

Return type:

The first item in the iterable which matches the predicate passed.

coc.utils.get(iterable: Iterable[T], **attrs: Any) → Optional[T]

A helper that returns the first item in an iterable that matches the attributes passed.

If no match is found, None is returned.

Example

member = utils.get(clan.members, level=100, name="Mathsman")
# returns the first member who has the name "Mathsman" and is level 100

member = utils.get(clan.members, role=coc.Role.leader)
# returns the clan leader

label = utils.get(player.labels, name="Competitive")
# returns the player's label if they have Competitive.

Parameters:

iterable (iterable) – The list of items to match the attributes from
**attrs – A series of kwargs that specify which attributes to match.

Return type:

The object from the iterable that matches the attributes passed, or None if not found.

coc.utils.from_timestamp(timestamp: str) → datetime: Parses the raw timestamp given by the API into a datetime.datetime object.

coc.utils.is_valid_tag(tag: str) → bool

Validates that a string is a valid Clash of Clans tag.

This uses the assumption that tags can only consist of the characters PYLQGRJCUV0289.

Example

from coc import utils

user_input = input("Please enter a tag")

if utils.is_valid_tag(user_input) is True:
    print("{} is a valid tag".format(user_input))
else:
    print("{} is not a valid tag".format(user_input))

Returns:: Whether the tag is a valid tag.
Return type:: bool

coc.utils.correct_tag(tag: str, prefix: str = '#') → str

Attempts to correct malformed Clash of Clans tags to match how they are formatted in game

Example

new_tag = utils.correct_tag(" 123aBc O")
# new_tag is "#123ABC0".

Parameters:

tag (str) – The tag to correct.
prefix (str) – The prefix to insert at the start of the tag. Defaults to #.

Returns:

The corrected tag.

Return type:

str

coc.utils.get_season_start(month: Optional[int] = None, year: Optional[int] = None) → datetime

Get the datetime that the season started.

This goes by the assumption that SC resets the season on the last monday of every month at 5am UTC.

Note

If you want the start of the current season, do not pass any parameters in, as doing so won’t check to ensure the season start is in the past.

Parameters:

month (Optional[int]) – The month to get the season start for. Defaults to the current month/season.
year (Optional[int]) – The year to get the season start for. Defaults to the current year/season.

Returns:

season_start – The start of the season.

Return type:

datetime.datetime

coc.utils.get_season_end(month: Optional[int] = None, year: Optional[int] = None) → datetime

Get the datetime that the season ends.

This goes by the assumption that SC resets the season on the last monday of every month at 5am UTC.

Note

If you want the end of the current season, do not pass any parameters in, as doing so won’t check to ensure the season end is in the future.

Parameters:

month (Optional[int]) – The month to get the season end for. Defaults to the current month/season.
year (Optional[int]) – The year to get the season end for. Defaults to the current year/season.

Returns:

season_end – The end of the season.

Return type:

datetime.datetime

coc.utils.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 – The start of the next or running clan games.
Return type:: datetime.datetime

coc.utils.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 – The end of the next or running clan games.
Return type:: datetime.datetime

coc.utils.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 7am UTC.

Note

If you want the start of the next or running raid weekend, do not pass any parameters in, for any other pass a datetime in the week before.

Parameters:: time (Optional[datetime]) – Some time in the week before the raid weekend you want the start of.
Returns:: raid_weekend_start – The start of the raid weekend.
Return type:: datetime.datetime

coc.utils.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 7am UTC.

Note

If you want the end of the next or running raid weekend, do not pass any parameters in, for any other pass a datetime in the week before.

Parameters:: time (Optional[datetime]) – Some time in the week before the raid weekend you want the end of.
Returns:: raid_weekend_end – The end of the raid weekend.
Return type:: datetime.datetime