Coc.py

------

- Maintenance event poller logic has been reworked to enable the use of :class:`EventsClient` without any player/clan/war
updates.

- 5min preparation time has been included in the list of valid prep times for friendly wars.

- The warlog example has been updated to properly close the client, and a typo fixed in the README example.

- The ``correct_tags`` parameter has been changed to default to ``True``. There is no side-effects of having this enabled.

:meth:`EventsClient.remove_player_updates`, :meth:`EventsClient.remove_clan_updates` and :meth:`EventsClient.remove_war_updates`.

The usage is intuitive, and identical to adding the tags:

.. code-block:: python3

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

tags = ["tag1", "tag2", "tag3"]
client.remove_player_updates(*tags)


End of Season Helpers
---------------------
A common use for users of the API is to do something when the season change occurs, at 5pm UTC on the last monday of each month.
This has been integrated into coc.py, and available with the new utility commands, :meth:`utils.get_season_start` and :meth:`utils.get_season_end`.

In addition, there has been a new event added, ``coc.ClientEvents.season_started()`` which will get fired upon season restart.

For Example:

.. code-block:: python3

from coc import utils

season_start = utils.get_season_start()
print("The current season started at " + str(season_start))

coc.ClientEvents.new_season_start()
async def season_started():
print("A new season has started, and it will finish at " + utils.get_season_end())


Custom Classes
--------------
For more information on custom class support, please see :ref:`custom_classes`.

Discord Links Extension
-----------------------
For more information on the new discord links extension, please see :ref:`links_extension`.

-------
Breaking Changes
~~~~~~~~~~~~~~~~~~
- ``SearchPlayer.versus_attacks_wins`` has been renamed to ``SearchPlayer.versus_attack_wins``.
- The ``on_player_versus_attacks_change`` event has been renamed to ``on_player_versus_attack_change`` to match the above change.
- There was a typo with the spelling of the ``coc.Maintenance`` exception. It has been renamed from ``coc.Maitenance`` to ``coc.Maintenance``.

New Things
~~~~~~~~~~~
- Add a default `Unranked` league to ``BasicPlayer.league``.
- Added TH13 content.

BugFixes
~~~~~~~~~
- Fixed ``client.get_members`` raising ``AttributeError`` if no clan is found in the cache.
- ``client.get_warlog`` was only returning league wars. This has been fixed.

--------
New Features.
~~~~~~~~~~~~~~
- :ref:`on_clan_member_trophy_change`, :ref:`on_clan_member_versus_trophy_change` and
:ref:`on_clan_member_league_change` were added as new events.
- Add ability to pass async and other iterables into methods that return iterators.
- Add the `HogGlider` to list of builder base troops.
- Added support for `SearchClan.labels` and `SearchPlayer.labels`. They will return a :class:`~coc.Label` object.
- Add a special parameter to `Client` to automatically "fix" or call `utils.correct_tag` on any tags passed in to calls.
- `Client.get_clan_labels()` and `Client.get_player_labels()` are now valid client calls.

BugFixes
~~~~~~~~~~~~
- Getting clans and players for a location will now default to getting for the global leaderboard.
- `LeagueWar` will no longer throw an `AttributeError` when no clan is found.
- Never update the cache automatically when the `EventsClient` is used.
- Fixed :ref:`on_war_state_change` not firing properly when a clan entered `preparation` or `warEnded`.

-------
Bug Fixes
~~~~~~~~~~~
- All iterators have been fixed in python 3.7
- :ref:`on_clan_member_join` will now fire events correctly
- Properly parse HTML errors thrown by CloudFlare
- Accessing the ``League.badge`` attribute has been fixed
- Clan events now sleep for the correct interval
- ``WarMember.town_hall`` has been fixed
- The API used to fetch IP has been changed (19) to https://api.ipify.org/
- Ensure the clan is in war before trying to find prep time (21)

New Things
~~~~~~~~~~~~~
- Check out the `Cache` tab in sidebar for a how-to work with the new cache. It still works out of the box!
- You can now call utils with ``coc.utils.X``
- All events now have callbacks as an extra layer of security to stop them from failing.
- New Properties: ``Clan.share_link`` and ``Player.share_link``.
- Add ``utils.maybe_sort()`` as an easy tool to sort clan war attacks.
- All attributes that were prefaced with a ``_`` to dictate being iterables have been changed to be prefixed
with ``iter``, ie. ``_attacks`` becomes ``iterattacks``.
- Rename ``SearchPlayer.level`` to ``SearchPlayer.exp_level`` - keep in line with API naming.
- Default value can be passed to ``BasicPlayer.league``; defaults to `None`
- Default value for ``SearchPlayer.builder_hall`` is 0.
- New Error: `PrivateWarLog`:

- Subclass of `Forbidden` and a special case for when a 403 is thrown from trying to access war info for a clan with a private war log.
- Redirect all `Forbidden` thrown errors in get_WARS methods to throw `PrivateWarLog`

- A valid operation is to do either:

.. code-block:: python3

try:
await coc.get_current_war(...)
except coc.Forbidden:
pass

or:

try:
await coc.get_current_war(...)
except coc.PrivateWarLog:
pass

- ``EventsClient.add_X_update`` now accepts either a string or iterable.
- New Method: ``client.remove_events()`` which works in the same way as ``client.add_events()``
- Speed up `utils.get`
- New Events:
- :ref:`on_player_clan_join` - when a player joins a clan
- :ref:`on_player_clan_leave` - when a player leaves a clan
- :ref:`on_player_clan_level_change` - when a player's clan's level changes
- :ref:`on_player_clan_badge_change` - when a player's clan's badges change.
- `on_client_close` which is dispatched upon closing the client

- Rename `x_achievement_update` --> `x_achievement_change` for consistency
- Add ``localised_name`` and ``localised_short_name`` attributes to :class:`League` and :class:`Location`
- These have no effect at present.

Documentation
~~~~~~~~~~~~~~~
- Lots of the docs have had tidy-ups, with 2 new how-to's dedicated to Cache and the Events Client.

BugFix