Utility Functions¶
- coc.utils.find(predicate: Callable[[coc.utils.T], Any], iterable: Iterable[coc.utils.T]) Optional[coc.utils.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, thenNone
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: Iterable[coc.utils.T], **attrs: Any) Optional[coc.utils.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.
- Returns
- Return type
The object from the iterable that matches the attributes passed, or
None
if not found.
- coc.utils.from_timestamp(timestamp: str) datetime.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
- 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".
- coc.utils.get_season_start(month: Optional[int] = None, year: Optional[int] = None) datetime.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
- Returns
season_start – The start of the season.
- Return type
- coc.utils.get_season_end(month: Optional[int] = None, year: Optional[int] = None) datetime.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
- Returns
season_end – The end of the season.
- Return type