achallonge

async challonge for python 3.5+!

Features

  • More than a just a wrapper to the Challonge API

  • Natural structures to work with (User, Tournament, Participant, Match, Attachment)

  • No knowledge of the Challonge API is required, thanks to extensively documented library

Getting Started

Simple example:

import asyncio

import challonge


my_username = 'challonge_username'
my_api_key = 'challonge_api_key'


async def main(loop):
    my_user = await challonge.get_user(my_username, my_api_key)
    my_tournaments = await my_user.get_tournaments()
    for t in my_tournaments:
        print(t.name, t.full_challonge_url)


if __name__ == '__main__':
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

Dependencies

  • python 3.5+

  • aiohttp
    • cchardet

    • aiodns

Author and License

The achallonge package is written by Fabien Poupineau (fp12).

It’s distributed under the MIT license.

Feel free to improve this package and send a pull request to GitHub.

API

User

async 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.

async validate()

checks whether the current user is connected

This method is a coroutine and needs to be awaited.

Raises

APIException

async get_tournament(t_id: Optional[int] = None, url: Optional[str] = None, subdomain: Optional[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

async get_tournaments(subdomain: Optional[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

async 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

async 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

Tournament

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

Representation of a Challonge tournament

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async set_start_date(date: str, time: str, check_in_duration: Optional[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

async 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

async 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

async setup_swiss_points(match_win: Optional[float] = None, match_tie: Optional[float] = None, game_win: Optional[float] = None, game_tie: Optional[float] = None, bye: Optional[float] = None)

This method is a coroutine and needs to be awaited.

Parameters
  • match_win

  • match_tie

  • game_win

  • game_tie

  • bye

Raises

APIException

async 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

async setup_round_robin_points(match_win: Optional[float] = None, match_tie: Optional[float] = None, game_win: Optional[float] = None, game_tie: Optional[float] = None)

This method is a coroutine and needs to be awaited.

Parameters
  • match_win

  • match_tie

  • game_win

  • game_tie

Raises

APIException

async update_notifications(on_match_open: Optional[bool] = None, on_tournament_end: Optional[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

async 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

async 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

async update_ranking_order(order: challonge.enums.RankingOrder)

This method is a coroutine and needs to be awaited.

Parameters

order – see RankingOrder

Raises

APIException

async update_website_options(hide_forum: Optional[bool] = None, show_rounds: Optional[bool] = None, open_signup: Optional[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

async update_pairing_method(pairing: challonge.enums.Pairing)

This method is a coroutine and needs to be awaited.

Parameters

pairing

Raises

APIException

async 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

async 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

async 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

async add_participant(display_name: Optional[str] = None, username: Optional[str] = None, email: Optional[str] = None, seed: int = 0, misc: Optional[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

async 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

async 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

async 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

async 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

async shuffle_participants()

Shuffle participants’ seeds

This method is a coroutine and needs to be awaited.

Note

From Challonge API: Randomize seeds among participants. Only applicable before a tournament has started.

Raises

APIException

async 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

async 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

async get_final_ranking()collections.OrderedDict

Get the ordered players ranking

Returns

Return type

collections.OrderedDict[rank, List[Participant]]

Raises

APIException

start_at

readonly attribute

category

readonly attribute

locked_at

readonly attribute

signup_cap

readonly attribute

accept_attachments

readonly attribute

open_signup

readonly attribute

rr_pts_for_match_win

readonly attribute

created_by_api

readonly attribute

game_id

readonly attribute

teams

readonly attribute

participants_count

readonly attribute

group_stages_enabled

readonly attribute

anonymous_voting

readonly attribute

started_at

readonly attribute

pts_for_match_win

readonly attribute

event_id

readonly attribute

require_score_agreement

readonly attribute

pts_for_game_win

readonly attribute

predict_the_losers_bracket

readonly attribute

completed_at

readonly attribute

predictions_opened_at

readonly attribute

description_source

readonly attribute

ranked_by

readonly attribute

pts_for_bye

readonly attribute

description

readonly attribute

rr_pts_for_game_tie

readonly attribute

id

readonly attribute

rr_pts_for_game_win

readonly attribute

check_in_duration

readonly attribute

private

readonly attribute

swiss_rounds

readonly attribute

quick_advance

readonly attribute

participants_swappable

readonly attribute

progress_meter

readonly attribute

live_image_url

readonly attribute

tournament_type

readonly attribute

started_checking_in_at

readonly attribute

pts_for_game_tie

readonly attribute

prediction_method

readonly attribute

participants_locked

readonly attribute

hide_seeds

readonly attribute

name

readonly attribute

public_predictions_before_start_time

readonly attribute

sign_up_url

readonly attribute

game_name

readonly attribute

review_before_finalizing

readonly attribute

max_predictions_per_user

readonly attribute

tie_breaks

readonly attribute

url

readonly attribute

rr_pts_for_match_tie

readonly attribute

notify_users_when_matches_open

readonly attribute

hide_forum

readonly attribute

grand_finals_modifier

readonly attribute

notify_users_when_the_tournament_ends

readonly attribute

sequential_pairings

readonly attribute

credit_capped

readonly attribute

ranked

readonly attribute

team_convertable

readonly attribute

accepting_predictions

readonly attribute

allow_participant_match_reporting

readonly attribute

state

readonly attribute

show_rounds

readonly attribute

hold_third_place_match

readonly attribute

updated_at

readonly attribute

subdomain

readonly attribute

created_at

readonly attribute

pts_for_match_tie

readonly attribute

group_stages_were_started

readonly attribute

full_challonge_url

readonly attribute

Participant

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

Representation of a Challonge participant

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

can_check_in

readonly attribute

challonge_email_address_verified

readonly attribute

seed

readonly attribute

group_id

readonly attribute

active

readonly attribute

tournament_id

readonly attribute

name

readonly attribute

icon

readonly attribute

checked_in

readonly attribute

updated_at

readonly attribute

reactivatable

readonly attribute

invite_email

readonly attribute

display_name_with_invitation_email_address

readonly attribute

username

readonly attribute

invitation_id

readonly attribute

removable

readonly attribute

on_waiting_list

readonly attribute

id

readonly attribute

final_rank

readonly attribute

misc

readonly attribute

challonge_username

readonly attribute

invitation_pending

readonly attribute

checked_in_at

readonly attribute

group_player_ids

readonly attribute

confirm_remove

readonly attribute

participatable_or_invitation_attached

readonly attribute

attached_participatable_portrait_url

readonly attribute

created_at

readonly attribute

display_name

readonly attribute

email_hash

readonly attribute

Match

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

Representation of a Challonge match

async 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
  • ValueError – scores_csv has a wrong format

  • APIException

async 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
  • ValueError – scores_csv has a wrong format

  • APIException

async 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

async 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

async mark_as_underway()

Marks the match as underway

This method is a coroutine and needs to be awaited.

Raises

APIException

async unmark_as_underway()

Unmarks the match as underway

This method is a coroutine and needs to be awaited.

Raises

APIException

async change_votes(player1_votes: Optional[int] = None, player2_votes: Optional[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

async attach_file(file_path: str, description: Optional[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
  • ValueError – file_path must not be None

  • APIException

async attach_url(url: str, description: Optional[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
async 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
async 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

winner_id

readonly attribute

player1_is_prereq_match_loser

readonly attribute

completed_at

readonly attribute

group_id

readonly attribute

scores_csv

readonly attribute

player2_id

readonly attribute

tournament_id

readonly attribute

player2_is_prereq_match_loser

readonly attribute

started_at

readonly attribute

player1_prereq_match_id

readonly attribute

rushb_id

readonly attribute

location

readonly attribute

optional

readonly attribute

loser_id

readonly attribute

attachment_count

readonly attribute

round

readonly attribute

player2_prereq_match_id

readonly attribute

player2_votes

readonly attribute

identifier

readonly attribute

scheduled_time

readonly attribute

suggested_play_order

readonly attribute

id

readonly attribute

state

readonly attribute

updated_at

readonly attribute

prerequisite_match_ids_csv

readonly attribute

created_at

readonly attribute

player1_votes

readonly attribute

has_attachment

readonly attribute

underway_at

readonly attribute

player1_id

readonly attribute

Attachment

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

representation of a Challonge match attachment

async change_url(url: str, description: Optional[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
async 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
async 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
async change_file(file_path: str, description: Optional[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
  • ValueError – file_path must not be None

  • APIException

id

readonly attribute

user_id

readonly attribute

asset_url

readonly attribute

asset_file_name

readonly attribute

url

readonly attribute

asset_file_size

readonly attribute

description

readonly attribute

updated_at

readonly attribute

match_id

readonly attribute

created_at

readonly attribute

original_file_name

readonly attribute

asset_content_type

readonly attribute

Enums

class challonge.TournamentState(value)

State a tournament can be in

pending = 'pending'
open_ = 'open'

can’t use open

complete = 'complete'
in_progress = 'in progress'
class challonge.TournamentType(value)

Type of a tournament

single_elimination = 'single elimination'
double_elimination = 'double elimination'
round_robin = 'round robin'
swiss = 'swiss'
class challonge.TournamentStateResult(value)

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

underway = 0
pending = 1
class challonge.DoubleEliminationEnding(value)

Type of ending for double elimination tournaments

default = None

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

single_match = 'single_match'

create only one grand finals match

no_grand_finals = 'skip'

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

class challonge.RankingOrder(value)

Order the ranking should be built upon

match_wins = 'match wins'
game_wins = 'game wins'
points_scored = 'points scored'
points_difference = 'points difference'
custom = 'custom'
class challonge.Pairing(value)

Method of participant pairing when building matches

seeds = 0
sequential = 1
class challonge.MatchState(value)

State a match can be in

all_ = 'all'

can’t use all

open_ = 'open'

can’t use open

pending = 'pending'
complete = 'complete'

Exceptions

class challonge.APIException

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

Examples

Simple list of tournaments

Let’s fetch and print all names and url of the organizer’s tournaments

import asyncio

import challonge


my_username = 'challonge_username'
my_api_key = 'challonge_api_key'


async def main(loop):
    my_user = await challonge.get_user(my_username, my_api_key)
    my_tournaments = await my_user.get_tournaments()
    for t in my_tournaments:
        print(t.name, t.full_challonge_url)


if __name__ == '__main__':
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

Simple creation of a tournament

import asyncio

import challonge


my_username = 'challonge_username'
my_api_key = 'challonge_api_key'


async def main(loop):
    my_user = await challonge.get_user(my_username, my_api_key)
    new_tournament = await my_user.create_tournament(name='my super tournament',
                                                     url='super-tournament-url')

    john = await new_tournament.add_participant('john')
    bob = await new_tournament.add_participant('bob')
    steve = await new_tournament.add_participant('steve')
    franck = await new_tournament.add_participant('franck')
    # or simply new_tournament.add_participants('john', 'bob', 'steve', 'franck')

    await new_tournament.start()

    matches = await new_tournament.get_matches()

    # match 1: john (p1) Vs bob (p2)
    await matches[0].report_winner(john, '2-0,1-2,2-1')
    # match 2: steve (p1) Vs franck (p2)
    await matches[1].report_winner(franck, '2-0,1-2,0-2')

    # finals: john (p1) Vs franck (p2)
    await matches[2].report_winner(franck, '2-1,0-2,1-2')

    await new_tournament.finalize()


if __name__ == '__main__':
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main(loop))

Indices and tables