lichess package¶

Submodules¶

lichess.client module¶

class lichess.client.Client(token=None)¶

Bases: object

export_arena_games(tournament_id)¶

Export games of an Arena tournament

Parameters: tournament_id (str) – ID of Arena tournament to query
Returns: A string with PGN data of the Arena tournament’s games
Return type: str

export_by_id(game_id, moves=True, pgn_in_json=False, tags=True, clocks=True, evals=True, opening=True, literate=False, players=None)¶

Export an individual game

Parameters

game_id (str) – ID of game to export
moves (Optional[bool]) – Whether to include the PGN moves
pgn_in_json (Optional[bool]) – Whether to include the full PGN within the JSON response
tags (Optional[bool]) – Whether to include the PGN tags
clocks (Optional[bool]) – Whether to include clock comments, whenever available, in the PGN moves
evals (Optional[bool]) – Whether to include analysis evaluation comments, whenever available, in the PGN
opening (Optional[bool]) – Whether to include the opening name
literate (Optional[bool]) – Whether to include textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination
players (Optional[str]) – A URL of a text file containing real names and ratings to replace Lichess usernames and ratings in the PGN

Returns

A string with PGN data of an individual game

Return type

str

export_by_user(user, since=None, until=None, max_games=None, vs=None, rated=None, perf_type=None, color=None, analyzed=None, moves=True, pgn_in_json=False, tags=True, clocks=True, evals=True, opening=True, ongoing=False, finished=True, players=None, sort='dateDesc')¶

Export all the games of a user

Parameters

user (str) – User whose games you want to export
since (Optional[int]) – Filters for games played since this timestamp (default is account creation date)
until (Optional[int]) – Filters for games played until this timestamp (default is now)
max_games (Optional[int]) – How many games to download (default downloads all games)
vs (Optional[str]) – Filter for games that are only played against this specific opponent
rated (Optional[bool]) – Filter for games that are only rated (True) or only casual (False)
perf_type (Optional[str]) – Filter for games that have a specific speed or variant
color (Optional[str]) – Filters for games only played as a specific color (“white” or “black”)
analyzed (Optional[bool]) – Whether to filter for games that have a computer analysis available
moves (Optional[bool]) – Whether to include the PGN moves
pgn_in_json (Optional[bool]) – Whether to include the full PGN within the JSON response
tags (Optional[bool]) – Whether to include the PGN tags
clocks (Optional[bool]) – Whether to include clock comments, whenever available, in the PGN moves
evals (Optional[bool]) – Whether to include analysis evaluation comments, whenever available, in the PGN
opening (Optional[bool]) – Whether to include the opening name
ongoing (Optional[bool]) – Whether to include ongoing games (last 3 moves will be omitted)
finished (Optional[bool]) – Whether to only include finished games (False to only get ongoing games)
players (Optional[str]) – A URL of a text file containing real names and ratings to replace Lichess usernames and ratings in the PGN
sort (Optional[str]) – Sort order of the games (“dateAsc” or “dateDesc”)

Returns

A string with PGN data of all the user’s games

Return type

str

export_chapter(study_id, chapter_id, clocks=True, comments=True, variations=True)¶

Export one study chapter

Parameters

study_id (str) – The study ID (8 characters)
chapter_id (str) – The chapter ID (8 characters)
clocks (Optional[bool]) – When available, include clock comments in the PGN moves
comments (Optional[bool]) – When available, include analysis and annotator comments in the PGN moves
variations (Optional[bool]) – When available, include non-mainline moves

Returns

A string with PGN data of one study chapter

Return type

str

export_chapters(study_id, clocks=True, comments=True, variations=True)¶

Export all the chapters of a study

Parameters

study_id (str) – The study ID (8 characters)
clocks (Optional[bool]) – When available, include clock comments in the PGN moves
comments (Optional[bool]) – When available, include analysis and annotator comments in the PGN moves
variations (Optional[bool]) – When available, include non-mainline moves

Returns

A string with PGN data of all the chapters of a study

Return type

str

export_ongoing_by_user(user, moves=True, pgn_in_json=False, tags=True, clocks=True, evals=True, opening=True, literate=False, players=None)¶

Export the ongoing game of a user

Parameters

user (str) – User whose ongoing game you want to export
moves (Optional[bool]) – Whether to include the PGN moves
pgn_in_json (Optional[bool]) – Whether to include the full PGN within the JSON response
tags (Optional[bool]) – Whether to include the PGN tags
clocks (Optional[bool]) – Whether to include clock comments, whenever available, in the PGN moves
evals (Optional[bool]) – Whether to include analysis evaluation comments, whenever available, in the PGN
opening (Optional[bool]) – Whether to include the opening name
literate (Optional[bool]) – Whether to include textual annotations in the PGN about the opening, analysis variations, mistakes, and game termination
players (Optional[str]) – A URL of a text file containing real names and ratings to replace Lichess usernames and ratings in the PGN

Returns

A string with PGN data of the user’s ongoing game

Return type

str

export_studies(user, clocks=True, comments=True, variations=True)¶

Export all the studies of a user

Parameters

user (str) – The user whose studies to export
clocks (Optional[bool]) – When available, include clock comments in the PGN moves
comments (Optional[bool]) – When available, include analysis and annotator comments in the PGN moves
variations (Optional[bool]) – When available, include non-mainline moves

Returns

A string with PGN data of all the studies of a user

Return type

str

export_swiss_games(tournament_id)¶

Export games of a Swiss tournament

Parameters: tournament_id (str) – ID of Swiss tournament to query
Returns: A string with PGN data of the Swiss tournament’s games
Return type: str

export_swiss_info(tournament_id)¶

Export the TRF of a Swiss tournament

Parameters: tournament_id (str) – ID of Swiss tournament to query
Returns: A string with TRF data of the Swiss tournament
Return type: str

following()¶

Get users who you are following

Returns: A list with dictionaries containing the information of users you are following
Return type: list

get_activity(user)¶

Get the activity feed of an individual user

Parameters: user (str) – User to query their activity feed
Returns: A list with dictionaries containing the activity feed of the user
Return type: list

get_arena_all()¶

Get recently finished, ongoing, and upcoming tournaments

Returns: A dictionary with the recently finished, ongoing, and upcoming tournaments
Return type: dict

get_arena_createdby(user)¶

Get tournaments created by a user

Parameters: user (str) – User to query their created tournaments
Returns: A list with dictionaries of all the tournaments created by the user
Return type: list

get_arena_info(tournament_id, page=1)¶

Get info about an Arena tournament

Parameters

tournament_id (str) – ID of Arena tournament to query
page (Optional[int]) –

Returns

A dictionary with the info about the queried Arena tournament

Return type

dict

get_arena_results(tournament_id, max_players=None)¶

Get results of an Arena tournament

Parameters

tournament_id (str) – ID of Arena tournament to query
max_players (Optional[int]) – Maximum number of players to fetch

Returns

A list with dictionaries of Arena tournament players, with their score and performance, sorted by rank (best first)

Return type

list

get_crosstable(user1, user2, matchup=False)¶

Get the crosstable of two users

Parameters

user1 (str) – First user to compare with second user
user2 (str) – Second user to compare with first user
matchup (Optional[bool]) – Flag to get current match data, if the two users are currently playing

Returns

A dictionary with the crosstable (total number of games and current score of the two users)

Return type

dict

get_daily_puzzle()¶

Get the daily puzzle

Returns: A dictionary with the daily puzzle
Return type: dict

get_data(user)¶

Get public data of an individual user

Parameters: user (str) – User to query their public data
Returns: A dictionary with the public data of the user
Return type: dict

get_email()¶

Get your email address

Returns: A dictionary with your email address
Return type: dict

get_games_channel(channel, num_games=10, moves=True, pgn_in_json=False, tags=True, clocks=True, opening=True)¶

Get the best games currently being played for a specific speed/variant, including computer games and bot games

Parameters

channel (str) – Name of the channel in camelCase
num_games (Optional[bool]) – Number of games to fetch
moves (Optional[bool]) – Whether to include the PGN moves
pgn_in_json (Optional[bool]) – Whether to include the full PGN within the JSON response
tags (Optional[bool]) – Whether to include the PGN tags
clocks (Optional[bool]) – Whether to include clock comments, whenever available, in the PGN moves
opening (Optional[bool]) – Whether to include the opening name

Returns

A string with the PGN data of the best games being played for a specific speed/variant

Return type

str

get_games_channels()¶

Get the best games currently being played for each speed/variant, including computer games and bot games

Returns: A dictionary with info on the current TV games
Return type: dict

get_kid_mode()¶

Get your kid mode status

Returns: A dictionary with your kid mode status
Return type: dict

get_live_streamers()¶

Get the current live streamers

Returns: A list with dictionaries containing the current live streamers
Return type: list

get_ongoing(max_games=9)¶

Get your ongoing games (realtime and correspondence)

Parameters: max_games (int) – Max number of games to fetch
Returns: A dictionary with your ongoing games
Return type: dict

get_popular_teams(page=1)¶

Get popular teams

Parameters: page (Optional[int]) – Page of most popular teams to query
Returns: A dictionary with the popular teams
Return type: dict

get_preferences()¶

Get your preferences

Returns: A dictionary with your preferences
Return type: dict

get_profile()¶

Get your public profile information

Returns: A dictionary with your public information
Return type: dict

get_puzzle_activity(max_entries=None)¶

Get your puzzle activity

Parameters: max_entries (Optional[int]) – Number of entries to download (leave empty to download all activity)
Returns: A list with dictionaries containing all your puzzle activity
Return type: list

get_puzzle_dashboard(days)¶

Get your puzzle dashboard

Parameters: days (int) – Number of days to look back when aggregating puzzle results
Returns: A dictionary with your puzzle dashboard data
Return type: dict

get_rating_history(user)¶

Get rating history of an individual user

Parameters: user (str) – User to query their public data
Returns: A list with dictionaries containing the rating history of the user
Return type: list

get_simuls()¶

Get recently finished, ongoing, and upcoming simuls

Returns: A dictionary with the recently finished, ongoing, and upcoming simuls
Return type: dict

get_stats(user, perf_type)¶

Get performance statistics of an individual user

Parameters

user (str) – User to query their performance statistics
perf_type (str) – Type of speed or variant to query

Returns

A dictionary with the performance statistics of the user

Return type

dict

get_status(users, with_game_ids=False)¶

Get real-time status of one or more users

Parameters

users (list[str]) – Users to query their real-time status
with_game_ids (Optional[bool]) – Flag to include the ID of games being played, if any, for each player

Returns

A list with dictionaries containing the real-time status of one or more users

Return type

list

get_storm_dashboard(user, days=30)¶

Get the storm dashboard of a player

Parameters

user (str) – User to query their storm dashboard data
days (Optional[int]) – Number of days of history to return (set to zero for only highscores)

Returns

A dictionary with the storm dashboard data of the user

Return type

dict

get_swiss_info(tournament_id)¶

Get info about a Swiss tournament

Parameters: tournament_id (str) – ID of Swiss tournament to query
Returns: A dictionary with the info about the queried Swiss tournament
Return type: dict

get_swiss_results(tournament_id, max_players=None)¶

Get results of a Swiss tournament

Parameters

tournament_id (str) – ID of Swiss tournament to query
max_players (Optional[int]) – Maximum number of players to fetch

Returns

A list with dictionaries of Swiss tournament players, with their score and performance, sorted by rank (best first)

Return type

list

get_team_info(team_id)¶

Get info about a team

Parameters: team_id (str) – ID of team whose info to query
Returns: A dictionary with the team’s info
Return type: dict

get_team_members(team_id)¶

Get members of a team

Parameters: team_id (str) – ID of team whose members to query
Returns: A list with dictionaries containing the members of a team
Return type: list

get_team_swiss(team_id, max_tournaments=100)¶

Get all swiss tournaments of a team

Parameters

team_id (str) – ID of team whose info to query
max_tournaments (Optional[int]) – Maximum tournaments to query

Returns

A list with dictionaries containing all the swiss tournaments of a team

Return type

list

get_teambattle_info(tournament_id)¶

Get team standing of a team battle

Parameters: tournament_id (str) – ID of arena tournament to query
Returns: A dictionary with the info about the queried team battle
Return type: dict

get_teams_player(user)¶

Get all the teams a player is a member of

Parameters: user (str) – User to query their team memberships
Returns: A list with dictionaries containing the teams a player is a member of
Return type: list

search_teams(text, page=1)¶

Get search results for keyword in team search

Parameters

text (str) – Keyword to use in team search
page (Optional[int]) – Page of team search to query

Returns

A dictionary with the team search results

Return type

dict

lichess.enums module¶

class lichess.enums.HttpStatusCode(value)¶

Bases: Enum

EXAMPLES:: HttpStatusCode.OK.value # 100 HttpStatusCode.INTERNAL_SERVER_ERROR.value # 500

ACCEPTED = 202¶

ALREADY_REPORTED = 208¶

BAD_GATEWAY = 502¶

BAD_REQUEST = 400¶

CONFLICT = 409¶

CONTINUE = 100¶

CREATED = 201¶

EARLY_HINTS = 103¶

EXPECTATION_FAILED = 417¶

FAILED_DEPENDENCY = 424¶

FORBIDDEN = 403¶

FOUND = 302¶

GATEWAY_TIMEOUT = 504¶

GONE = 410¶

HTTP_VERSION_NOT_SUPPORTED = 505¶

IM_A_TEAPOT = 418¶

IM_USED = 226¶

INSUFFICIENT_STORAGE = 507¶

INTERNAL_SERVER_ERROR = 500¶

LENGTH_REQUIRED = 411¶

LOCKED = 423¶

LOOP_DETECTED = 508¶

METHOD_NOT_ALLOWED = 405¶

MISDIRECTED_REQUEST = 421¶

MOVED_PERMANENTLY = 301¶

MULTIPLE_CHOICE = 300¶

MULTI_STATUS = 207¶

NETWORK_AUTHENTICATION_REQUIRED = 511¶

NON_AUTHORITATIVE_INFORMATION = 203¶

NOT_ACCEPTABLE = 406¶

NOT_EXTENDED = 510¶

NOT_FOUND = 404¶

NOT_IMPLEMENTED = 501¶

NOT_MODIFIED = 304¶

NO_CONTENT = 204¶

OK = 200¶

PARTIAL_CONTENT = 206¶

PAYLOAD_TOO_LARGE = 413¶

PAYMENT_REQUIRED = 402¶

PERMANENT_REDIRECT = 308¶

PRECONDITION_FAILED = 412¶

PRECONDITION_REQUIRED = 428¶

PROCESSING = 102¶

PROXY_AUTHENTICATION_REQUIRED = 407¶

REQUESTED_RANGE_NOT_SATISFIABLE = 416¶

REQUEST_HEADER_FIELDS_TOO_LARGE = 431¶

REQUEST_TIMEOUT = 408¶

RESET_CONTENT = 205¶

SEE_OTHER = 303¶

SERVICE_UNAVAILABLE = 503¶

SWITCHING_PROTOCOL = 101¶

TEMPORARY_REDIRECT = 307¶

TOO_EARLY = 425¶

TOO_MANY_REQUESTS = 429¶

UNAUTHORIZED = 401¶

UNAVAILABLE_FOR_LEGAL_REASONS = 451¶

UNPROCESSABLE_ENTITY = 422¶

UNSUPPORTED_MEDIA_TYPE = 415¶

UNUSED = 306¶

UPGRADE_REQUIRED = 426¶

URI_TOO_LONG = 414¶

USE_PROXY = 305¶

VARIANT_ALSO_NEGOTIATES = 506¶

class lichess.enums.PerfType(value)¶

Bases: Enum

EXAMPLES:: PerfType.ULTRA_BULLET.value # “ultraBullet” PerfType.CHESS960.value # “chess960”

ANTICHESS = 'antichess'¶

ATOMIC = 'atomic'¶

BLITZ = 'blitz'¶

BULLET = 'bullet'¶

CHESS960 = 'chess960'¶

CLASSICAL = 'classical'¶

CRAZYHOUSE = 'crazyhouse'¶

HORDE = 'horde'¶

KING_OF_THE_HILL = 'kingOfTheHill'¶

RACING_KINGS = 'racingKings'¶

RAPID = 'rapid'¶

THREE_CHECK = 'threeCheck'¶

ULTRA_BULLET = 'ultraBullet'¶

lichess.exceptions module¶

exception lichess.exceptions.APIKeyError(message)¶: Bases: ValueError

exception lichess.exceptions.ResponseError(message)¶: Bases: ValueError

lichess.utils module¶

lichess.utils.ndjson(response)¶

lichess.utils.valid_input(user_input)¶

lichess package¶

Submodules¶

lichess.client module¶

lichess.enums module¶

lichess.exceptions module¶

lichess.utils module¶

Module contents¶

lichess

Navigation

Related Topics