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()

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() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

share_link¶: 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()

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() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

share_link¶: 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()

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() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

share_link¶: 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:

`attacks`	Returns all clan member’s attacks this war.
`defenses`	Returns all clan member’s defenses this war.
`is_opponent`	Indicates whether the clan is the opponent.
`members`	A list of members that are in the war.
`share_link`	`str` - A formatted link to open the clan in-game

Methods:

`get_detailed_members`()	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() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

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: Optional[:class:`ClanWarMember`]
Return type: The clan member who matches the tag.

is_opponent¶

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]

share_link¶: 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()

Get detailed player information for every player in the clan.

Attributes:

`members`	A list of players participating in this clan war league season.
`share_link`	`str` - A formatted link to open the clan in-game

get_detailed_members() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

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]

share_link¶: 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

level¶

The clan’s level.

Type: int

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`()	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:

`labels`	A `List` of `Label` that the clan has.
`members`	A list of members that belong to the clan.
`share_link`	`str` - A formatted link to open the clan in-game

get_detailed_members() → coc.iterators.PlayerIterator¶

Get detailed player information for every player in the clan. This will return an AsyncIterator of Player.

Example

clan = await client.get_clan('tag')

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

Returns
Return type: AsyncIterator of Player - the clan members.

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]

share_link¶: 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

share_link¶: 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

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 in the clan at the end of the last season.

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()

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

Ranked Player¶

class coc.RankedPlayer¶

Represents a leaderboard-ranked player.

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

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 in the clan at the end of the last season.

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

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 leader board.

Type: int

previous_rank¶

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

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()

share_link¶: 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

share_link¶: 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¶: War: 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.

attacks¶

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

Type: List[WarAttack]

best_opponent_attack¶

Returns the best opponent attack on this base.

Type: WarAttack

defenses¶

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

Type: List[WarAttack]

is_opponent¶

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

Type: bool

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

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.

Type: int

Player¶

class coc.Player¶

Represents a Clash of Clans Player.

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

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 in the clan at the end of the last season.

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

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:

`achievements`	A list of the player’s achievements.
`builder_troops`	A `List` of the player’s builder-base `Troop`.
`heroes`	A `List` of the player’s `Hero`.
`home_troops`	A `List` of the player’s home-base `Troop`.
`labels`	A `List` of `Label` that the player has.
`share_link`	`str` - A formatted link to open the player in-game
`siege_machines`	A `List` of the player’s siege-machine `Troop`.
`spells`	A `List` of the player’s `Spell` ordered as they appear in-game.
`troops`	A `List` of the player’s `Troop`.

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.

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.

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.miscmodels.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.miscmodels.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.miscmodels.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]

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.

Type: List[Troop]

labels¶

A List of Label that the player has.

Type: List[Label]

share_link¶: 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.

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]

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.

Type: List[Troop]

Wars¶

Clan War¶

class coc.ClanWar¶

Represents a Current Clash of Clans War

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

attacks¶

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)¶

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

is_cwl¶

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

Type: bool

members¶

A list of members that are in the war.

Type: List[ClanWarMember]

status¶

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

type¶

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: 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.

is_league_entry¶

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:

clans

Returns all participating clans.

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[class
Type: LeagueClan]

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

Returns war information for every war in a league round.

This will return an AsyncIterator of ClanWar.

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.

Returns

AsyncIterator of :class:`ClanWar`

Return type

All wars in the given round.

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

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

This will return an AsyncIterator of ClanWar.

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.

Returns

AsyncIterator of :class:`ClanWar`

Return type

All wars in the given round.

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

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.

attacker¶

Returns the attacking player.

Type: ClanWarMember

defender¶

Returns the defending player.

Type: ClanWarMember

is_fresh_attack¶

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

is_builder_base¶

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

Type: bool

is_completed¶

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

Type: bool

is_home_base¶

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

Type: bool

Troop¶

class coc.Troop¶

Represents a Clash of Clans Troop.

name¶: str: The name of the troop.

level¶: int: The level of the troop.

max_level¶: int: The overall max level of the troop; excluding townhall limitations.

village¶: str: Either home or builderBase.

Attributes:

`is_builder_base`	Returns a boolean that indicates whether the troop belongs to the builder base.
`is_home_base`	Returns a boolean that indicates whether the troop belongs to the home base.
`is_max`	Returns a boolean that indicates whether the troop is the max level

is_builder_base¶

Returns a boolean that indicates whether the troop belongs to the builder base.

Type: bool

is_home_base¶

Returns a boolean that indicates whether the troop belongs to the home base.

Type: bool

is_max¶

Returns a boolean that indicates whether the troop is the max level

Type: bool

Hero¶

class coc.Hero¶

Represents a Clash of Clans Hero.

name¶: str: The name of the hero.

level¶: int: The level of the hero.

max_level¶: int: The overall max level of the hero, excluding townhall limitations.

village¶: str: Either home or builderBase.

Attributes:

`is_builder_base`	Returns a boolean that indicates whether the hero belongs to the builder base.
`is_home_base`	Returns a boolean that indicates whether the hero belongs to the home base.
`is_max`	Returns a boolean that indicates whether the hero is the max level.

is_builder_base¶

Returns a boolean that indicates whether the hero belongs to the builder base.

Type: bool

is_home_base¶

Returns a boolean that indicates whether the hero belongs to the home base.

Type: bool

is_max¶

Returns a boolean that indicates whether the hero is the max level.

Type: bool

Spell¶

class coc.Spell¶

Represents a Clash of Clans Spell.

name¶: str: The name of the spell.

level¶: int: The level of the spell.

max_level¶: int: The overall max level of the spell, excluding townhall limitations.

village¶: str: Either home or builderBase.

Attributes:

`is_builder_base`	Returns a boolean that indicates whether the spell belongs to the builder base.
`is_home_base`	Returns a boolean that indicates whether the spell belongs to the home base.
`is_max`	Returns a boolean that indicates whether the spell is the max level.

is_builder_base¶

Returns a boolean that indicates whether the spell belongs to the builder base.

Type: bool

is_home_base¶

Returns a boolean that indicates whether the spell belongs to the home base.

Type: bool

is_max¶

Returns a boolean that indicates whether the spell is the max level.

Type: bool

Location¶

class coc.Location¶

Represents a Clash of Clans Location

id¶: str - 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¶: str: 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, size=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.

now¶

Returns the time in UTC now as a datetime object.

Type: datetime

seconds_until¶

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

Type: int

time¶

Returns the timestamp as a UTC datetime object.

Type: datetime

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¶

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.