Events Client

The following details all valid operations for the EventsClient. This extends the Client class, and all methods from Client are valid with the EventsClient, too.

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 True.
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.
load_game_data (LoadGameData) – The option for how coc.py will load game data. See Initialising the Client for more info.
realtime (bool) – Some developers are given special access to an uncached API access by Super Cell. If you are one of those developers, your account will have special flags that will only be interpreted by coc.py if you set this bool to True.
raw_attribute (bool) – The option to enable the _raw_data attribute for most objects in the library. This attribute will contain the original json data as returned by the API. This can be useful if you want to store a response in a database for later use or are interested in new things that coc.py does not support otherwise yet. But because this increases the memory footprint and is not needed for most use cases, this defaults to False.
base_url (str) – The base URL to use for API requests. Defaults to “https://api.clashofclans.com/v1”

loop

The loop that is used for HTTP requests

Type:: asyncio.AbstractEventLoop

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)

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

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)

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