Utility Functions

coc.utils.find(predicate, iterable)

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.

Returns

Return type

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

coc.utils.get(iterable, **attrs)

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.

Returns

Return type

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

coc.utils.from_timestamp(timestamp)

Parses the raw timestamp given by the API into a datetime.datetime object.

coc.utils.is_valid_tag(tag)

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, prefix='#')

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

Example

‘ 123aBc O’ -> ‘#123ABC0’

coc.utils.get_season_start(month=None, year=None)

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 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=None, year=None)

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