powerchallonge 1.0.4

challonge.com API client

powerchallonge is a client libary for the Challonge.com API.

All the API Methods are supported.

Contents

• Python version compatibility

• Dependencies

• Installation

• Basic usage

• Known Issues

• Running the tests

• Advanced usage

  • Passing parameters

  • Advanced user settings

  • Convert xml and json files to params

  • API Methods examples list

    • Tournaments

    • Participants

    • Matches

    • Match Attachments

Python version compatibility

• 2.7

• 3.3+

Dependencies

• requests

Installation

pip install powerchallonge

Basic usage

import challonge

#Configure your settings
api_key = 'YOURCHALLONGEAPIKEY'
challonge.set_user_settings(api_key)


#Retrieve a set of tournaments created with your account as a Python list of dictionaries
tournaments = challonge.tournaments.index()
for tournament in tournaments:
    print(tournament['name'], tournament['id'])

#Retrieve a single tournamentas a Python dictionnary using it's id or challonge like url
tournament = challonge.tournaments.show(1234)
print(tournament['name'], tournament['game_name'])

Known Issues

• After a participant is checked in using participants.check_in(), the ‘checked_in’ field remains False but the participant is properly checked in on the site

• This problem doesn’t appear for the participants.undo_check_in(), the field is properly set from True to False when using it

• Challonge API returns error 500 when Creatin/Updating a match_attachment asset

• When using match_attachments.update(), the updated field does not seem to get changed when doing a verification with match_attachments.show(), however the update is effective and shows up correctly on the site

All these issues have been reported to challonge.

Running the tests

The tests/tests.py script verifies functionality for all the API Methods (except the ones with known issues) and powerchallonge specific functions such as settings configuring and both json and xml conversion functions.

How to run the tests:

• Set a CHALLONGE_API_KEY environment variable

• From the repository’s root directory

python -m unittest discover -s tests -p "tests.py" -v

Advanced usage

Passing parameters

Some methods only have positional arguments, some require the keyword argument ‘params’

params should be a dictionnary of the parameters you intend to use in the method.

myparams = {'subdomain': my_subdomain}
subdomain_tournaments = challonge.tournaments.index(params=myparams)

myparams2 = {'name': 'tournament1', 'url': 'tournament123123129032901'}
tournament1 = challonge.tournaments.create(params=myparams2)

Advanced user settings

By default, you only need your api key and the set_user_settings() function to use powerchallonge.

You can use set_user_settings_advanced() for more customization

The variables below are the default settings if set_user_settings_advanced() isn’t called.

api_key = "YOURCHALLONGEAPIKEY"  # Your Challonge API key

easy_tournament_identifier = False
# True to use full URLs for referring to tournaments
# instead of challonge like URLs.
# false to use regular challonge API like URLs.

query_type = ".json"
# The desired response expected from the challonge API, '.json' or '.xml'

raw_response = False
# The desired response, False for python like objects : lists, dictionnaries.
# True for raw response from the API in the form of a Requests Response Object
# http://docs.python-requests.org/en/master/api/#requests.Response

#Apply the settings
challonge.set_user_settings_advanced(api_key, easy_tournament_identifier,
                                     query_type,
                                     raw_response, verbose_level, test_mode)

Convert xml and json files to params

powerchallonge comes with tools to convert json or xml files to a dictionnary that can be used agument in the API methods. This allows the user to create custom templates for specific tournaments and save them as .json or .xml and load them easily.

the functions only supports single parent type json/xml files the childs will be the key:elements in the dictionnary

myparams = challonge.json_to_params(path_to_json_file)
myparams = challonge.xml_to_params(path_to_xml_file)

Elements are always processed as strings or booleans, if you want an element to be a list (only interesting in the case of participants.bulk_add() ) use the following in your xml file :

<name type='list'>player1,player2,player3</name>

API Methods examples list

If raw_response is set to False (default), the output for any API method used will be a Python object.

If raw response is set to True, the output for any API method used will be a requests response object.

Tournaments

Tournaments : Index.

# params argument is optional
r = challonge.tournaments.index()
print(r)  # a list of dictionaries of attributes (one dictionary per tournament)

Tournaments : Create.

# params argument is optional but necessary (challonge error later on if missing)
myparams = {'name': 'mytournament123123', 'url': 'mytournament123123'}
myparams['start_at']="2020/02/16T17:00:00+00:00"
#If you don't set an offset ("+00:00" above), the hour will be inconsistent
#Always set your start_time to UTC+your_zone_offset
r = challonge.tournaments.create(params=myparams)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Show.

# params argument is optional
r = challonge.tournaments.show(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Update.

# params argument is optional but necessary (challonge error later on if missing)
myparams{'description': 'new_description'}
r = challonge.tournaments.update(identifier, params=myparams)
print(r)  # a dictionary of the attributes of tournament

Tournaments : Destroy.

# no params argument required
r = challonge.tournaments.destroy(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Process Check-ins.

# params argument is optional
r = challonge.tournaments.process_check_ins(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Abort Check-in.

# params argument is optional
r = challonge.tournaments.abort_check_ins(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Start.

# params argument is optional
r = challonge.tournaments.start(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Finalize.

# params argument is optional
r = challonge.tournaments.finalize(identifier)
print(r)  # a dictionary of the attributes of the tournament

Tournaments : Reset.

Participants

# params argument is optional
r = challonge.tournaments.reset(identifier)
print(r)  # a dictionary of the attributes of the tournament

Participants : index.

# params argument is optional
r = challonge.participants.index(identifier)
print(r)  # a list of dictionnaries of attributes (one dictionnary per participant)

Participants : Create.

# params argument is optional but necessary (challonge error later on if missing)
myparams = {'name': 'player1'}
r = challonge.participants.create(identifier, params=myparams)
print(r)  # a dictionary of the attributes of the participant

Participants : Bulk-Add.

# params argument is optional but necessary (challonge error later on if missing)
# For the bulk_add to work, the 'name' field of params must be a list of the names
myparams = {'name': ['player1', 'player2', 'player3']}
r = challonge.participants.bulk_add(identifier, params=myparams)
print(r)  # a list of dictionnaries of attributes (one dictionnary per added participant)

Participants : Show.

# params argument is optional
r = challonge.participants.show(identifier, participant_id)
print(r)  # a dictionary of the attributes of the participant

Participants : Update.

# params argument is optional but necessary (challonge error later on if missing)
myparams = {'name': 'player1_update'}
r = challonge.participants.update(identifier, participant_id, params=myparams)
print(r)  # a dictionary of the attributes of the participant

Participants : Check-in.

# no params argument required
r = challonge.participants.check_in(identifier, participant_id)
print(r)  # a dictionary of the attributes of the participant
#The participant is properly checked-in on the site
#But the 'checked_in' field will still be set to False, check Known Issues

Participants : Undo Check In.

# no params argument required
r = challonge.participants.undo_check_in(identifier, participant_id)
print(r)  # a dictionary of the attributes of the participant

Participants : Destroy.

# no params argument required
r = challonge.participants.destroy(identifier, participant_id)
print(r)  # a dictionary of the attributes of the participant

Participants : Randomize.

# no params argument required
r = challonge.participants.randomize(identifier)
print(r)  # a list of dictionnaries of attributes (one dictionary per participant)

Matches

Matches : Index.

# params argument is optional
r = challonge.matches.index(identifier)
print(r)  # a list of dictionaries of attributes (one dictionary per match)

Matches : Show.

# params argument is optional
r = challonge.matches.show(identifier, match_id)
print(r)  # a dictionary of the attributes of the match

Matches : Update.

# params argument is optional but necessary (challonge error later on if missing)
myparams = {'scores_csv': '1-0'}
r = challonge.matches.update(identifier, match_id, params=myparams)
print(r)  # a dictionary of the attributes of the match

Matches : Reopen.

# no params argument required
r = challonge.matches.reopen(identifier, match_id)
print(r)  # a dictionary of the attributes of the match

Match Attachments : Index.

# no params argument required
r = challonge.match_attachments.index(identifier, match_id)
print(r)  # a list of dictionaries of attributes (one dictionary per match attachment)

Match Attachments

Match Attachments : Create.

#Doesn't work if asset is a file (Error 500, check known issues)
# params argument is optional but necessary (challonge error later on if missing)
myparams = {'description': 'description'}
r = challonge.match_attachments.create(identifier, match_id, params=myparams)
print(r)  # a dictionary of the attributes of the match attachment

Match Attachments : Show.

# no params argument required
r = challonge.match_attachments.show(identifier, match_id, attachment_id)
print(r)  # a dictionary of the attributes of the match attachment

Match Attachments : Update.

# params argument is optional but necessary (challonge error later on if missing)
myparams = {'description': 'new_description'}
r = challonge.match_attachments.update(identifier, match_id, attachment_id, params)
print(r)  # a dictionary of the attributes of the match attachment
#the updated field does not seem to get changed when doing a verification
#with match_attachments.show(),
#however the update is effective and shows up correctly on the site

Match Attachments : Destroy.

# no params argument required
r = challonge.match_attachments.destroy(identifier, match_id, attachment_id)
print(r)  # a dictionary of the attributes of the match attachment