API Reference ¶

await get_clan_war(clan_tag: str, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about clan’s current clan war

Parameters: clan_tag (str) – The clan tag to search for.
Returns: The clan’s current war.
Return type: ClanWar
Raises: PrivateWarLog –

get_clan_wars(clan_tags: collections.abc.Iterable, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information multiple clan’s current clan wars

Example

tags = [...]
async for clan_war in Client.get_clan_wars(tags):
    print(clan_war.opponent)

Parameters: clan_tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: An iterator of all clan wars. This will skip clans who have a private war-log.
Return type: coc.iterators.WarIterator of ClanWar

get_clans(tags: collections.abc.Iterable, cls=<class 'coc.clans.Clan'>, **kwargs)¶

Get information about multiple clans by clan tag. Refer to Client.get_clan for more information.

Example

tags = [...]
async for clan in Client.get_clans(tags):
    print(clan.name)

Parameters: tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: An iterable of the requested clans.
Return type: ClanIterator of Clan

await get_current_war(clan_tag: str, cwl_round=<WarRound.current_war: 1>, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve a clan’s current war.

Unlike Client.get_clan_war or Client.get_league_war, this method will search for a regular war, and if the clan is in notInWar state, search for a current league war.

This simplifies what would otherwise be 2-3 function calls to find a war.

If you don’t wish to search for CWL wars, use Client.get_clan_war().

This method will consume the PrivateWarLog error, instead returning None.

Note

You can differentiate between a regular clan war and a clan war league (CWL) war by using the helper property, ClanWar.is_cwl.

Parameters

clan_tag (str) – An iterable of clan tag to search for.
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

The clan’s current war.

If no league group is found, or the group is in preparation, this method will return the ClanWar, which appears notInWar, rather than returning None.

If the clan is in CWL, the league group can be accessed via ClanWar.league_group.

Return type

ClanWar

get_current_wars(clan_tags: collections.abc.Iterable, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information multiple clan’s current wars.

See Client.get_current_war() for more information.

Example

tags = [...]
async for war in Client.get_current_wars(tags):
    print(war.type)

Parameters: clan_tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: Current wars for the clans.
Return type: coc.iterators.CurrentWarIterator of ClanWar

await get_league(league_id: int)¶

Get league information

Parameters: league_id (str) – The League ID to search for.
Returns
Return type: League

await get_league_group(clan_tag: str, cls=<class 'coc.wars.ClanWarLeagueGroup'>, **kwargs)¶

Retrieve information about clan’s current clan war league group.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: The clan’s war league group.
Return type: ClanWarLeagueGroup
Raises: PrivateWarLog –

await get_league_named(league_name: str)¶

Get a location by name.

This is somewhat equivilant to

leagues = await client.search_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters: league_name (str) – The league name to search for
Returns: The first location matching the location name.
Return type: League

await get_league_war(war_tag: str, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about a clan war league war.

Parameters: war_tag (str) – The league war tag to search for.
Returns: The league war assosiated with the war tag
Return type: ClanWar

get_league_wars(war_tags: collections.abc.Iterable, clan_tag: str = None, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about multiple league wars

Example

tags = [...]
async for league_war in Client.get_league_wars(tags):
    print(league_war.opponent)

Parameters

war_tags (collections.Iterable) – An iterable of war tags to search for.
clan_tag (Optional[str]) – An optional clan tag. If present, this will only return wars which belong to this clan.

Returns

An iterator of wars.

Return type

coc.iterators.LeagueWarIterator of ClanWar

await get_location(location_id: int)¶

Get information about specific location

Parameters: location_id (int) – The Location ID to search for.
Returns
Return type: Location

await get_location_clans(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get clan rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_clans_versus(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get clan versus rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_named(location_name: str)¶

Get a location by name.

This is somewhat equivilant to:

locations = await client.search_locations(limit=None)
return utils.get(locations, name=location_name)

Parameters: location_name (str) – The location name to search for
Returns: The first location matching the location name.
Return type: Location

await get_location_players(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get player rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_players_versus(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get player versus rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_members(clan_tag: str, cls=<class 'coc.players.ClanMember'>, **kwargs)¶

List clan members.

This is equivilant to (await Client.get_clan('tag')).members.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: A list of :class:`ClanMember`s in the clan.
Return type: List[ClanMember]

await get_player(player_tag: str, cls=<class 'coc.players.Player'>, **kwargs)¶

Get information about a single player by player tag. Player tags can be found either in game or by from clan member lists.

Parameters: player_tag (str) – The player tag to search for.
Returns: The player with the tag.
Return type: Player

await get_player_labels(*, limit: int = None, before: str = None, after: str = None)¶

List player labels.

Parameters

limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

get_players(player_tags: collections.abc.Iterable, cls=<class 'coc.players.Player'>, **kwargs)¶

Get information about a multiple players by player tag. Player tags can be found either in game or by from clan member lists.

Example

tags = [...]
async for player in Client.get_players(tags):
    print(player)

Parameters: player_tags (collections.Iterable) – An iterable of player tags to search for.
Returns
Return type: PlayerIterator of SearchPlayer

await get_season_rankings(league_id: int, season_id: int)¶

Get league season rankings. Note that league season information is available only for Legend League.

Parameters

league_id (str) – The League ID to search for.
season_id (str) – The Season ID to search for.

Returns

Return type

list of RankedPlayer

await get_seasons(league_id: int)¶

Get league seasons. Note that league season information is available only for Legend League.

Parameters

league_id (str) – The League ID to search for.

Returns

In the form

{
    "id": "string"
}

where id is the Season ID

Return type

dict

await get_warlog(clan_tag: str, cls=<class 'coc.wars.ClanWarLogEntry'>, **kwargs)¶

Retrieve a clan’s clan war log.

Note

Please see documentation for ClanWarLogEntry for different attributes which are present when the entry is a regular clan war or a league clan war. The difference can be found with ClanWarLogEntry.is_league_entry.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: A list of the ClanWarLogEntry in the warlog.
Return type: List[ClanWarLogEntry]
Raises: PrivateWarLog –

await login(email: str, password: str)¶

Retrieves all keys and creates an HTTP connection ready for use.

Parameters

email (str) – Your password email from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes
password (str) – Your password login from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes

await reset_keys(number_of_keys: int = None)¶

Manually reset any number of keys.

Under normal circumstances, this method should not need to be called.

Parameters: number_of_keys (int) – The number of keys to reset. Defaults to None - all keys.

await search_clans(*, name: str = None, war_frequency: str = None, location_id: int = None, min_members: int = None, max_members: int = None, min_clan_points: int = None, min_clan_level: int = None, limit: int = None, before: str = None, after: str = None, cls=<class 'coc.clans.Clan'>, **kwargs)¶

Search all clans by name and/or filtering the results using various criteria.

At least one filtering criteria must be defined and if name is used as part of search, it is required to be at least three characters long.

Parameters

name (str, optional) – The clan name.
war_frequency (str, optional) – The war frequency.
location_id (int, optional) – The location id.
min_members (int, optional) – The minimum number of members.
max_members (int, optional) – The maximum number of members.
min_clan_points (int, optional) – The minumum clan points.
min_clan_level (int, optional) – The minimum clan level.
limit (int) – The number of clans to search for.

Returns

A list of all clans found matching criteria provided.

Return type

list of SearchClan

Raises

HTTPException – No options were passed.

await search_leagues(*, limit: int = None, before: str = None, after: str = None)¶

Get list of leagues.

Parameters

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Returns a list of all leagues found. Could be None

Return type

list of League

await search_locations(*, limit: int = None, before: str = None, after: str = None)¶

List all available locations

Parameters

limit (int, optional) – Number of items to fetch. Default is None, which returns all available locations
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

list of Location

Events Client¶

class coc.EventsClient(**options)¶

This is the client connection used to interact with the Clash of Clans API.

Parameters

key_count (int) – The amount of keys to use for this client. Maximum of 10. Defaults to 1.
key_names (str) – Default name for keys created to use for this client. All keys created or to be used with this client must have this name. Defaults to “Created with coc.py Client”.
throttle_limit (int) –
The number of requests per token per second to send to the API. Once hitting this limit, the library will automatically throttle your requests.

Note

Setting this value too high may result in the API rate-limiting your requests. This means you cannot request for ~30-60 seconds.

Warning

Setting this value too high may result in your requests being deemed “API Abuse”, potentially resulting in an IP ban.

Defaults to 10 requests per token, per second.
loop (asyncio.AbstractEventLoop, optional) – The asyncio.AbstractEventLoop to use for HTTP requests. An asyncio.get_event_loop() will be used if None is passed
correct_tags (bool) – Whether the client should correct tags before requesting them from the API. This process involves stripping tags of whitespace and adding a # prefix if not present. Defaults to False.
connector (aiohttp.BaseConnector) – The aiohttp connector to use. By default this is None.
timeout (float) – The number of seconds before timing out with an API query. Defaults to 30.
cache_max_size (int) – The max size of the internal cache layer. Defaults to 10 000. Set this to None to remove any cache layer.

loop¶

The loop that is used for HTTP requests

Type: asyncio.AbstractEventLoop

Methods:

`add_clan_updates`(*tags)	Add clan tags to receive updates for.
`add_events`(*events)	Shortcut to add many events at once.
`add_player_updates`(*tags)	Add player tags to receive events for.
`add_war_updates`(*tags)	Add clan tags to receive war events for.
`close`()	Closes the client and all running tasks.
`dispatch`(event_name, args, *kwargs)	Dispatches an event listener matching the event_name parameter.
`event`(function)	A decorator or regular function that registers an event.
`get_clan`(tag[, cls])	Get information about a single clan by clan tag.
`get_clan_labels`(*[, limit, before, after])	List clan labels.
`get_clan_war`(clan_tag[, cls])	Retrieve information about clan’s current clan war
`get_clan_wars`(clan_tags[, cls])	Retrieve information multiple clan’s current clan wars
`get_clans`(tags[, cls])	Get information about multiple clans by clan tag.
`get_current_war`(clan_tag[, cwl_round, cls])	Retrieve a clan’s current war.
`get_current_wars`(clan_tags[, cls])	Retrieve information multiple clan’s current wars.
`get_league`(league_id)	Get league information
`get_league_group`(clan_tag[, cls])	Retrieve information about clan’s current clan war league group.
`get_league_named`(league_name)	Get a location by name.
`get_league_war`(war_tag[, cls])	Retrieve information about a clan war league war.
`get_league_wars`(war_tags[, clan_tag, cls])	Retrieve information about multiple league wars
`get_location`(location_id)	Get information about specific location
`get_location_clans`([location_id, limit, …])	Get clan rankings for a specific location
`get_location_clans_versus`([location_id, …])	Get clan versus rankings for a specific location
`get_location_named`(location_name)	Get a location by name.
`get_location_players`([location_id, limit, …])	Get player rankings for a specific location
`get_location_players_versus`([location_id, …])	Get player versus rankings for a specific location
`get_members`(clan_tag[, cls])	List clan members.
`get_player`(player_tag[, cls])	Get information about a single player by player tag.
`get_player_labels`(*[, limit, before, after])	List player labels.
`get_players`(player_tags[, cls])	Get information about a multiple players by player tag.
`get_season_rankings`(league_id, season_id)	Get league season rankings.
`get_seasons`(league_id)	Get league seasons.
`get_warlog`(clan_tag[, cls])	Retrieve a clan’s clan war log.
`login`(email, password)	Retrieves all keys and creates an HTTP connection ready for use.
`remove_clan_updates`(*tags)	Remove clan tags that you receive events updates for.
`remove_events`(*events)	Shortcut to remove many events at once.
`remove_player_updates`(*tags)	Remove player tags that you receive events updates for.
`remove_war_updates`(*tags)	Remove player tags that you receive events updates for.
`reset_keys`([number_of_keys])	Manually reset any number of keys.
`run_forever`()	A blocking call which runs the loop and script.
`search_clans`(*[, name, war_frequency, …])	Search all clans by name and/or filtering the results using various criteria.
`search_leagues`(*[, limit, before, after])	Get list of leagues.
`search_locations`(*[, limit, before, after])	List all available locations

add_clan_updates(*tags)¶

Add clan tags to receive updates for.

Parameters: *tags (str) – The clan tags to add. If you wish to pass in an iterable, you must unpack it with *.

Example

client.add_clan_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.add_clan_updates(*tags)

add_events(*events)¶

Shortcut to add many events at once.

This method just iterates over EventsClient.listener().

Parameters: *events (function) – The event listener functions to add.

add_player_updates(*tags)¶

Add player tags to receive events for.

Parameters: \*tags (str) – The player tags to add. If you wish to pass in an iterable, you must unpack it with *.

Example

client.add_player_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.add_player_updates(*tags)

add_war_updates(*tags)¶

Add clan tags to receive war events for.

Parameters: \*tags (str) – The clan tags to add that will receive war events. If you wish to pass in an iterable, you must unpack it with *.

Example

client.add_war_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.add_war_updates(*tags)

close()¶: Closes the client and all running tasks.

dispatch(event_name: str, *args, **kwargs)¶: Dispatches an event listener matching the event_name parameter.

event(function)¶

A decorator or regular function that registers an event.

The function may be be a coroutine.

Parameters: function (function) – The function to be registered (not needed if used with a decorator)

Example

import coc

client = coc.login(...)

@client.event
@coc.ClanEvents.description_change()
async def player_donated_troops(old_player, new_player):
    print('{} has donated troops!'.format(new_player))

import coc

client = coc.login(...)

@client.event
@coc.ClientEvents.maintenance_start()
async def maintenance_has_started():
    print('maintenance has started!')

Note

The order of decorators is important - the @client.event one must lay above

Returns: function
Return type: The function registered

await get_clan(tag: str, cls=<class 'coc.clans.Clan'>, **kwargs)¶

Get information about a single clan by clan tag.

Clan tags can be found using clan search operation.

Parameters: tag (str) – The clan tag to search for.
Returns: The clan with provided tag.
Return type: SearchClan

await get_clan_labels(*, limit: int = None, before: str = None, after: str = None)¶

List clan labels.

Parameters

limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_clan_war(clan_tag: str, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about clan’s current clan war

Parameters: clan_tag (str) – The clan tag to search for.
Returns: The clan’s current war.
Return type: ClanWar
Raises: PrivateWarLog –

get_clan_wars(clan_tags: collections.abc.Iterable, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information multiple clan’s current clan wars

Example

tags = [...]
async for clan_war in Client.get_clan_wars(tags):
    print(clan_war.opponent)

Parameters: clan_tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: An iterator of all clan wars. This will skip clans who have a private war-log.
Return type: coc.iterators.WarIterator of ClanWar

get_clans(tags: collections.abc.Iterable, cls=<class 'coc.clans.Clan'>, **kwargs)¶

Get information about multiple clans by clan tag. Refer to Client.get_clan for more information.

Example

tags = [...]
async for clan in Client.get_clans(tags):
    print(clan.name)

Parameters: tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: An iterable of the requested clans.
Return type: ClanIterator of Clan

await get_current_war(clan_tag: str, cwl_round=<WarRound.current_war: 1>, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve a clan’s current war.

Unlike Client.get_clan_war or Client.get_league_war, this method will search for a regular war, and if the clan is in notInWar state, search for a current league war.

This simplifies what would otherwise be 2-3 function calls to find a war.

If you don’t wish to search for CWL wars, use Client.get_clan_war().

This method will consume the PrivateWarLog error, instead returning None.

Note

You can differentiate between a regular clan war and a clan war league (CWL) war by using the helper property, ClanWar.is_cwl.

Parameters

clan_tag (str) – An iterable of clan tag to search for.
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

The clan’s current war.

If no league group is found, or the group is in preparation, this method will return the ClanWar, which appears notInWar, rather than returning None.

If the clan is in CWL, the league group can be accessed via ClanWar.league_group.

Return type

ClanWar

get_current_wars(clan_tags: collections.abc.Iterable, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information multiple clan’s current wars.

See Client.get_current_war() for more information.

Example

tags = [...]
async for war in Client.get_current_wars(tags):
    print(war.type)

Parameters: clan_tags (collections.Iterable) – An iterable of clan tags to search for.
Returns: Current wars for the clans.
Return type: coc.iterators.CurrentWarIterator of ClanWar

await get_league(league_id: int)¶

Get league information

Parameters: league_id (str) – The League ID to search for.
Returns
Return type: League

await get_league_group(clan_tag: str, cls=<class 'coc.wars.ClanWarLeagueGroup'>, **kwargs)¶

Retrieve information about clan’s current clan war league group.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: The clan’s war league group.
Return type: ClanWarLeagueGroup
Raises: PrivateWarLog –

await get_league_named(league_name: str)¶

Get a location by name.

This is somewhat equivilant to

leagues = await client.search_leagues(limit=None)
return utils.get(leagues, name=league_name)

Parameters: league_name (str) – The league name to search for
Returns: The first location matching the location name.
Return type: League

await get_league_war(war_tag: str, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about a clan war league war.

Parameters: war_tag (str) – The league war tag to search for.
Returns: The league war assosiated with the war tag
Return type: ClanWar

get_league_wars(war_tags: collections.abc.Iterable, clan_tag: str = None, cls=<class 'coc.wars.ClanWar'>, **kwargs)¶

Retrieve information about multiple league wars

Example

tags = [...]
async for league_war in Client.get_league_wars(tags):
    print(league_war.opponent)

Parameters

war_tags (collections.Iterable) – An iterable of war tags to search for.
clan_tag (Optional[str]) – An optional clan tag. If present, this will only return wars which belong to this clan.

Returns

An iterator of wars.

Return type

coc.iterators.LeagueWarIterator of ClanWar

await get_location(location_id: int)¶

Get information about specific location

Parameters: location_id (int) – The Location ID to search for.
Returns
Return type: Location

await get_location_clans(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get clan rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_clans_versus(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get clan versus rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_named(location_name: str)¶

Get a location by name.

This is somewhat equivilant to:

locations = await client.search_locations(limit=None)
return utils.get(locations, name=location_name)

Parameters: location_name (str) – The location name to search for
Returns: The first location matching the location name.
Return type: Location

await get_location_players(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get player rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_location_players_versus(location_id: int = 'global', *, limit: int = None, before: str = None, after: str = None)¶

Get player versus rankings for a specific location

Parameters

location_id (int) – The Location ID to search for. Defaults to all locations (global).
limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

await get_members(clan_tag: str, cls=<class 'coc.players.ClanMember'>, **kwargs)¶

List clan members.

This is equivilant to (await Client.get_clan('tag')).members.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: A list of :class:`ClanMember`s in the clan.
Return type: List[ClanMember]

await get_player(player_tag: str, cls=<class 'coc.players.Player'>, **kwargs)¶

Get information about a single player by player tag. Player tags can be found either in game or by from clan member lists.

Parameters: player_tag (str) – The player tag to search for.
Returns: The player with the tag.
Return type: Player

await get_player_labels(*, limit: int = None, before: str = None, after: str = None)¶

List player labels.

Parameters

limit (int) – The number of results to fetch.
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

get_players(player_tags: collections.abc.Iterable, cls=<class 'coc.players.Player'>, **kwargs)¶

Get information about a multiple players by player tag. Player tags can be found either in game or by from clan member lists.

Example

tags = [...]
async for player in Client.get_players(tags):
    print(player)

Parameters: player_tags (collections.Iterable) – An iterable of player tags to search for.
Returns
Return type: PlayerIterator of SearchPlayer

await get_season_rankings(league_id: int, season_id: int)¶

Get league season rankings. Note that league season information is available only for Legend League.

Parameters

league_id (str) – The League ID to search for.
season_id (str) – The Season ID to search for.

Returns

Return type

list of RankedPlayer

await get_seasons(league_id: int)¶

Get league seasons. Note that league season information is available only for Legend League.

Parameters

league_id (str) – The League ID to search for.

Returns

In the form

{
    "id": "string"
}

where id is the Season ID

Return type

dict

await get_warlog(clan_tag: str, cls=<class 'coc.wars.ClanWarLogEntry'>, **kwargs)¶

Retrieve a clan’s clan war log.

Note

Please see documentation for ClanWarLogEntry for different attributes which are present when the entry is a regular clan war or a league clan war. The difference can be found with ClanWarLogEntry.is_league_entry.

Parameters: clan_tag (str) – The clan tag to search for.
Returns: A list of the ClanWarLogEntry in the warlog.
Return type: List[ClanWarLogEntry]
Raises: PrivateWarLog –

await login(email: str, password: str)¶

Retrieves all keys and creates an HTTP connection ready for use.

Parameters

email (str) – Your password email from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes
password (str) – Your password login from https://developer.clashofclans.com This is used when updating keys automatically if your IP changes

remove_clan_updates(*tags)¶

Remove clan tags that you receive events updates for.

Parameters: *tags (str) – The clan tags to remove. If you wish to pass in an iterable, you must unpack it with *.

Example

client.remove_clan_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.remove_clan_updates(*tags)

remove_events(*events)¶

Shortcut to remove many events at once.

Parameters: *events (function) – The event listener functions to remove.

remove_player_updates(*tags)¶

Remove player tags that you receive events updates for.

Parameters: \*tags (str) – The player tags to remove. If you wish to pass in an iterable, you must unpack it with *.

Example

client.remove_player_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.remove_player_updates(*tags)

remove_war_updates(*tags)¶

Remove player tags that you receive events updates for.

Parameters: \*tags (str) – The clan tags to remove that will receive war events. If you wish to pass in an iterable, you must unpack it with *.

Example

client.remove_war_updates("#tag1", "#tag2", "#tag3")

tags = ["#tag4", "#tag5", "#tag6"]
client.remove_war_updates(*tags)

await reset_keys(number_of_keys: int = None)¶

Manually reset any number of keys.

Under normal circumstances, this method should not need to be called.

Parameters: number_of_keys (int) – The number of keys to reset. Defaults to None - all keys.

run_forever()¶

A blocking call which runs the loop and script.

This is useful if you have no other clients to deal with and just wish to run the script and receive updates indefinately.

Roughly equivilant to:

try:
    client.loop.run_forever()
except KeyboardInterrupt:
    client.close()
finally:
    client.loop.close()

await search_clans(*, name: str = None, war_frequency: str = None, location_id: int = None, min_members: int = None, max_members: int = None, min_clan_points: int = None, min_clan_level: int = None, limit: int = None, before: str = None, after: str = None, cls=<class 'coc.clans.Clan'>, **kwargs)¶

Search all clans by name and/or filtering the results using various criteria.

At least one filtering criteria must be defined and if name is used as part of search, it is required to be at least three characters long.

Parameters

name (str, optional) – The clan name.
war_frequency (str, optional) – The war frequency.
location_id (int, optional) – The location id.
min_members (int, optional) – The minimum number of members.
max_members (int, optional) – The maximum number of members.
min_clan_points (int, optional) – The minumum clan points.
min_clan_level (int, optional) – The minimum clan level.
limit (int) – The number of clans to search for.

Returns

A list of all clans found matching criteria provided.

Return type

list of SearchClan

Raises

HTTPException – No options were passed.

await search_leagues(*, limit: int = None, before: str = None, after: str = None)¶

Get list of leagues.

Parameters

limit (int) – Number of items to fetch. Defaults to None (all leagues).
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Returns a list of all leagues found. Could be None

Return type

list of League

await search_locations(*, limit: int = None, before: str = None, after: str = None)¶

List all available locations

Parameters

limit (int, optional) – Number of items to fetch. Default is None, which returns all available locations
before (str, optional) – For use with paging. Not implemented yet.
after (str, optional) – For use with paging. Not implemented yet.

Returns

Return type

list of Location

Event Reference¶

Events are called when using the EventsClient client, clans/players/wars have been registered, and have been started.

Events need to be registered in order to be called by the client. You can register events by using either EventsClient.event(), or EventsClient.add_events().

All events the client will dispatch are listed below.

Event Error¶

coc.on_event_error(event_name, \*args, \*\*kwargs)¶

This event is called when another event raises an exception and fails. By default, it will print the traceback to stderr and the exception will be ignored.

The information of the exception raised and the exception itself can be retrieved with a standard call to sys.exc_info().

Parameters

event_name – The event which caused the error
args – The positional args for the event which raised the error
kwargs – The keyword-args for the event which raised the error

Clan Events¶

These events are all related to clan changes and changes to players within the clan. Clans can be added by registering clan tags and relevant events.

Clan Level Change¶

coc.on_clan_level_change(old_level, new_level, clan)¶

This event is called when the clan level changes.

Parameters

old_level (int) – The old clan level
new_level (int) – The new clan level
clan (SearchClan) – The clan who’s level changed

Clan Description Change¶

coc.on_clan_description_change(old_description, new_description, clan)¶

This event is called when the clan description changes.

Parameters

old_description (str) – The old clan’s description
new_description (str) – The new clan description
clan (SearchClan) – The clan who’s description changed

Clan Public WarLog Change¶

coc.on_clan_public_war_log_change(old_toggle, new_toggle, clan)¶

This event is called when the clan’s toggle changes.

Parameters

old_toggle (bool) – The old clan toggle
new_toggle (bool) – The new clan toggle
clan (SearchClan) – The clan who’s toggle changed

Clan Type Change¶

coc.on_clan_type_change(old_type, new_type, clan)¶

This event is called when the clan’s type changes.

Parameters

old_type (str) – The old clan type
new_type (str) – The new clan type
clan (SearchClan) – The clan who’s type changed

Clan Badge Change¶

coc.on_clan_badge_change(old_badge, new_badge, clan)¶

This event is called when the clan’s badge changes.

Parameters

old_badge (Badge) – The old clan badge
new_badge (Badge) – The new clan badge
clan (SearchClan) – The clan who’s badge changed

Clan Required Trophies Change¶

coc.on_clan_required_trophies_change(old_requirement, new_requirement, clan)¶

This event is called when the clan’s trophy requirement changes.

Parameters

old_requirement (int) – The old clan requirement
new_requirement (int) – The new clan requirement
clan (SearchClan) – The clan who’s requirement changed

Clan War Frequency Change¶

coc.on_clan_war_frequency_change(old_frequency, new_frequency, clan)¶

This event is called when the clan’s war frequency changes.

Parameters

old_frequency (str) – The old clan war frequency
new_frequency (str) – The new clan war frequency
clan (SearchClan) – The clan who’s war frequency changed

Clan War Win Streak Change¶

coc.on_clan_war_win_streak_change(old_streak, new_streak, clan)¶

This event is called when the clan’s war win streak changes.

Parameters

old_streak (int) – The old clan streak
new_streak (int) – The new clan streak
clan (SearchClan) – The clan who’s streak changed

Clan War Wins Change¶

coc.on_clan_war_win_change(old_wins, new_wins, clan)¶

This event is called when the clan’s war wins change.

Parameters

old_wins (int) – The old clan wins
new_wins (int) – The new clan wins
clan (SearchClan) – The clan who’s wins changed

Clan War Ties Change¶

coc.on_clan_war_tie_change(old_ties, new_ties, clan)¶

This event is called when the clan’s war ties change.

Parameters

old_ties (int) – The old clan ties
new_ties (int) – The new clan ties
clan (SearchClan) – The clan who’s ties changed

Clan War Losses Change¶

coc.on_clan_war_loss_change(old_losses, new_losses, clan)¶

This event is called when the clan’s war losses change.

Parameters

old_losses (int) – The old clan losses
new_losses (int) – The new clan losses
clan (SearchClan) – The clan who’s losses changed

Clan Member Join¶

coc.on_clan_member_join(member, clan)¶

This event is called when a member joins a clan.

Parameters

member (BasicPlayer) – The member who joined.
clan (SearchClan) – The clan the member joined.

Clan Member Leave¶

coc.on_clan_member_leave(member, clan)¶

This event is called when a member leaves a clan.

Parameters

member (BasicPlayer) – The member who left.
clan (SearchClan) – The clan the member left.

Clan Member Name Change¶

coc.on_clan_member_name_change(old_name, new_name, player)¶

This event is called when a clan member’s name changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_name (str) – The player’s old name
new_name (str) – The player’s new name
player (BasicPlayer) – The player object which changed

Clan Member Donations¶

coc.on_clan_member_donation(old_donations, new_donations, player)¶

This event is called when a clan member’s donations changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_donations (int) – The player’s old donations
new_donations (int) – The player’s new donations
player (BasicPlayer) – The player object which changed

Clan Member Received¶

coc.on_clan_member_received(old_received, new_received, player)¶

This event is called when a clan member’s donations received changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_received (int) – The player’s old received
new_received (int) – The player’s new received
player (BasicPlayer) – The player object which changed

Clan Member Trophy Count Change¶

coc.on_clan_member_trophy_change(old_trophies, new_trophies, player)¶

This event is called when a clan member’s trophy count has changed. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_received (int) – The player’s old trophy count
new_received (int) – The player’s new trophy count
player (BasicPlayer) – The player object which changed

Clan Member Versus Trophy Count Change¶

coc.on_clan_member_versus_trophy_change(old_trophies, new_trophies, player)¶

This event is called when a clan member’s versus trophy count has changed. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_received (int) – The player’s old versus trophy count
new_received (int) – The player’s new versus trophy count
player (BasicPlayer) – The player object which changed

Clan Member Role Change¶

coc.on_clan_member_role_change(old_role, new_role, player)¶

This event is called when a clan member’s role changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_role (str) – The player’s old role
new_role (str) – The player’s new role
player (BasicPlayer) – The player object which changed

Clan Member Rank Change¶

coc.on_clan_member_rank_change(old_rank, new_rank, player)¶

This event is called when a clan member’s rank changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_rank (int) – The player’s old rank
new_rank (int) – The player’s new rank
player (BasicPlayer) – The player object which changed

Clan Member Level Change¶

coc.on_clan_member_level_change(old_level, new_level, player)¶

This event is called when a clan member’s level changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_level (str) – The player’s old level
new_level (str) – The player’s new level
player (BasicPlayer) – The player object which changed

Clan Member League Change¶

coc.on_clan_member_league_change(old_league, new_league, player, clan)¶

This event is called when a clan member’s league changes. The player’s clan can be accessed through BasicPlayer.clan and is of type SearchClan

Parameters

old_level (League) – The player’s old league
new_level (League) – The player’s new league
player (BasicPlayer) – The player object which changed
clan (SearchClan) – The player’s clan

War Events¶

These events are all related to war changes, such as war attacks and state changes. Clans can be added by registering clan tags and relevant events.

War Update¶

coc.on_war_update(old_war, new_war)¶

This event is called when a war update occurs, regardless of it’s nature. This could be an attack, state change or other.

Parameters

old_war (War) – The war object before the change
new_war (War) – The war object after the change

New War Attack¶

coc.on_war_attack(attack, war)¶

This event is called when a new war attack has been made. This could be an offensive or defensive attack. This will be called once per new attack, even if multiple new attacks are found.

Parameters

attack (WarAttack) – The new attack.
war (War) – The war this attack belongs to.

War State Change¶

coc.on_war_state_change(current_state, war)¶

This event is called when a change of war state occurs. This will not necessarily be called when the client checks for a change, as a task will be created at the last update to wait for new state changes.

Parameters

current_state (str) – The current war state it has changed to.
war (War) – The war that has changed state

Player Events¶

These events are all related to player changes and changes to clans within the player. Clans can be added by registering clan tags and relevant events.

Player Update¶

coc.on_player_update(old_player, new_player)¶

This event is called when a player changes. This event will be called regardless of the update that follows. This could be a name or level change, or a troop/spell upgrade.

Parameters

old_war (SearchPlayer) – The player object before the change
new_war (SearchPlayer) – The player object after the change

Player Name Change¶

coc.on_player_name_change(old_name, new_name, player)¶

This event is called when a player’s name has changed.

Parameters

old_name (str) – The player’s old name
new_name (str) – The player’s new name
player (SearchPlayer) – The new player object

Player Town Hall Change¶

coc.on_player_townhall_upgrade(old_townhall, new_townhall, player)¶

This event is called when a player’s townhall has been upgraded.

Parameters

old_townhall (int) – The player’s old townhall level
new_townhall (int) – The player’s new townhall level
player (SearchPlayer) – The new player object

Player Builder Hall Change¶

coc.on_player_builderhall_upgrade(old_builderhall, new_builderhall, player)¶

This event is called when a player’s builder hall has been upgraded.

Parameters

old_builderhall (int) – The player’s old builder hall level
new_builderhall (int) – The player’s new builder hall level
player (SearchPlayer) – The new player object

Player Best Trophies Change¶

coc.on_player_best_trophies_change(old_best, new_best, player)¶

This event is called when a player’s best trophy count changes.

Parameters

old_best (int) – The player’s old best trophy count
new_best (int) – The player’s new best trophy count
player (SearchPlayer) – The player in question

Player Best Versus Trophies Change¶

coc.on_player_best_versus_trophies_change(old_best, new_best, player)¶

This event is called when a player’s best versus trophy count changes.

Parameters

old_best (int) – The player’s old best versus trophy count
new_best (int) – The player’s new best versus trophy count
player (SearchPlayer) – The player in question

Player War Stars Change¶

coc.on_player_war_stars_change(old_stars, new_stars, player)¶

This event is called when a player’s war stars changes.

Parameters

old_stars (int) – The player’s old war stars
new_stars (int) – The player’s new war stars
player (SearchPlayer) – The player in question

Player Attack Wins Change¶

coc.on_player_attack_wins_change(old_attacks, new_attacks, player)¶

This event is called when a player’s attacks count changes.

Parameters

old_attacks (int) – The player’s old attacks count
new_attacks (int) – The player’s new attacks count
player (SearchPlayer) – The player in question

Player Defense Wins Change¶

coc.on_player_defense_wins_change(old_defenses, new_defenses, player)¶

This event is called when a player’s defenses trophy count changes.

Parameters

old_defenses (int) – The player’s old defenses count
new_defenses (int) – The player’s new defenses count
player (SearchPlayer) – The player in question

Player Versus Attack Change¶

coc.on_player_versus_attack_change(old_attacks, new_attacks, player)¶

This event is called when a player’s versus attack count changes.

Parameters

old_attacks (int) – The player’s old versus attack count
new_attacks (int) – The player’s new versus attack count
player (SearchPlayer) – The player in question

Player Trophies Change¶

coc.on_player_trophies_change(old_trophies, new_trophies, player)¶

This event is called when a player’s trophy count changes.

Parameters

old_trophies (int) – The player’s old trophy count
new_trophies (int) – The player’s new trophy count
player (SearchPlayer) – The player in question

Player League Change¶

coc.on_player_league_change(old_league, new_league, player)¶

This event is called when a player’s league changes.

Parameters

old_league (League) – The player’s old league
new_league (League) – The player’s new league
player (SearchPlayer) – The player in question

Player Role Change¶

coc.on_player_role_change(old_role, new_role, player)¶

This event is called when a player’s clan role.

Parameters

old_role (str) – The player’s old role
new_role (str) – The player’s new role
player (SearchPlayer) – The player in question

Player Donations Change¶

coc.on_player_donations_change(old_donations, new_donations, player)¶

This event is called when a player’s donation count changes.

Parameters

old_donations (int) – The player’s old donation count
new_donations (int) – The player’s new donation count
player (SearchPlayer) – The player in question

Player Received Change¶

coc.on_player_received_change(old_received, new_received, player)¶

This event is called when a player’s donations received count changes.

Parameters

old_received (int) – The player’s old received count
new_received (int) – The player’s new received count
player (SearchPlayer) – The player in question

Player’s Clan Rank Change¶

coc.on_player_clan_rank_change(old_rank, new_rank, player)¶

This event is called when a player’s clan rank changes.

Parameters

old_rank (int) – The player’s old rank
new_rank (int) – The player’s new rank
player (SearchPlayer) – The player in question

Player’s Previous Clan Rank Change¶

coc.on_player_previous_clan_rank_change(old_rank, new_rank, player)¶

This event is called when a player’s previous clan rank changes. This would typically be at the end of the season.

Parameters

old_rank (int) – The player’s old previous rank
new_rank (int) – The player’s new previous rank
player (SearchPlayer) – The player in question

Player Achievement Change¶

coc.on_player_achievement_change(old_achievement, new_achievement, player)¶

This event is called when a player’s achievement has changed.

Parameters

old_achievement (Achievement) – The player’s old achievement.
new_achievement (Achievement) – The player’s new achievement.
player (SearchPlayer) – The new player object

Player Troop Upgrade¶

coc.on_player_troop_upgrade(old_troop, new_troop, player)¶

This event is called when a player’s troop has been upgraded.

Parameters

old_troop (Troop) – The player’s old troop.
new_troop (Troop) – The player’s new troop.
player (SearchPlayer) – The new player object

Player Spell Upgrade¶

coc.on_player_spell_upgrade(old_spell, new_spell, player)¶

This event is called when a player’s spell has been upgraded.

Parameters

old_spell (Spell) – The player’s old spell.
new_spell (Spell) – The player’s new spell.
player (SearchPlayer) – The new player object

Player Hero Upgrade¶

coc.on_player_hero_upgrade(old_hero, new_hero, player)¶

This event is called when a player’s hero has been upgraded.

Parameters

old_hero (Hero) – The player’s old hero.
new_hero (Hero) – The player’s new hero.
player (SearchPlayer) – The new player object

Player Clan Join¶

coc.on_player_clan_join(player, clan)¶

This event is called when a player joins a clan.

Parameters

member (SearchPlayer) – The player who joined.
clan (Clan) – The clan the player joined.

Player Clan Leave¶

coc.on_player_clan_leave(player, clan)¶

This event is called when a player leaves a clan.

Parameters

member (SearchPlayer) – The member who left.
clan (Clan) – The clan the member left.

Player’s Clan Level Change¶

coc.on_player_clan_level_change(old_level, new_level, clan, player)¶

This event is called when a player’s clan’s level changes.

Parameters

old_level (int) – The old clan level
new_level (int) – The new clan level
clan (Clan) – The clan who’s level changed
player (SearchPlayer) – The player who’s clan’s level changed.

Player’s Clan Badge Change¶

coc.on_player_clan_badge_change(old_badge, new_badge, clan, player)¶

This event is called when the clan’s badge changes.

Parameters

old_badge (Badge) – The old clan badge
new_badge (Badge) – The new clan badge
clan (Clan) – The clan who’s badge changed
player (SearchPlayer) – The player who’s clan’s badge changed.

Data 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 Supercell 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.

Note: If a SearchPlayer inherits BasicPlayer, it will inherit all attributes of both Player and BasicPlayer, however it will not necessarily inherit WarMember

Clans¶

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 player information for every player in the clan.

Attributes:

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

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 player information for every player in the clan.

Attributes:

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

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 player information for every player in the clan.

Attributes:

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

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

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

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¶

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:

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

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

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:

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

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:

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

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: