Models¶

These are the data models used by the API. All calls will return one of these

Due to the unpredictable nature of the API and what it returns, all attributes have the possibility of being None. However, as much as possible, the library tries to return an object most appropriate to results returned.

Due to this, there are many objects for what may seem like similar things.

Clans¶

Base Clan¶

class coc.BaseClan¶

An ABC that implements some common operations on clans, regardless of type.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

Methods:

get_detailed_members([cls, load_game_data])

Get detailed player information for every player in the clan.

Attributes:

share_link

str - A formatted link to open the clan in-game

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

property share_link: str¶: str - A formatted link to open the clan in-game

Player Clan¶

class coc.PlayerClan¶

Represents a clan that belongs to a player.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

Methods:

get_detailed_members([cls, load_game_data])

Get detailed player information for every player in the clan.

Attributes:

share_link

str - A formatted link to open the clan in-game

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

property share_link: str¶: str - A formatted link to open the clan in-game

Ranked Clan¶

class coc.RankedClan¶

Represents the clan object returned by leader-board rankings.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

location¶

The clan’s location.

Type: Location

member_count¶

The number of members in the clan.

Type: int

points¶

The clan’s trophy-count. If retrieving info for versus leader-boards, this will be None.

Type: int

versus_points¶

The clan’s versus trophy count. If retrieving info for regular leader boards, this will be None.

Type: int

rank¶

The clan’s rank in the leader board.

Type: int

previous_rank¶

The clan’s rank in the previous season’s leaderboard.

Type: int

Methods:

get_detailed_members([cls, load_game_data])

Get detailed player information for every player in the clan.

Attributes:

share_link

str - A formatted link to open the clan in-game

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

property share_link: str¶: str - A formatted link to open the clan in-game

War Clan¶

class coc.WarClan¶

Represents a War Clan that the API returns.

Note

If this is called via ClanWarLog.clan, then WarClan.members, WarClan.attacks and WarClan.defenses will be empty.

If this is called via ClanWarLog.opponent, then WarClan.members, WarClan.attacks and WarClan.defenses will be empty. WarClan.exp_earned and WarClan.attacks will be None.

If this is called via ClanWar.clan or ClanWar.opponent then WarClan.exp_earned will be None.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

stars¶: int: Number of stars by clan this war.

destruction¶: float: Destruction as a percentage.

exp_earned¶: int: Total XP earned by clan this war.

attacks_used¶: int: Total attacks used by clan this war.

max_stars¶: int: Total possible stars achievable.

Attributes:

`is_opponent`	Indicates whether the clan is the opponent.
`share_link`	`str` - A formatted link to open the clan in-game

Methods:

`get_detailed_members`([cls, load_game_data])	Get detailed player information for every player in the clan.
`get_member`(tag)	Get a member of the clan for the given tag, or `None` if not found.

attacks¶

Returns all clan member’s attacks this war. This is sorted by attack order.

Type: List[WarAttack]

defenses¶

Returns all clan member’s defenses this war. This is sorted by attack order.

Equivalent to the other team’s .attacks property.

Type: List[WarAttack]

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

get_member(tag: str) → Optional[coc.war_members.ClanWarMember]¶

Get a member of the clan for the given tag, or None if not found.

Returns: The clan member who matches the tag.
Return type: Optional[ClanWarMember]

property is_opponent: bool¶

Indicates whether the clan is the opponent.

Type: bool

members¶

A list of members that are in the war. This is sorted by ClanWarMember.map_position

Type: List[ClanWarMember]

property share_link: str¶: str - A formatted link to open the clan in-game

Clan War League Clan¶

class coc.ClanWarLeagueClan¶

Represents a Clan War League Clan.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

Methods:

get_detailed_members([cls, load_game_data])

Get detailed player information for every player in the clan.

Attributes:

share_link

str - A formatted link to open the clan in-game

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

members¶

A list of players participating in this clan war league season.

This list is selected when the clan chooses to participate in CWL, and will not change throughout the season. It is sometimes referred to as the master roster.

Type: List[ClanWarLeagueClanMember]

property share_link: str¶: str - A formatted link to open the clan in-game

Clan¶

class coc.Clan¶

Represents a Clash of Clans clan.

tag¶

The clan’s tag

Type: str

name¶

The clan’s name

Type: str

badge¶

The clan’s badge

Type: Badge

level¶

The clan’s level.

Type: int

type¶

The clan’s type for accepting members. This could be open, inviteOnly or closed.

Type: str

description¶

The clan’s public description.

Type: str

location¶

The clan’s location.

Type: Location

points¶

The clan’s trophy count. This is calculated according to members’ trophy counts.

Type: int

versus_points¶

The clan’s versus trophy count. This is calculated according to members’ versus trophy counts.

Type: int

required_trophies¶

The minimum trophies required to apply to this clan.

Type: int

war_frequency¶

The frequency for when this clan goes to war. For example, this could be always.

Type: str

war_win_streak¶

The clan’s current war winning streak.

Type: int

war_wins¶

The number of wars the clan has won.

Type: int

war_ties¶

The number of wars the clan has tied.

Type: int

war_losses¶

The number of wars the clan has lost.

Type: int

public_war_log¶

Indicates if the clan has a public war log. If this is False, operations to find the clan’s current war may raise PrivateWarLog.

Type: bool

member_count¶

The number of members in the clan.

Type: int

label_cls¶

The type which the labels found in Clan.labels will be of. Ensure any overriding of this inherits from coc.Label.

Type: coc.Label

member_cls¶

The type which the members found in Clan.members will be of. Ensure any overriding of this inherits from coc.ClanMember.

Type: coc.ClanMember

war_league¶

The clan’s CWL league.

Type: coc.WarLeague

Methods:

`get_detailed_members`([cls, load_game_data])	Get detailed player information for every player in the clan.
`get_member`(tag)	Return a `ClanMember` with the tag provided.
`get_member_by`(**attrs)	Returns the first `ClanMember` that meets the attributes passed

Attributes:

share_link

str - A formatted link to open the clan in-game

get_detailed_members(cls: Type[Player] = None, load_game_data: bool = None) → AsyncIterator[Player]¶

Get detailed player information for every player in the clan.

This returns a PlayerIterator which fetches all player tags in the clan in parallel.

Example

clan = await client.get_clan('tag')

async for player in clan.get_detailed_members():
    print(player.name)

Yields: Player – A full player object of a clan member.

get_member(tag: str) → Optional[coc.players.ClanMember]¶

Return a ClanMember with the tag provided. Returns None if not found.

Example

clan = await client.get_clan('clan_tag')
member = clan.get_member('player_tag')

Returns: The member who matches the tag provided
Return type: Optional[ClanMember]

get_member_by(**attrs) → Optional[coc.players.ClanMember]¶

Returns the first ClanMember that meets the attributes passed

This search implements the coc.utils.get() function

Example

labels¶

A List of Label that the clan has.

Type: List[Label]

members¶

A list of members that belong to the clan.

Type: List[ClanMember]

property share_link: str¶: str - A formatted link to open the clan in-game

Players¶

Base Player¶

class coc.BasePlayer¶

An ABC that implements some common operations on players, regardless of type.

tag¶

The player’s tag

Type: str

name¶

The player’s name

Type: str

Attributes:

share_link

str - A formatted link to open the player in-game

property share_link: str¶: str - A formatted link to open the player in-game

Clan Member¶

class coc.ClanMember¶

Represents a Clash of Clans Clan Member.

tag¶

The player’s tag

Type: str

name¶

The player’s name

Type: str

clan¶

The player’s clan. If the player is clanless, this will be None.

Type: Optional[Clan]

role¶

The member’s role in a clan. To get a string as rendered in-game, do str(member.role).

Type: Role

exp_level¶

The member’s experience level.

Type: int

league¶

The member’s current league.

Type: League

trophies¶

The member’s trophy count.

Type: int

versus_trophies¶

The member’s versus trophy count.

Type: int

clan_rank¶

The member’s rank in the clan.

Type: int

clan_previous_rank¶

The member’s rank before the last leaderboard change (ie if Bob overtakes Jim in trophies, and they switch ranks on the leaderboard, and you want to find out their previous rankings, this will help.).

Type: int

donations¶

The member’s donation count for this season.

Type: int

received¶

The member’s donations received count for this season.

Type: int

clan_cls¶

The class to use to create the ClanMember.clan attribute. Ensure any overriding of this inherits from coc.Clan or coc.PlayerClan.

Type: coc.Clan

league_cls¶

The class to use to create the Clanmember.league attribute. Ensure any overriding of this inherits from coc.League.

Type: coc.League

Methods:

get_detailed_clan()

Get detailed clan details for the player’s clan.

Attributes:

share_link

str - A formatted link to open the player in-game

await get_detailed_clan() → Optional[Clan]¶

Get detailed clan details for the player’s clan. If the player’s clan is None,this will return None.

Example

player = await client.get_player('tag')
clan = await player.get_detailed_clan()

property share_link: str¶: str - A formatted link to open the player in-game

Ranked Player¶

class coc.RankedPlayer¶

Represents a leaderboard-ranked player.

attack_wins¶

The player’s number of attack wins. If retrieving info for versus leader-boards, this will be None.

Type: int

defense_wins¶

The player’s number of defense wins. If retrieving info for versus leader-boards, this will be None.

Type: int

versus_trophies¶

The player’s versus trophy count. If retrieving info for regular leader-boards, this will be None.

Type: int

rank¶

The player’s rank in the clan leaderboard.

Type: int

previous_rank¶

The member’s rank before the last clan leaderboard change (ie if Bob overtakes Jim in trophies, and they switch ranks on the leaderboard, and you want to find out their previous rankings, this will help.).

Type: int

Methods:

get_detailed_clan()

Get detailed clan details for the player’s clan.

Attributes:

share_link

str - A formatted link to open the player in-game

await get_detailed_clan() → Optional[Clan]¶

Get detailed clan details for the player’s clan. If the player’s clan is None,this will return None.

Example

player = await client.get_player('tag')
clan = await player.get_detailed_clan()

property share_link: str¶: str - A formatted link to open the player in-game

Clan War League Clan Member¶

class coc.ClanWarLeagueClanMember¶

Represents a clan member who is a part of the Clan War League master roster.

tag¶

The player’s tag

Type: str

name¶

The player’s name

Type: str

town_hall¶

The player’s town hall level.

Type: int

Attributes:

share_link

str - A formatted link to open the player in-game

property share_link: str¶: str - A formatted link to open the player in-game

Clan War Member¶

class coc.ClanWarMember¶

Represents a War Member that the API returns. Depending on which method calls this, some attributes may be None.

tag¶

The player’s tag

Type: str

name¶

The player’s name

Type: str

town_hall¶: int: The member’s townhall level.

map_position¶: int: The member’s map position in the war.

defense_count¶: int: The number of times this member has been attacked.

war¶: ClanWar: The current war this member is in.

clan¶: WarClan: The member’s clan.

Attributes:

`attacks`	The member’s attacks this war.
`best_opponent_attack`	Returns the best opponent attack on this base.
`defenses`	The member’s defenses this war.
`is_opponent`	Indicates whether the member is from the opponent clan or not.
`previous_best_opponent_attack`	Returns the previous best opponent attack on this base.
`share_link`	`str` - A formatted link to open the player in-game
`star_count`	Get the total number of stars the member has gained this war.

property attacks: List[coc.war_attack.WarAttack]¶

The member’s attacks this war. Could be an empty list.

Type: List[WarAttack]

property best_opponent_attack: coc.war_attack.WarAttack¶

Returns the best opponent attack on this base.

Type: WarAttack

property defenses: List[coc.war_attack.WarAttack]¶

The member’s defenses this war. Could be an empty list.

Type: List[WarAttack]

property is_opponent: bool¶

Indicates whether the member is from the opponent clan or not.

Type: bool

property previous_best_opponent_attack¶

Returns the previous best opponent attack on this base.

This is useful for calculating the new stars and/or destruction for new attacks.

Type: WarAttack

property share_link: str¶: str - A formatted link to open the player in-game

property star_count¶

Get the total number of stars the member has gained this war.

Type: int

Player¶

class coc.Player¶

Represents a Clash of Clans Player.

achievement_cls¶

The constructor used to create the Player.achievements list. This must inherit Achievement.

Type: Achievement

hero_cls¶

The constructor used to create the Player.heroes list. This must inherit from Hero.

Type: Hero

label_cls¶

The constructor used to create the Player.labels list. This must inherit from Label.

Type: Label

spell_cls¶

The constructor used to create the Player.spells list. This must inherit from Spell.

Type: Spell

troop_cls¶

The constructor used to create the Player.troops list. This must inherit from Troop.

Type: Troop

attack_wins¶

The number of attacks the player has won this season.

Type: int

defense_wins¶

The number of defenses the player has won this season.

Type: int

best_trophies¶

The player’s best recorded trophies for the home base.

Type: int

war_stars¶

The player’s total war stars.

Type: int

town_hall¶

The player’s town hall level.

Type: int

town_hall_weapon¶

The player’s town hall weapon level, or None if it doesn’t exist.

Type: Optional[int]

builder_hall¶

The player’s builder hall level, or 0 if it hasn’t been unlocked.

Type: int

best_versus_trophies¶

The player’s best versus trophy count.

Type: int

versus_attack_wins¶

The number of versus attacks the player has won

Type: int

legend_statistics¶

The player’s legend statistics, or None if they have never been in the legend league.

Type: Optional[LegendStatistics]

Attributes:

share_link

str - A formatted link to open the player in-game

Methods:

`get_achievement`(name[, default_value])	Returns an achievement with the given name.
`get_detailed_clan`()	Get detailed clan details for the player’s clan.
`get_hero`(name[, default_value])	Returns a hero with the given name.
`get_spell`(name[, default_value])	Returns a spell with the given name.
`get_troop`(name[, is_home_troop, default_value])	Returns a troop with the given name.
`load_game_data`()	Load game data for this player’s troops and spells.

achievements¶

A list of the player’s achievements.

Type: List[Achievement]

builder_troops¶

A List of the player’s builder-base Troop.

This will return troops in the order found in both barracks and labatory in-game.

This includes: - Builder troops

Type: List[Troop]

get_achievement(name: str, default_value=None) → Optional[coc.miscmodels.Achievement]¶

Returns an achievement with the given name.

Parameters

name (str) – The name of an achievement as found in-game.
default_value – The value to return if the name is not found. Defaults to None.

Returns

The returned achievement or the default_value if not found, which defaults to None..

Return type

Optional[Achievement]

await get_detailed_clan() → Optional[Clan]¶

Get detailed clan details for the player’s clan. If the player’s clan is None,this will return None.

Example

player = await client.get_player('tag')
clan = await player.get_detailed_clan()

get_hero(name: str, default_value=None) → Optional[coc.hero.Hero]¶

Returns a hero with the given name.

Parameters

name (str) – The name of a hero as found in-game.
default_value – The default value to return if a hero with name is not found. Defaults to None.

Returns

The returned hero or the default_value if not found, which defaults to None..

Return type

Optional[Hero]

get_spell(name: str, default_value=None) → Optional[coc.spell.Spell]¶

Returns a spell with the given name.

Parameters

name (str) – The name of a spell as found in-game.
default_value – The default value to return if a spell with name is not found. Defaults to None.

Returns

The returned spell or the default_value if not found, which defaults to None..

Return type

Optional[Spell]

get_troop(name: str, is_home_troop=None, default_value=None) → Optional[coc.troop.Troop]¶

Returns a troop with the given name.

Parameters

name (str) – The name of a troop as found in-game.
is_home_troop (bool) – Whether the troop you’re trying to find is a home troop. This changes how the lookup is done, in order to facilitate searching for a Baby Dragon. By default, this will search from both builder and home troops.
default_value – The value to return if the name is not found. Defaults to None.

Returns

The returned troop or the default_value if not found, which defaults to None..

Return type

Optional[Troop]

hero_pets¶

A List of the player’s hero pets.

This will return hero pets in the order found in the Pet House in-game.

This includes: - Hero pets only.

Type: List[Troop]

heroes¶

A List of the player’s Hero.

This will return heroes in the order found in the store and labatory in-game.

Type: List[Hero]

home_troops¶

A List of the player’s home-base Troop.

This will return troops in the order found in both barracks and labatory in-game.

This includes: - Elixir Troops (Barbarian, Balloon, etc.) - Dark Elixir Troops (Minion, Hog Rider, etc.) - Siege Machines (Log Launcher, etc.) - Boosted Super Troops

Type: List[Troop]

labels¶

A List of Label that the player has.

Type: List[Label]

load_game_data()¶: Load game data for this player’s troops and spells.

Note

This is not the preferred way to load game data. The best way to load game data is to pass load_game_data=True into your get_player call, or to have load_game_data=LoadGameData(default=True) in your client initiation.

This method is provided as a utility for events where loading game data is not desirable unless a change has been observed.

Note

This operation may be slow if you have not loaded the game files during the current session yet.

property share_link: str¶: str - A formatted link to open the player in-game

siege_machines¶

A List of the player’s siege-machine Troop.

This will return siege machines in the order found in both barracks and labatory in-game.

This includes: - Siege machines only.

Type: List[Troop]

spells¶

A List of the player’s Spell ordered as they appear in-game.

This will return spells in the order found in both spell factory and labatory in-game.

Type: List[Spell]

super_troops¶

A List of the player’s super troops.

This will return super troops in the order found in the super troop boosting building, in game.

This includes: - All super troops, boosted or not.

Type: List[Troop]

troops¶

A List of the player’s Troop.

Troops are not ordered in this attribute. Use either Player.home_troops or Player.builder_troops if you want an ordered list.

This includes: - Elixir Troops (Barbarian, Balloon, etc.) - Dark Elixir Troops (Minion, Hog Rider, etc.) - Siege Machines (Log Launcher, etc.) - Boosted Super Troops - Builder Troops (Raged Barbarian, etc.)

This does not include: - Heroes - Hero Pets - Spells - Un-boosted Super Troops

Type: List[Troop]

Wars¶

Clan War¶

class coc.ClanWar¶

Represents a Current Clash of Clans War

clan¶: WarClan: The home clan.

opponent¶: WarClan: The opposition clan.

state¶: str: The clan’s current war state.

preparation_start_time¶: Timestamp: The Timestamp that preparation day started at.

start_time¶: Timestamp: The Timestamp that battle day starts at.

end_time¶: Timestamp: The Timestamp that battle day ends at.

team_size¶: int: The number of players on each side of the war.

war_tag¶: str: The war’s unique tag. This is None unless this is a Clan League War (CWL).

league_group¶: ClanWarLeagueGroup: The war’s league group. This is None unless this is a Clan League War.

Attributes:

`attacks`	Returns all attacks this war, sorted by attack order.
`is_cwl`	Returns a boolean indicating if the war is a Clan War League (CWL) war.
`members`	A list of members that are in the war.
`status`	Returns the war status, based off the home clan.
`type`	Returns either `friendly`, `random` or `cwl`.

Methods:

`get_attack`(attacker_tag, defender_tag)	Return the `WarAttack` with the attacker tag and defender tag provided.
`get_defenses`(defender_tag)	Return a `list` of `WarAttack` for the defender tag provided.
`get_member`(tag)	Return a `ClanWarMember` with the tag provided.
`get_member_by`(**attrs)	Returns the first `WarMember` that meets the attributes passed

property attacks: List[coc.war_attack.WarAttack]¶

Returns all attacks this war, sorted by attack order.

Type: List[WarAttack]

get_attack(attacker_tag: str, defender_tag: str) → Optional[coc.war_attack.WarAttack]¶

Return the WarAttack with the attacker tag and defender tag provided.

If the attack was not found, this will return None.

Returns: The attack with the correct attacker and defender tags
Return type: WarAttack:

get_defenses(defender_tag: str) → List[coc.war_attack.WarAttack]¶

Return a list of WarAttack for the defender tag provided.

If the player has no defenses, this will return an empty list.

Returns: The player’s defenses
Return type: list`[:class:`WarAttack]

get_member(tag: str) → Optional[ClanWarMember]¶

Return a ClanWarMember with the tag provided. Returns None if not found.

Example

war = await client.get_current_war('clan_tag')
member = war.get_member('player_tag')

Returns: Optional[:class:`ClanWarMember`]
Return type: The member who matches the tag provided.

get_member_by(**attrs) → Optional[ClanWarMember]¶

Returns the first WarMember that meets the attributes passed

This will return the first member matching the attributes passed.

An example of this looks like:

member = ClanWar.get_member(tag='tag')

This search implements the coc.utils.get() function

property is_cwl: bool¶

Returns a boolean indicating if the war is a Clan War League (CWL) war.

Type: bool

property members: List[ClanWarMember]¶

A list of members that are in the war.

Type: List[ClanWarMember]

property status: str¶

Returns the war status, based off the home clan.

Strings returned are determined by result and state, as listed below:

`inWar`	`warEnded`
`winning`	`won`
`tied`	`tie`
`losing`	`lost`

Type: str

property type: Optional[str]¶

Returns either friendly, random or cwl.

This will returns None if the clan is not in war, or cwl if the clan is in a league war.

Possibilities for the length of preparation time for a friendly war include: 5 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours, 8 hours, 12 hours, 16 hours, 20 hours or 24 hours.

Type: str

Clan War Log Entry¶

class coc.ClanWarLogEntry¶

Represents a Clash of Clans War Log Entry

Note

Please see the WarClan documention for a full list of missing attributes, as the clan and opponent attributes are only partially filled by the API.

If the ClanWarLogEntry.type is cwl, the WarClan.attack_count, WarClan.stars and WarClan.destruction are all a total which over the period of that CWL season.

In addition, if it is a CWL entry, opponent and result will be None.

result¶: str: The result of the war - win or loss

end_time¶: Timestamp: The Timestamp that the war ended at.

team_size¶: int: The number of players on each side of the war.

clan¶: WarClan: The home clan.

opponent¶: WarClan: The opposition clan.

Attributes:

is_league_entry

Boolean indicating if the entry is a Clan War League (CWL) entry.

property is_league_entry: bool¶

Boolean indicating if the entry is a Clan War League (CWL) entry.

Type: bool

Clan War League Group¶

class coc.ClanWarLeagueGroup¶

Represents a Clan War League (CWL) Group

state¶: str: The current state of the league group (inWar, preparation etc.)

season¶: str: The current season of the league group

number_of_rounds¶: int: The number of rounds this league group contains.

rounds¶: List[List[str]]: A list of lists containing all war tags for each round.

Note

This only returns the current or past rounds. Any future rounds filled with #0 war tags will not appear.

To find the number of rounds in this season, use LeagueGroup.number_of_rounds.

Attributes:

Methods:

`get_wars`([cwl_round, cls])	Returns war information for every war in a league round.
`get_wars_for_clan`(clan_tag[, cls])	Returns every war the clan has participated in this current CWL.

clans¶

Returns all participating clans.

Type: List[LeagueClan]

get_wars(cwl_round: coc.enums.WarRound = WarRound.current_war, cls: Type[coc.wars.ClanWar] = <class 'coc.wars.ClanWar'>) → AsyncIterator[coc.wars.ClanWar]¶

Returns war information for every war in a league round.

This returns a LeagueWarIterator which fetches all wars in parallel.

Example

group = await client.get_league_group('clan_tag')

async for war in group.get_wars():
    print(war.clan_tag)

Parameters

cls (Type[ClanWar]: The constructor used to create the league war.) – This should inherit from ClanWar.
cwl_round (WarRound) – An enum detailing the type of round to get. Could be coc.WarRound.previous_war, coc.WarRound.current_war or coc.WarRound.preparation. This defaults to coc.WarRound.current_war.

Yields

ClanWar – A war in the requested round.

get_wars_for_clan(clan_tag: str, cls: Type[coc.wars.ClanWar] = <class 'coc.wars.ClanWar'>) → AsyncIterator[coc.wars.ClanWar]¶

Returns every war the clan has participated in this current CWL.

This returns a LeagueWarIterator which fetches all wars in parallel.

Example

group = await client.get_league_group('#clan_tag')

async for war in group.get_wars_for_clan('#clantag'):
    print(war.start_time)

Parameters

clan_tag (str) – The clan tag to get wars for. This method will only return wars which belong to this clan.
cls (Type[ClanWar]: The constructor used to create the league war.) – This should inherit from ClanWar.

Yields

ClanWar – A war in the current CWL season with the clan in it..

WarAttack¶

class coc.WarAttack¶

Represents a Clash of Clans War Attack

war¶: ClanWar - The war this attack belongs to

stars¶: int - The stars achieved

destruction¶: float - The destruction achieved as a percentage (of 100)

order¶: int - The attack order in this war

attacker_tag¶: str - The attacker tag

defender_tag¶: str - The defender tag

duration¶: int - Duration of attack in seconds

Attributes:

`attacker`	Returns the attacking player.
`defender`	Returns the defending player.
`is_fresh_attack`	Returns whether the attack is a fresh (first) attack on the defender.

property attacker: ClanWarMember¶

Returns the attacking player.

Type: ClanWarMember

property defender: ClanWarMember¶

Returns the defending player.

Type: ClanWarMember

property is_fresh_attack: bool¶

Returns whether the attack is a fresh (first) attack on the defender.

Type: boolean

Achievement¶

class coc.Achievement¶

Represents a Clash of Clans Achievement.

name¶: str: The name of the achievement.

stars¶: int: The current stars achieved for the achievement.

value¶: int: The number of X things attained for this achievement.

target¶: int: The number of X things required to complete this achievement.

info¶: str: Information regarding the achievement.

completion_info¶: str: Information regarding completion of the achievement.

village¶: str: Either home or builderBase.

Attributes:

`is_builder_base`	Returns a boolean which indicates if the achievement belongs to the builder base
`is_completed`	Returns a boolean which indicates whether the achievement is completed (3 stars achieved)
`is_home_base`	Returns a boolean which indicates if the achievement belongs to the home base

property is_builder_base: bool¶

Returns a boolean which indicates if the achievement belongs to the builder base

Type: bool

property is_completed: bool¶

Returns a boolean which indicates whether the achievement is completed (3 stars achieved)

Type: bool

property is_home_base: bool¶

Returns a boolean which indicates if the achievement belongs to the home base

Type: bool

Troop¶

class coc.Troop¶

Represents a Troop object as returned by the API, optionally filled with game data.

id¶

The troop’s unique ID.

Type: int

name¶

The troop’s name.

Type: str

range¶

The troop’s attack range.

Type: int

lab_level¶

The required labatory level to upgrade the troop to this level.

Type: int

dps¶

The troop’s Damage Per Second (DPS).

Type: int

hitpoints¶

The number of hitpoints the troop has at this level.

Type: int

ground_target¶

Whether the troop is ground-targetting.

Type: bool

speed¶

The troop’s speed.

Type: int

upgrade_cost¶

The amount of resources required to upgrade the troop to the next level.

Type: int

upgrade_resource¶

The type of resource used to upgrade this troop.

Type: Resource

upgrade_time¶

The time taken to upgrade this troop to the next level.

Type: TimeDelta

training_cost¶

The amount of resources required to train this troop.

Type: int

training_resource¶

The type of resource used to train this troop.

Type: Resource

training_time¶

The amount of time required to train this troop.

Type: TimeDelta

is_elixir_troop¶

Whether this troop is a regular troop from the Barracks

Type: bool

is_dark_troop¶

Whether this troop is a dark-troop, trained in the Dark Barracks.

Type: bool

is_siege_machine¶

Whether this troop is a Siege Machine.

Type: bool

is_super_troop¶

Whether this troop is a Super Troop.

Type: bool

cooldown¶

The cooldown on this super troop before being able to be reactivated [Super Troops Only].

Type: TimeDelta

duration¶

The length of time this super troop is active for [Super Troops Only].

Type: TimeDelta

min_original_level¶

The minimum level required of the original troop in order to boost this troop [Super Troops Only].

Type: int

original_troop¶

The “original” counterpart troop to this super troop [Super Troops Only].

Type: Troop

is_loaded¶

Whether the API data has been loaded for this troop.

Type: bool

level¶

The troop’s level

Type: int

max_level¶

The max level for this troop.

Type: int

village¶

Either home or builderBase, indicating which village this troop belongs to.

Type: str

Methods:

get_max_level_for_townhall(townhall)

Get the maximum level for a troop for a given townhall level.

Attributes:

is_max_for_townhall

bool: Returns a boolean that indicates whether the troop is the max level for the player’s townhall level.

classmethod get_max_level_for_townhall(townhall)¶

Get the maximum level for a troop for a given townhall level.

Parameters: townhall – The townhall level to get the maximum troop level for.
Returns: The maximum troop level, or None if the troop hasn’t been unlocked at that level.
Return type: int

property is_max_for_townhall¶: bool: Returns a boolean that indicates whether the troop is the max level for the player’s townhall level.

Hero¶

class coc.Hero¶

Represents a Hero object as returned by the API, optionally filled with game data.

id¶

The hero’s unique ID.

Type: int

name¶

The hero’s name.

Type: str

range¶

The hero’s attack range.

Type: int

dps¶

The hero’s Damage Per Second (DPS).

Type: int

hitpoints¶

The number of hitpoints the troop has at this level.

Type: int

ground_target¶

Whether the hero is ground-targetting. The Grand Warden is classified as ground targetting always.

Type: bool

speed¶

The hero’s speed.

Type: int

upgrade_cost¶

The amount of resources required to upgrade the hero to the next level.

Type: int

upgrade_resource¶

The type of resource used to upgrade this hero.

Type: Resource

upgrade_time¶

The time taken to upgrade this hero to the next level.

Type: TimeDelta

ability_time¶

The number of milliseconds the hero’s ability lasts for.

Type: int

required_th_level¶

The minimum required townhall to unlock this level of the hero.

Type: int

regeneration_time¶

The time required for this hero to regenerate after being “knocked out”.

Type: TimeDelta

is_loaded¶

Whether the API data has been loaded for this hero.

Type: bool

level¶

The hero’s level

Type: int

max_level¶

The max level for this hero.

Type: int

village¶

Either home or builderBase, indicating which village this hero belongs to.

Type: str

Methods:

get_max_level_for_townhall(townhall)

Get the maximum level for a spell for a given townhall level.

Attributes:

is_max_for_townhall

Returns whether the hero is the max level for the player’s townhall level.

classmethod get_max_level_for_townhall(townhall)¶

Get the maximum level for a spell for a given townhall level.

Parameters: townhall – The townhall level to get the maximum troop level for.
Returns: The maximum spell level.
Return type: int

property is_max_for_townhall: bool¶

Returns whether the hero is the max level for the player’s townhall level.

Type: bool

Spell¶

class coc.Spell¶

Represents a Spell object as returned by the API, optionally filled with game data.

id¶

The spell’s unique ID.

Type: int

name¶

The spell’s name.

Type: str

range¶

The spell’s attack range.

Type: int

upgrade_cost¶

The amount of resources required to upgrade the spell to the next level.

Type: int

upgrade_resource¶

The type of resource used to upgrade this spell.

Type: Resource

upgrade_time¶

The time taken to upgrade this spell to the next level.

Type: TimeDelta

training_cost¶

The amount of resources required to train this spell.

Type: int

training_resource¶

The type of resource used to train this spell.

Type: Resource

training_time¶

The amount of time required to train this spell.

Type: TimeDelta

is_elixir_spell¶

Whether this spell is a regular spell from the Barracks

Type: bool

is_dark_spell¶

Whether this spell is a dark-spell, trained in the Dark Barracks.

Type: bool

is_siege_machine¶

Whether this spell is a Siege Machine.

Type: bool

is_loaded¶

Whether the API data has been loaded for this spell.

Type: bool

level¶

The spell’s level

Type: int

max_level¶

The max level for this spell.

Type: int

village¶

Either home or builderBase, indicating which village this spell belongs to.

Type: str

Methods:

get_max_level_for_townhall(townhall)

Get the maximum level for a spell for a given townhall level.

Attributes:

is_max_for_townhall

bool: Returns a boolean that indicates whether the spell is the max level for the player’s townhall level.

classmethod get_max_level_for_townhall(townhall)¶

Get the maximum level for a spell for a given townhall level.

Parameters: townhall – The townhall level to get the maximum troop level for.
Returns: The maximum spell level, or None if the spell hasn’t been unlocked at that level.
Return type: int

property is_max_for_townhall¶: bool: Returns a boolean that indicates whether the spell is the max level for the player’s townhall level.

Location¶

class coc.Location¶

Represents a Clash of Clans Location

id¶: int - The location ID

name¶: str - The location name

is_country¶: bool - Indicates whether the location is a country

country_code¶: str - The shorthand country code, if the location is a country

localised_name¶: str - A localised name of the location. The extent of the use of this is unknown at present.

League Objects¶

class coc.League¶

Represents a Clash of Clans League

id¶: int: The league ID.

name¶: str: The league name.

localised_name¶: str: A localised name of the location. The extent of the use of this is unknown at present.

localised_short_name¶: str: A localised short name of the location. The extent of the use of this is unknown at present.

icon¶: Icon: The league’s icon.

class coc.LegendStatistics¶

Represents the Legend Statistics for a player.

legend_trophies¶: int - The player’s legend trophies

current_season¶: Season: Legend statistics for this season.

previous_season¶: Season: Legend statistics for the previous season.

best_season¶: Season: Legend statistics for the player’s best season.

Badge and Icons¶

class coc.Badge¶

Represents a Clash Of Clans Badge.

small¶: str - URL for a small sized badge (70x70).

medium¶: str - URL for a medium sized badge (200x200).

large¶: str - URL for a large sized badge (512x512).

url¶: str - Medium, the default URL badge size.

Methods:

save(filepath[, size])

This function is a coroutine.

await save(filepath, size=None) → int¶

This function is a coroutine.

Save this badge as a file-like object.

Parameters

filepath (os.PathLike) – The filename to save the badge to.
size (Optional[str]) – Either small, medium or large. The default is medium.

Returns

The number of bytes written

Return type

int

Raises

HTTPException – Saving the badge failed.
NotFound – The URL was not found.

class coc.Icon¶

Represents a Clash Of Clans Icon.

tiny¶: str: URL for a tiny sized icon (32x32).

small¶: str: URL for a small sized icon (72x72).

medium¶: str: URL for a medium sized icon (288x288).

url¶: str: small, the default URL icon size

Methods:

save(filepath[, size])

This function is a coroutine.

await save(filepath: str, size: Optional[str] = None) → int¶

This function is a coroutine.

Save this icon as a file-like object.

Parameters

filepath (os.PathLike) – The filename to save the badge to.
size (Optional[str]) – Either tiny, small or medium. The default is small.

Returns

:class:`int`

Return type

The number of bytes written.

Raises

HTTPException – Saving the badge failed.
NotFound – The URL was not found.

Timestamp¶

class coc.Timestamp¶

Represents a Clash of Clans Timestamp

raw_time¶: str: The raw timestamp string (ISO8601) as given by the API.

Attributes:

`now`	Returns the time in UTC now as a datetime object.
`seconds_until`	Returns the number of seconds until the timestamp.
`time`	Returns the timestamp as a UTC datetime object.

property now: datetime.datetime¶

Returns the time in UTC now as a datetime object.

Type: datetime

property seconds_until: int¶

Returns the number of seconds until the timestamp. This may be negative.

Type: int

property time: datetime.datetime¶

Returns the timestamp as a UTC datetime object.

Type: datetime

TimeDelta¶

class coc.TimeDelta¶

Represents a Timedelta object corresponding to things that take time to do in the API.

Some examples include:

Upgrade times
Training times
Cooldown times

This object works in a very similar fashion to datetime’s timedelta object, but with a few more helpful attributes.

Note

You should not construct this yourself, instead use it from the attribute of an e.g. Troop model.

days¶

The number of days in the timedelta.

Type: int

hours¶

The number of hours in the timedelta. This does not include days. For example, if an upgrade took 36 hours, the .days attribute would be 1, and .hours would be 12.

Type: int

minutes¶

The number of minutes in the timedelta. The same logic applies as with hours.

Type: int

seconds¶

The number of seconds in the timedelta. The same logic applies as with hours.

Type: int

Methods:

total_seconds()

Returns the total number of seconds in the time object.

total_seconds()¶

Returns the total number of seconds in the time object.

This is the addition of all days, hours, minutes, seconds.

Returns: The number of seconds
Return type: int

Label¶

class coc.Label¶

Represents a clan or player label.

id¶: int: The label’s unique ID as given by the API.

name¶: str: The label’s name.

badge¶: Badge: The label’s badge.

War League¶

class coc.WarLeague¶

Represents a clan’s CWL league. .. attribute:: id

type

int: The league’s unique ID

name¶

Type: str: The league’s name, as it appears in-game.

Enumerations¶

The library provides some enumerations for certain types of strings, as well as orders for troops, spells and achievements that are used internally.

Corresponds to a member’s in-game role in the clan.

class coc.Role¶

Returns a string that is rendered as the role appears in-game, ie Co-Leader or Elder. str(member.role) will also return this.

in_game_name¶

class coc.WarRound¶

Corresponds to the previous war day in Clan-War League (ie the war most recently finished)

previous_war¶

Corresponds to the current war day in Clan-War Leagues.

current_war¶

Corresponds to the current preparation day in Clan-War Leagues.

current_preparation¶

class coc.Resource¶

Corresponds to resources found in-game

gold¶

elixir¶

dark_elixir¶

builder_elixir¶

All elixir troops, ordered as they appear in-game.

coc.ELIXIR_TROOP_ORDER¶

All dark elixir troops, ordered as they appear in-game.

coc.DARK_ELIXIR_TROOP_ORDER¶

All siege machines, ordered as they appear in-game.

coc.SIEGE_MACHINE_ORDER¶

All super troops, ordered as they appear in-game.

coc.SUPER_TROOP_ORDER¶

All home troops, ordered as they appear in-game. This is a combination of elixir, dark elixir and siege machine troops. This does not contain super troops.

coc.HOME_TROOP_ORDER¶

All builder troops, ordered as they appear in-game.

coc.BUILDER_TROOPS_ORDER¶

All elixir spells, ordered as they appear in-game.

coc.ELIXIR_SPELL_ORDER¶

All dark elixir spells, ordered as they appear in-game.

coc.DARK_ELIXIR_SPELL_ORDER¶

All spells, ordered as they appear in-game.

coc.SPELL_ORDER¶

All heroes, ordered as they appear in-game.

coc.HERO_ORDER¶

All achievements, ordered as they appear in-game.

coc.ACHIEVEMENT_ORDER¶

All of the above contain a list of strings, corresponding to the name given in-game and in the API.