=======
berserk
=======
.. image:: https://img.shields.io/pypi/v/berserk.svg
:target: https://pypi.python.org/pypi/berserk
:alt: Available on PyPI
.. image:: https://img.shields.io/travis/rhgrant10/berserk.svg
:target: https://travis-ci.org/rhgrant10/berserk
:alt: Continuous Integration
.. image:: https://codecov.io/gh/rhgrant10/berserk/branch/master/graph/badge.svg
:target: https://codecov.io/gh/rhgrant10/berserk
:alt: Code Coverage
.. image:: https://readthedocs.org/projects/berserk/badge/?version=latest
:target: https://berserk.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
Python client for the `Lichess API`_.
.. _Lichess API: https://lichess.org/api
* Free software: GNU General Public License v3
* Documentation: https://berserk.readthedocs.io.
Features
========
* handles JSON and PGN formats at user's discretion
* token auth session
* easy integration with OAuth2
* automatically converts time values to datetimes
Usage
=====
You can use any ``requests.Session``-like object as a session, including those
from ``requests_oauth``. A simple token session is included, as shown below:
.. code-block:: python
import berserk
session = berserk.TokenSession(API_TOKEN)
client = berserk.Client(session=session)
Most if not all of the API is available:
.. code-block:: python
client.account.get
client.account.get_email
client.account.get_preferences
client.account.get_kid_mode
client.account.set_kid_mode
client.account.upgrade_to_bot
client.users.get_puzzle_activity
client.users.get_realtime_statuses
client.users.get_all_top_10
client.users.get_leaderboard
client.users.get_public_data
client.users.get_activity_feed
client.users.get_by_id
client.users.get_by_team
client.users.get_live_streamers
client.users.get_users_followed
client.users.get_users_following
client.users.get_rating_history
client.teams.get_members
client.teams.join
client.teams.leave
client.teams.kick_member
client.games.export
client.games.export_by_player
client.games.export_multi
client.games.get_among_players
client.games.get_ongoing
client.games.get_tv_channels
client.challenges.create
client.challenges.create_ai
client.challenges.create_open
client.challenges.create_with_accept
client.challenges.accept
client.challenges.decline
client.board.stream_incoming_events
client.board.seek
client.board.stream_game_state
client.board.make_move
client.board.post_message
client.board.abort_game
client.board.resign_game
client.board.handle_draw_offer
client.board.offer_draw
client.board.accept_draw
client.board.decline_draw
client.bots.stream_incoming_events
client.bots.stream_game_state
client.bots.make_move
client.bots.post_message
client.bots.abort_game
client.bots.resign_game
client.bots.accept_challenge
client.bots.decline_challenge
client.tournaments.get
client.tournaments.create
client.tournaments.export_games
client.tournaments.stream_results
client.tournaments.stream_by_creator
client.broadcasts.create
client.broadcasts.get
client.broadcasts.update
client.broadcasts.push_pgn_update
client.simuls.get
client.studies.export_chapter
client.studies.export
Details for each function can be found in the `full documentation <https://berserk.readthedocs.io>`_.
Credits
=======
This package was created with Cookiecutter_ and the
`audreyr/cookiecutter-pypackage`_ project template.
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
History
=======
0.10.0 (2020-04-26)
-------------------
* Add ``Challenge.create_ai`` for creating an AI challenge
* Add ``Challenge.create_open`` for creating an open challenge
* Add ``Challenge.create_with_accept`` auto-acceptance of challenges using OAuth token
* Bugfix for passing initial board positions in FEN for challenges
* Minor fixes for docstrings
0.9.0 (2020-04-14)
------------------
* Add remaining ``Board`` endpoints: seek, handle_draw_offer, offer_draw, accept_draw, and decline_draw
* Multiple doc updates/fixes
* Add codecov reporting
0.8.0 (2020-03-08)
------------------
* Add new ``Board`` client: stream_incoming_events, stream_game_state, make_move, post_message, abort_game, and resign_game
0.7.0 (2020-01-26)
------------------
* Add simuls
* Add studies export and export chapter
* Add tournament results, games export, and list by creator
* Add user followers, users following, rating history, and puzzle activity
* Add new ``Teams`` client: join, get members, kick member, and leave
* Updated documentation, including new docs for some useful utils
* Fixed bugs in ``Tournaments.export_games``
* Deprecated ``Users.get_by_team`` - use ``Teams.get_members`` instead
0.6.1 (2020-01-20)
------------------
* Add py37 to the travis build
* Update development status classifier to 4 - Beta
* Fix py36 issue preventing successful build
* Make updates to the Makefile
0.6.0 (2020-01-20)
------------------
* Add logging to the ``berserk.session`` module
* Fix exception message when no cause
* Fix bug in ``Broadcasts.push_pgn_update``
* Update documentation and tweak the theme
0.5.0 (2020-01-20)
------------------
* Add ``ResponseError`` for 4xx and 5xx responses with status code, reason, and cause
* Add ``ApiError`` for all other request errors
* Fix test case broken by 0.4.0 release
* Put all utils code under test
0.4.0 (2020-01-19)
------------------
* Add support for the broadcast endpoints
* Add a utility for easily converting API objects into update params
* Fix multiple bugs with the tournament create endpoint
* Improve the reusability of some conversion utilities
* Improve many docstrings in the client classes
0.3.2 (2020-01-04)
------------------
* Fix bug where options not passed for challenge creation
* Convert requirements from pinned to sematically compatible
* Bump all developer dependencies
* Use pytest instead of the older py.test
* Use py37 in tox
0.3.1 (2018-12-23)
------------------
* Convert datetime string in tournament creation response into datetime object
0.3.0 (2018-12-23)
------------------
* Convert all timestamps to datetime in all responses
* Provide support for challenging other players to a game
0.2.1 (2018-12-08)
------------------
* Bump requests dependency to >-2.20.0 (CVE-2018-18074)
0.2.0 (2018-12-08)
------------------
* Add `position` and `start_date` params to `Tournament.create`
* Add `Position` enum
0.1.2 (2018-07-14)
------------------
* Fix an asine bug in the docs
0.1.1 (2018-07-14)
------------------
* Added tests for session and formats modules
* Fixed mispelled PgnHandler class (!)
* Fixed issue with trailing whitespace when splitting multiple PGN texts
* Fixed the usage overview in the README
* Fixed the versions for travis-ci
* Made it easier to test the `JsonHandler` class
* Salted the bumpversion config to taste
0.1.0 (2018-07-10)
------------------
* First release on PyPI.