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

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

builder_base_league

The member’s current builder base league.

Type:

BaseLeague

trophies

The member’s trophy count.

Type:

int

builder_base_trophies

The member’s builder base trophy count.

Type:

int

town_hall

The player’s town hall level. In case the player hasn’t logged in since 2019, this will be 0.

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

builder_base_rank

The member’s rank in the clan based on builder base trophies.

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

builder_base_league_cls

The class to use to create the ClanMember.builder_base_league attribute. Ensure any overriding of this inherits from coc.BaseLeague.

Type:

coc.League

async get_detailed_clan() → Optional[Clan]

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

A List of :class:`PlayerHouseElement`s that the player has.

Type:

List[PlayerHouseElement]

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 builder base leader-boards, this will be None.

Type:

int

defense_wins

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

Type:

int

builder_base_trophies

The player’s builder base 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

async get_detailed_clan() → Optional[Clan]

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

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

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

Raid Member

class coc.RaidMember

Represents a Raid Member that the API returns.

tag

The player’s tag

Type:

str

name

The player’s name

Type:

str

attack_count

The number of attacks from this player

Type:

int

attack_limit

The limit of attacks from this player

Type:

int

bonus_attack_limit

The limit of bonus attacks from this player

Type:

int

capital_resources_looted

The amount of resources looted by this player

Type:

int

raid_log_entry

The raid log entry this member is in

Type:

RaidLogEntry

attacks

The member’s attacks in this raid log entry. Can be empty due to missing parts in the API response.

Type:

List[RaidAttack]

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.

attack_cls

The type which the attacks in ClanWarMember.attacks will be of. Ensure any overriding of this inherits from coc.WarAttack.

Type:

coc.WarAttack

property attacks: List[WarAttack]

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

Type:

List[WarAttack]

property best_opponent_attack: WarAttack

Returns the best opponent attack on this base.

Type:

WarAttack

property defenses: List[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

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 from 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

equipment_cls

The constructor used to create the Player.equipment list. This must inherit from Equipment.

Type:

Equipment

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_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_builder_base_trophies

The player’s best builder base trophy count.

Type:

int

clan_capital_contributions

The player’s total contribution to clan capitals

Type:

int

legend_statistics

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

Type:

Optional[LegendStatistics]

war_opted_in

Whether the player has selected that they are opted “in” (True) for wars, or opted “out” (False). This will be None if the player is not in a clan.

Type:

Optional[bool]

equipment

The player’s unlocked hero equipment

Type:

List[Equipment]

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]

equipment

A List of the player’s hero equipment.

This will return hero equipment in the order it is in the player’s profile

This includes: - Hero equipment only.

Type:

List[Equipment]

get_achievement(name: str, default_value=None) → Optional[Achievement]

Gets 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]

async get_detailed_clan() → Optional[Clan]

Get 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_equipment(name: str, default_value=None) → Optional[Equipment]

Gets the hero equipment with the given name.

Parameters:

  • name (str) – The name of a hero equipment as found in-game.

  • default_value – The default value to return if a hero equipment with name is not found. Defaults to None.

Returns:

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

Return type:

Optional[Equipment]

get_hero(name: str, default_value=None) → Optional[Hero]

Gets the 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_pet(name: str, default_value=None) → Optional[Pet]

Gets the pet with the given name.

Parameters:

  • name (str) – The name of a pet as found in-game.

  • default_value – The default value to return if a pet with name is not found. Defaults to None.

Returns:

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

Return type:

Optional[Pet]

get_spell(name: str, default_value=None) → Optional[Spell]

Gets the 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[Troop]

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

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 :class:`Label`s 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.

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[Pet]

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]