API

User

challonge.get_user(username: str, api_key: str, **kwargs) → challonge.user.User

Creates a new user, validate its credentials and returns it

This function is a coroutine and needs to be awaited.

Parameters:
  • username – username as specified on the challonge website
  • api_key – key as found on the challonge settings
Returns:

a logged in user if no exception has been raised

Return type:

User

Raises:

APIException

class challonge.User(username: str, api_key: str, **kwargs)

Representation of a Challonge user

Main entry point for using the async challonge library.

create_tournament(name: str, url: str, tournament_type: challonge.enums.TournamentType=<TournamentType.single_elimination: 'single elimination'>, **params) → challonge.tournament.Tournament

creates a simple tournament with basic options

This method is a coroutine and needs to be awaited.

Parameters:
Returns:

the newly created tournament

Return type:

Tournament

Raises:

APIException

destroy_tournament(t: challonge.tournament.Tournament)

completely removes a tournament from Challonge

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Deletes a tournament along with all its associated records. There is no undo, so use with care!

Raises:APIException
get_tournament(t_id: int=None, url: str=None, subdomain: str=None, force_update=False) → challonge.tournament.Tournament

gets a tournament with its id or url or url+subdomain Note: from the API, it can’t be known if the retrieved tournament was made from this user. Thus, any tournament is added to the local list of tournaments, but some functions (updates/destroy...) cannot be used for tournaments not owned by this user.

This method is a coroutine and needs to be awaited.

Parameters:
  • t_id – tournament id
  • url – last part of the tournament url (http://challonge.com/XXX)
  • subdomain – first part of the tournament url, if any (http://XXX.challonge.com/...)
  • force_updateoptional set to True to force the data update from Challonge
Returns:

Tournament

Raises:
  • APIException
  • ValueError – if neither of the arguments are provided
get_tournaments(subdomain: str=None, force_update: bool=False) → list

gets all user’s tournaments

This method is a coroutine and needs to be awaited.

Parameters:
  • subdomainoptional subdomain needs to be given explicitely to get tournaments in a subdomain
  • force_updateoptional set to True to force the data update from Challonge
Returns:

list of all the user tournaments

Return type:

list[Tournament]

Raises:

APIException

validate()

checks whether the current user is connected

This method is a coroutine and needs to be awaited.

Raises:APIException

Tournament

class challonge.Tournament(connection, json_def, **kwargs)

Representation of a Challonge tournament

abort_check_in()

Abort the check in process

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Note

From Challonge API: When your tournament is in a ‘checking_in’ or ‘checked_in’ state, there’s no way to edit the tournament’s start time (start_at) or check-in duration (check_in_duration). You must first abort check-in, then you may edit those attributes. 1. Makes all participants active and clears their checked_in_at times. 2. Transitions the tournament state from ‘checking_in’ or ‘checked_in’ to ‘pending’

Raises:APIException
accept_attachments

readonly attribute

accepting_predictions

readonly attribute

add_participant(display_name: str=None, username: str=None, email: str=None, seed: int=0, misc: str=None, **params)

add a participant to the tournament

This method is a coroutine and needs to be awaited.

Parameters:
  • display_name – The name displayed in the bracket/schedule - not required if email or challonge_username is provided. Must be unique per tournament.
  • username – Provide this if the participant has a Challonge account. He or she will be invited to the tournament.
  • email – Providing this will first search for a matching Challonge account. If one is found, this will have the same effect as the “challonge_username” attribute. If one is not found, the “new-user-email” attribute will be set, and the user will be invited via email to create an account.
  • seed – The participant’s new seed. Must be between 1 and the current number of participants (including the new record). Overwriting an existing seed will automatically bump other participants as you would expect.
  • misc – Max: 255 characters. Multi-purpose field that is only visible via the API and handy for site integration (e.g. key to your users table)
  • params – optional params (see http://api.challonge.com/v1/documents/participants/create)
Returns:

newly created participant

Return type:

Participant

Raises:

APIException

add_participants(*names: str) → list

This method is a coroutine and needs to be awaited.

Warning

This method is being worked on. Consider it a preview, and not a final version: it may change in a later version.

Raises:APIException
allow_attachments(allow: bool=True)

allow this tournament to accept attachments or not

This method is a coroutine and needs to be awaited.

Parameters:allow (default=True) – False to disallow
Raises:APIException
allow_participant_match_reporting

readonly attribute

anonymous_voting

readonly attribute

category

readonly attribute

check_in_duration

readonly attribute

completed_at

readonly attribute

created_at

readonly attribute

created_by_api

readonly attribute

credit_capped

readonly attribute

description

readonly attribute

description_source

readonly attribute

event_id

readonly attribute

finalize()

finalize the tournament on Challonge

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Finalize a tournament that has had all match scores submitted, rendering its results permanent.

Raises:APIException
full_challonge_url

readonly attribute

game_id

readonly attribute

game_name

readonly attribute

get_final_ranking() → collections.OrderedDict

Get the ordered players ranking

Returns:
Return type:collections.OrderedDict[rank, List[Participant]]
Raises:APIException
get_match(m_id, force_update=False) → challonge.match.Match

get a single match by id

This method is a coroutine and needs to be awaited.

Parameters:
  • m_id – match id
  • force_update (default=False) – True to force an update to the Challonge API
Returns:

Match

Raises:

APIException

get_matches(force_update=False) → list

get all matches (once the tournament is started)

This method is a coroutine and needs to be awaited.

Parameters:force_update (default=False) – True to force an update to the Challonge API
Returns:
Return type:list[Match]
Raises:APIException
get_participant(p_id: int, force_update=False) → challonge.participant.Participant

get a participant by its id

This method is a coroutine and needs to be awaited.

Parameters:
  • p_id – participant id
  • force_update (dfault=False) – True to force an update to the Challonge API
Returns:

None if not found

Return type:

Participant

Raises:

APIException

get_participants(force_update=False) → list

get all participants

This method is a coroutine and needs to be awaited.

Parameters:force_update (default=False) – True to force an update to the Challonge API
Returns:
Return type:list[Participant]
Raises:APIException
grand_finals_modifier

readonly attribute

group_stages_enabled

readonly attribute

group_stages_were_started

readonly attribute

hide_forum

readonly attribute

hide_seeds

readonly attribute

hold_third_place_match

readonly attribute

id

readonly attribute

live_image_url

readonly attribute

locked_at

readonly attribute

max_predictions_per_user

readonly attribute

name

readonly attribute

notify_users_when_matches_open

readonly attribute

notify_users_when_the_tournament_ends

readonly attribute

open_signup

readonly attribute

participants_count

readonly attribute

participants_locked

readonly attribute

participants_swappable

readonly attribute

predict_the_losers_bracket

readonly attribute

prediction_method

readonly attribute

predictions_opened_at

readonly attribute

private

readonly attribute

process_check_ins()

finalize the check in phase

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Note

From Challonge API: This should be invoked after a tournament’s check-in window closes before the tournament is started. 1. Marks participants who have not checked in as inactive. 2. Moves inactive participants to bottom seeds (ordered by original seed). 3. Transitions the tournament state from ‘checking_in’ to ‘checked_in’ NOTE: Checked in participants on the waiting list will be promoted if slots become available.

Raises:APIException
progress_meter

readonly attribute

pts_for_bye

readonly attribute

pts_for_game_tie

readonly attribute

pts_for_game_win

readonly attribute

pts_for_match_tie

readonly attribute

pts_for_match_win

readonly attribute

public_predictions_before_start_time

readonly attribute

quick_advance

readonly attribute

ranked

readonly attribute

ranked_by

readonly attribute

remove_participant(p: challonge.participant.Participant)

remove a participant from the tournament

This method is a coroutine and needs to be awaited.

Parameters:p – the participant to remove
Raises:APIException
require_score_agreement

readonly attribute

reset()

reset the tournament on Challonge

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Reset a tournament, clearing all of its scores and attachments. You can then add/remove/edit participants before starting the tournament again.

Raises:APIException
review_before_finalizing

readonly attribute

rr_pts_for_game_tie

readonly attribute

rr_pts_for_game_win

readonly attribute

rr_pts_for_match_tie

readonly attribute

rr_pts_for_match_win

readonly attribute

search_participant(name, force_update=False)

search a participant by (display) name

This method is a coroutine and needs to be awaited.

Parameters:
  • name – display name of the participant
  • force_update (dfault=False) – True to force an update to the Challonge API
Returns:

None if not found

Return type:

Participant

Raises:

APIException

sequential_pairings

readonly attribute

set_max_participants(max_participants: int)

This method is a coroutine and needs to be awaited.

Parameters:max_participants – Maximum number of participants in the bracket. A waiting list (attribute on Participant) will capture participants once the cap is reached.
Raises:APIException
set_private(private: bool=True)

Hide this tournament from the public browsable index and your profile

This method is a coroutine and needs to be awaited.

Parameters:private
Raises:APIException
set_single_elim_third_place_match(play_third_place_match: bool)

This method is a coroutine and needs to be awaited.

Parameters:play_third_place_match – Include a match between semifinal losers if True
Raises:APIException
set_start_date(date: str, time: str, check_in_duration: int=None)

set the tournament start date (and check in duration)

This method is a coroutine and needs to be awaited.

Parameters:
  • date – fomatted date as YYYY/MM/DD (2017/02/14)
  • time – fromatted time as HH:MM (20:15)
  • check_in_duration (optional) – duration in minutes
Raises:

APIException

setup_round_robin_points(match_win: float=None, match_tie: float=None, game_win: float=None, game_tie: float=None)

This method is a coroutine and needs to be awaited.

Parameters:
  • match_win
  • match_tie
  • game_win
  • game_tie
Raises:

APIException

setup_swiss_points(match_win: float=None, match_tie: float=None, game_win: float=None, game_tie: float=None, bye: float=None)

This method is a coroutine and needs to be awaited.

Parameters:
  • match_win
  • match_tie
  • game_win
  • game_tie
  • bye
Raises:

APIException

setup_swiss_rounds(rounds_count: int)

This method is a coroutine and needs to be awaited.

Note

From Challonge API: We recommend limiting the number of rounds to less than two-thirds the number of players. Otherwise, an impossible pairing situation can be reached and your tournament may end before the desired number of rounds are played.

Parameters:rounds_count
Raises:APIException
show_rounds

readonly attribute

sign_up_url

readonly attribute

signup_cap

readonly attribute

start()

start the tournament on Challonge

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Start a tournament, opening up first round matches for score reporting. The tournament must have at least 2 participants.

Raises:APIException
start_at

readonly attribute

started_at

readonly attribute

started_checking_in_at

readonly attribute

state

readonly attribute

subdomain

readonly attribute

swiss_rounds

readonly attribute

team_convertable

readonly attribute

teams

readonly attribute

tie_breaks

readonly attribute

tournament_type

readonly attribute

update(**params)

update some parameters of the tournament

Use this function if you want to update multiple options at once, but prefer helpers functions like allow_attachments(), set_start_date()...

This method is a coroutine and needs to be awaited.

Parameters:params – one or more of: name tournament_type url subdomain description open_signup hold_third_place_match pts_for_match_win pts_for_match_tie pts_for_game_win pts_for_game_tie pts_for_bye swiss_rounds ranked_by rr_pts_for_match_win rr_pts_for_match_tie rr_pts_for_game_win rr_pts_for_game_tie accept_attachments hide_forum show_rounds private notify_users_when_matches_open notify_users_when_the_tournament_ends sequential_pairings signup_cap start_at check_in_duration grand_finals_modifier
Raises:APIException
update_description(new_description: str)

This method is a coroutine and needs to be awaited.

Parameters:new_description – the description to be changed to
Raises:APIException
update_double_elim_ending(ending: challonge.enums.DoubleEliminationEnding)

update the ending format for your Double Elimination tournament

This method is a coroutine and needs to be awaited.

Parameters:
  • ending – choose between: * DoubleEliminationEnding.default: give the winners bracket finalist two chances to beat the losers bracket finalist
  • DoubleEliminationEnding.single_match (*) – create only one grand finals match
  • DoubleEliminationEnding.no_grand_finals (*) – don’t create a finals match between winners and losers bracket finalists
Raises:

APIException

update_name(new_name: str)

This method is a coroutine and needs to be awaited.

Parameters:new_name – the name to be changed to (Max: 60 characters)
Raises:APIException
update_notifications(on_match_open: bool=None, on_tournament_end: bool=None)

update participants notifications for this tournament

This method is a coroutine and needs to be awaited.

Parameters:
  • on_match_open – Email registered Challonge participants when matches open up for them
  • on_tournament_end – Email registered Challonge participants the results when this tournament ends
Raises:

APIException

update_pairing_method(pairing: challonge.enums.Pairing)

This method is a coroutine and needs to be awaited.

Parameters:pairing
Raises:APIException
update_ranking_order(order: challonge.enums.RankingOrder)

This method is a coroutine and needs to be awaited.

Parameters:order – see RankingOrder
Raises:APIException
update_subdomain(new_subdomain: str)

This method is a coroutine and needs to be awaited.

Parameters:new_subdomain – the subdomain to be changed to (subdomain.challonge.com/url - letters, numbers, and underscores only)
Raises:APIException – if you don’t have write access to this subdomain
update_tournament_type(tournament_type: challonge.enums.TournamentType)

This method is a coroutine and needs to be awaited.

Parameters:tournament_type – choose between TournamentType.single_elimination, TournamentType.double_elimination, TournamentType.round_robin, TournamentType.swiss
Raises:APIException
update_url(new_url: str)

This method is a coroutine and needs to be awaited.

Parameters:new_url – the url to be changed to (challonge.com/url - letters, numbers, and underscores only)
Raises:APIException
update_website_options(hide_forum: bool=None, show_rounds: bool=None, open_signup: bool=None)

This method is a coroutine and needs to be awaited.

Parameters:
  • hide_forum – Hide the forum tab on your Challonge page
  • show_rounds – Double Elimination only - Label each round above the bracket
  • open_signup – Have Challonge host a sign-up page (otherwise, you manually add all participants)
Raises:

APIException

updated_at

readonly attribute

url

readonly attribute

Participant

class challonge.Participant(connection, json_def, tournament, **kwargs)

Representation of a Challonge participant

active

readonly attribute

attached_participatable_portrait_url

readonly attribute

can_check_in

readonly attribute

challonge_email_address_verified

readonly attribute

challonge_username

readonly attribute

change_display_name(new_name: str)

Change the name displayed on the Challonge website

This method is a coroutine and needs to be awaited.

Note

From Challonge API: The name displayed in the bracket/schedule. Must be unique per tournament.

Parameters:new_name – as described
Raises:APIException
change_email(email: str)

Set / update the email associated to the participant

This method is a coroutine and needs to be awaited.

Setting an email will first search for a matching Challonge account. If one is found, it will be invited to the tournament. If one is not found, the “new-user-email” attribute will be set, and the user will be invited via email to create an account.

Parameters:email – as described
Raises:APIException
change_misc(misc: str) → str

Change the misc field

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Max: 255 characters. Multi-purpose field that is only visible via the API and handy for site integration (e.g. key to your users table)

Parameters:misc – str content
Raises:APIException
change_seed(new_seed: int) → int

Change the seed of the participant

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Must be between 1 and the current number of participants (including the new record). Overwriting an existing seed will automatically bump other participants as you would expect.

Parameters:new_seed – as described
Returns:the same seed number as passed or None if something failed
Raises:APIException
change_username(username: str)

Will invite the Challonge user to the tournament

This method is a coroutine and needs to be awaited.

Parameters:username – Challonge username
Raises:APIException
check_in()

Checks this participant in

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Raises:APIException
checked_in

readonly attribute

checked_in_at

readonly attribute

confirm_remove

readonly attribute

created_at

readonly attribute

display_name

readonly attribute

display_name_with_invitation_email_address

readonly attribute

email_hash

readonly attribute

final_rank

readonly attribute

get_matches(state: challonge.enums.MatchState=<MatchState.all_: 'all'>)

Return the matches of the given state

This method is a coroutine and needs to be awaited.

Parameters:state – see MatchState
Raises:APIException
get_next_match()

Return the first open match found, or if none, the first pending match found

This method is a coroutine and needs to be awaited.

Raises:APIException
get_next_opponent()

Get the opponent of the potential next match. See get_next_match()

This method is a coroutine and needs to be awaited.

Raises:APIException
group_id

readonly attribute

group_player_ids

readonly attribute

icon

readonly attribute

id

readonly attribute

invitation_id

readonly attribute

invitation_pending

readonly attribute

invite_email

readonly attribute

misc

readonly attribute

name

readonly attribute

on_waiting_list

readonly attribute

participatable_or_invitation_attached

readonly attribute

reactivatable

readonly attribute

removable

readonly attribute

seed

readonly attribute

tournament_id

readonly attribute

undo_check_in()

Undo the check in for this participant

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Raises:APIException
updated_at

readonly attribute

username

readonly attribute

Match

class challonge.Match(connection, json_def, tournament, **kwargs)

Representation of a Challonge match

attach_file(file_path: str, description: str=None) → challonge.attachment.Attachment

add a file as an attachment

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Parameters:
  • file_path – path to the file you want to add
  • descriptionoptional description for your attachment
Returns:

Return type:

Attachment

Raises:
attach_text(text: str) → challonge.attachment.Attachment

add a simple text as an attachment

This method is a coroutine and needs to be awaited.

Parameters:

text – content you want to add (description)

Returns:

newly created instance

Return type:

Attachment

Raises:
attach_url(url: str, description: str=None) → challonge.attachment.Attachment

add an url as an attachment

This method is a coroutine and needs to be awaited.

Parameters:
  • url – url you want to add
  • descriptionoptional description for your attachment
Returns:

Return type:

Attachment

Raises:
attachment_count

readonly attribute

change_votes(player1_votes: int=None, player2_votes: int=None, add: bool=False)

change the votes for either player

This method is a coroutine and needs to be awaited. The votes will be overriden by default, If add is set to True, another API request call will be made to ensure the local is up to date with the Challonge server. Then the votes given in argument will be added to those on the server

Parameters:
  • player1_votes – if set, the player 1 votes will be changed to this value, or added to the current value if add is set
  • player1_votes – if set, the player 2 votes will be changed to this value, or added to the current value if add is set
  • add – if set, votes in parameters will be added instead of overriden
Raises:
  • ValueError – one of the votes arguments must not be None
  • APIException
completed_at

readonly attribute

created_at

readonly attribute

destroy_attachment(a: challonge.attachment.Attachment)

destroy a match attachment

This method is a coroutine and needs to be awaited.

Parameters:a – the attachment you want to destroy
Raises:APIException
group_id

readonly attribute

has_attachment

readonly attribute

id

readonly attribute

identifier

readonly attribute

location

readonly attribute

loser_id

readonly attribute

optional

readonly attribute

player1_id

readonly attribute

player1_is_prereq_match_loser

readonly attribute

player1_prereq_match_id

readonly attribute

player1_votes

readonly attribute

player2_id

readonly attribute

player2_is_prereq_match_loser

readonly attribute

player2_prereq_match_id

readonly attribute

player2_votes

readonly attribute

prerequisite_match_ids_csv

readonly attribute

reopen()

Reopens a match that was marked completed, automatically resetting matches that follow it

This method is a coroutine and needs to be awaited.

Raises:APIException
report_live_scores(scores_csv: str)

report scores without giving a winner yet

This method is a coroutine and needs to be awaited.

Parameters:

scores_csv – Comma separated set/game scores with player 1 score first (e.g. “1-3,3-0,3-2”)

Raises:
report_tie(scores_csv: str)

report tie if applicable (Round Robin and Swiss)

This method is a coroutine and needs to be awaited.

Parameters:scores_csv – Comma separated set/game scores with player 1 score first (e.g. “1-3,3-0,3-2”)
Raises:APIException
report_winner(winner: challonge.participant.Participant, scores_csv: str)

report scores and give a winner

This method is a coroutine and needs to be awaited.

Parameters:
  • winner – :class:Participant instance
  • scores_csv – Comma separated set/game scores with player 1 score first (e.g. “1-3,3-0,3-2”)
Raises:
round

readonly attribute

rushb_id

readonly attribute

scheduled_time

readonly attribute

scores_csv

readonly attribute

started_at

readonly attribute

state

readonly attribute

suggested_play_order

readonly attribute

tournament_id

readonly attribute

underway_at

readonly attribute

updated_at

readonly attribute

winner_id

readonly attribute

Attachment

class challonge.Attachment(connection, json_def, **kwargs)

representation of a Challonge match attachment

asset_content_type

readonly attribute

asset_file_name

readonly attribute

asset_file_size

readonly attribute

asset_url

readonly attribute

change_description(text: str)

change the text / description of that attachment

This method is a coroutine and needs to be awaited.

Parameters:

text – content you want to add / modify (description)

Raises:
change_file(file_path: str, description: str=None)

change the file of that attachment

This method is a coroutine and needs to be awaited.

Warning

This method has been tested but is not considered to be reliable, API-wise.

Parameters:
  • file_path – path to the file you want to add / modify
  • descriptionoptional description for your attachment
Raises:
change_text(text: str)

change the text / description of that attachment

This method is a coroutine and needs to be awaited.

Parameters:

text – content you want to add / modify (description)

Raises:
change_url(url: str, description: str=None)

change the url of that attachment

This method is a coroutine and needs to be awaited.

Parameters:
  • url – url you want to change
  • descriptionoptional description for your attachment
Raises:
created_at

readonly attribute

description

readonly attribute

id

readonly attribute

match_id

readonly attribute

original_file_name

readonly attribute

updated_at

readonly attribute

url

readonly attribute

user_id

readonly attribute

Enums

class challonge.TournamentState

State a tournament can be in

pending = <TournamentState.pending: 'pending'>
open_ = <TournamentState.open_: 'open'>

can’t use open

complete = <TournamentState.complete: 'complete'>
in_progress = <TournamentState.in_progress: 'in progress'>
class challonge.TournamentType

Type of a tournament

single_elimination = <TournamentType.single_elimination: 'single elimination'>
double_elimination = <TournamentType.double_elimination: 'double elimination'>
round_robin = <TournamentType.round_robin: 'round robin'>
swiss = <TournamentType.swiss: 'swiss'>
class challonge.TournamentStateResult

State given from the Challonge API. Can be different from TournamentState

underway = <TournamentStateResult.underway: 0>
pending = <TournamentStateResult.pending: 1>
class challonge.DoubleEliminationEnding

Type of ending for double elimination tournaments

default = <DoubleEliminationEnding.default: None>

give the winners bracket finalist two chances to beat the losers bracket finalist

single_match = <DoubleEliminationEnding.single_match: 'single_match'>

create only one grand finals match

no_grand_finals = <DoubleEliminationEnding.no_grand_finals: 'skip'>

don’t create a finals match between winners and losers bracket finalists

class challonge.RankingOrder

Order the ranking should be built upon

match_wins = <RankingOrder.match_wins: 'match wins'>
game_wins = <RankingOrder.game_wins: 'game wins'>
points_scored = <RankingOrder.points_scored: 'points scored'>
points_difference = <RankingOrder.points_difference: 'points difference'>
custom = <RankingOrder.custom: 'custom'>
class challonge.Pairing

Method of participant pairing when building matches

seeds = <Pairing.seeds: 0>
sequential = <Pairing.sequential: 1>
class challonge.MatchState

State a match can be in

all_ = <MatchState.all_: 'all'>

can’t use all

open_ = <MatchState.open_: 'open'>

can’t use open

pending = <MatchState.pending: 'pending'>
complete = <MatchState.complete: 'complete'>

Exceptions

class challonge.APIException

If anything goes wrong during a request to the Challonge API, this exception will be raised.