Tournaments

API Reference

Base

Tournament

class tournaments.objects.Tournament(bot: Red, guild: Guild, config: Config, custom_config: str, name: str, game: str, url: str, id: str, limit: int | None, status: str, tournament_start: datetime, bot_prefix: str, cog_version: str, data: dict)[source]

Bases: object

Represents a tournament in a guild.

This object is created as soon as the tournament is setup, and destroyed only once it ends.

The config is loaded inside and will not be updated unless reloaded.

This contains all of the methods useful for the tournament, a list of Participant and a list of Match, and a discord.ext.tasks.Loop task updating the infos from the bracket.

This contains the base structure, but no interface with a bracket, this has to be implemented later by inheriting from this class and overwriting the abstract methods, allowing multiple providers to work with the same structure.

If you’re implementing this for a new provider, the following methods need to be implemented:

And set the following class vars with your other inherited objects for Participant and Match :

See challonge.py for an example.

Parameters:

  • bot (redbot.core.bot.Red) – The bot object

  • guild (discord.Guild) – The current guild for the tournament

  • config (redbot.core.Config) – The cog’s Config object

  • name (str) – Name of the tournament

  • game (str) – Name of the game

  • url (str) – Link of the bracket

  • id (str) – Internal ID for the tournament

  • limit (Optional[int]) – An optional limit of participants

  • status (str) – The status provided by the API

  • tournament_start (datetime.datetime) – Expected start time for this tournament. Planned events are based on this.

  • bot_prefix (str) – A prefix to use for displaying commands without context.

  • cog_version (str) – Current version of Tournaments

  • data (dict) – A dict with all the config required for the tournament (combines guild and game settings)

bot

The bot object

Type:

redbot.core.bot.Red

guild

The current guild for the tournament

Type:

discord.Guild

config

The cog’s Config object

Type:

redbot.core.Config

name

Name of the tournament

Type:

str

game

Name of the game

Type:

str

url

Link of the bracket

Type:

str

id

Internal ID for the tournament

Type:

str

limit

An optional limit of participants

Type:

Optional[int]

status

The status provided by the API

Type:

str

tournament_start

Expected start time for this tournament. Planned events are based on this.

Type:

datetime.datetime

tz

The timezone of the tournament. You need to use this when creating datetime objects.

from datetime import datetime
now = datetime.now(tz=tournament.tz)
Type:

datetime.tzinfo

bot_prefix

A prefix to use for displaying commands without context.

Type:

str

cog_version

Current version of Tournaments

Type:

str

participants

List of participants in the tournament

Type:

List[Participant]

matches

List of open matches in the tournament

Type:

List[Match]

streamers

List of streamers in the tournament

Type:

List[Streamer]

winner_categories

List of categories created for the winner bracket

Type:

List[discord.CategoryChannel]

loser_categories

List of categories created for the loser bracket

Type:

List[discord.CategoryChannel]

category

The category defined (our categories will be created below)

Type:

Optional[discord.CategoryChannel]

announcements_channel

The channel for announcements

Type:

Optional[discord.TextChannel]

checkin_channel

The channel for check-in

Type:

Optional[discord.TextChannel]

queue_channel

The channel for match queue

Type:

Optional[discord.TextChannel]

register_channel

The channel for registrations

Type:

Optional[discord.TextChannel]

scores_channel

The channel for score setting

Type:

Optional[discord.TextChannel]

stream_channel

The channel for announcing matches on stream

Type:

Optional[discord.TextChannel]

to_channel

The channel for tournament organizers. Send warnings there.

Type:

discord.TextChanne]

vip_register_channel

A channel where registrations are always open

Type:

Optional[discord.TextChannel]

participant_role

The role given to participants

Type:

discord.Role

streamer_role

Role giving access to stream commands

Type:

Optional[discord.Role]

to_role

Role giving access to T.O. commands

Type:

Optional[discord.Role]

credentials

Credentials for connecting to the bracket

Type:

dict

delay

Time in minutes until disqualifying a participant for AFK

Type:

int

time_until_warn

Represents the different warn times for duration

Type:

dict

autostop_register

Should the bot close registrations when it’s full?

Type:

bool

ignored_events

A list of events to ignore (checkin/register start/stop)

Type:

list

register_start

When we should open the registrations automatically

Type:

Optional[datetime.datetime]

register_second_start

When we should open the registrations a second time automatically

Type:

Optional[datetime.datetime]

register_stop

When we should close the registrations automatically

Type:

Optional[datetime.datetime]

checkin_start

When we should open the checkin automatically

Type:

Optional[datetime.datetime]

checkin_stop

When we should close the checkin automatically

Type:

Optional[datetime.datetime]

ruleset_channel

Channel for the rules

Type:

Optional[discord.TextChannel]

game_role

Role targeted at players for this game. Basically we use that role when opening the registrations, for opening the channel and pinging.

Type:

Optional[discord.Role]

baninfo

Baninfo set (ex: 3-4-2)

Type:

Optional[str]

ranking

Data for braacket ranking

Type:

dict

stages

List of allowed stages

Type:

List[str]

counterpicks

List of allowed counterpicks

Type:

List[str]

phase

Something very important! Used for knowing what is the current phase of the tournament. It is also used by commands to know if it is allowed to run.

Can be the following values:

  • "pending": Tournament just setup, nothing open yet

  • "register": Registrations or check-in started and are not finished

  • "awaiting": Registrations and check-in done, awaiting upload and start

  • "ongoing": Tournament is started and ongoing

  • "finished": Tournament done. Should be immediatly deleted unless there’s an issue

Type:

str

register_phase

Defines the current status of registration.

Can be the following values:

  • "manual": No start date setup, waiting for manual start

  • "pending": Start date setup, awaiting automatic start

  • "ongoing": Registrations active

  • "onhold": Registrations started and ended once, but awaiting a second start

  • "done": Registrations ended

Type:

str

checkin_phase

Defines the current status of check-in.

Can be the following values:

  • "manual": No start date setup, waiting for manual start

  • "pending": Start date setup, awaiting automatic start

  • "ongoing": Check-in active

  • "onhold": Check-in started and ended once, but awaiting a second start

  • "done": Check-in ended

Type:

str

register_message

The pinned message in the registrations channel

Type:

Optional[discord.Message]

checkin_reminders

A list of reminders to send for the check-in. Contains tuples of two items: when to send the reminder (minutes before check-in end date), and if the bot should DM members. This is calculated on check-in start.

Type:

List[Tuple[int, bool]]

lock

A lock acquired when the tournament is being refreshed by the loop task, to prevent commands like win or dq from being run at the same time.

New since beta 13: The lock is also acquired with the [p]in command to prevent too many concurrent tasks, breaking the limit.

Type:

asyncio.Lock

task

The task for the loop_task function (discord.ext.tasks.Loop object)

Type:

asyncio.Task

task_errors

Number of errors that occured within the loop task. If it reaches 5, task is cancelled.

Type:

int

top_8

Represents when the top 8 and bo5 begins in the bracket.

Type:

dict

matches_to_announce

A list of strings to announce in the defined queue channel. This is done to prevent sending too many messages at once and hitting ratelimits, so we wrap messages together.

Type:

List[str]

participant_object

alias of Participant

match_object

alias of Match

cancel()[source]

Correctly clears the object, stopping the task and removing ranking data.

classmethod await from_saved_data(bot: Red, guild: Guild, config: Config, cog_version: str, data: dict, config_data: dict)[source]

Loads a tournament from Config.

Due to Python’s weird behaviour, this method must be reimplemented and simply called back without changes.

to_dict() → dict[source]

Returns a dict ready for Config.

await save()[source]

Saves data with Config. This is done with the loop task during a tournament but must be called while it’s not ongoing.

property allowed_roles

Return a list of roles that should have access to the temporary channels.

next_scheduled_event() → Tuple[str, timedelta][source]

Returns the next scheduled event (register/checkin/None) with the corresponding timedelta

await warn_bracket_change(*sets)[source]

Warn T.O.s of a bracket change.

Parameters:

*sets (str) – The list of affected sets.

find_participant(*, player_id: str | None = None, discord_id: int | None = None, discord_name: str | None = None) → Tuple[int, Participant][source]

Find a participant in the internal cache, and returns its object and position in the list.

You need to provide only one of the parameters.

Parameters:

  • player_id (Optional[str]) – Player’s ID on the bracket, as returned by Participant.player_id

  • discord_id (Optional[int]) – Player’s Discord ID

  • discord_name (Optional[str], as returned by discord.Member.id) – Player’s full Discord name, as returned by str(discord.Member)

Returns:

The index of the participant in the list (useful for deletion or deplacement) and its Participant object

Return type:

Tuple[int, Participant]

Raises:

RuntimeError – No parameter was provided

find_match(*, match_id: int | None = None, match_set: int | None = None, channel_id: int | None = None) → Tuple[int, Match][source]

Find a match in the internal cache, and returns its object and position in the list.

You need to provide only one of the parameters.

Parameters:

  • match_id (Optional[int]) – Match’s ID on the bracket, as returned by Match.id

  • match_set (Optional[int]) – Match’s number, or suggested play order, on the bracket, as returned by Match.set

  • channel_id (Optional[id]) –

    Discord channel’s ID, as returned by discord.TextChannel.id

    Warning

    A match may not have a channel assigned

Returns:

The index of the match in the list (useful for deletion or deplacement) and its Match object

Return type:

Tuple[int, Match]

Raises:

RuntimeError – No parameter was provided

find_streamer(*, channel: str | None = None, discord_id: int | None = None) → Tuple[int, Streamer][source]

Find a streamer in the internal cache, and returns its object and position in the list.

You need to provide only one of the parameters.

Parameters:
Returns:

The index of the streamer in the list (useful for deletion or deplacement) and its Streamer object

Return type:

Tuple[int, Streamer]

Raises:

RuntimeError – No parameter was provided

await start_registration(second=False)[source]

Open the registrations and save.

Parameters:

second (bool) – If this is the second time registrations are started (will not annouce the same message, and keep updating the same pinned message). Defaults to False.

await end_registration()[source]

Close the registrations and save.

If the check-in is also done, participants will be seeded and uploaded.

Parameters:

background (bool) – If the function is called in a background loop. If True, the bot will do actions knowing there’s no context command (for now, means a background seed and upload). Defaults to False.

await start_check_in()[source]

Open the check-in and save.

This will also calculate and fill the checkin_reminders list.

await call_check_in(with_dm: bool = False)[source]

Pings participants that have not checked in yet.

Only works with a check-in channel setup and a stop time.

Parameters:

with_dm (bool) –

If the bot should DM unchecked members too. Defaults to False.

Caution

Prevent using this if there are too many unchecked members, as Discord started to ban bots sending too many DMs.

await end_checkin()[source]

Close the check-in, unregister unchecked members (attempts to DM) and save.

If the registrations are also done, participants will be seeded and uploaded.

Parameters:

background (bool) – If the function is called in a background loop. If True, the bot will do actions knowing there’s no context command (for now, means a background seed and upload). Defaults to False.

await register_participant(member: Member, send_dm: bool = True)[source]

Register a new participant to the tournament (add role) and save.

If the check-in has started, participant will be pre-checked.

If there is a limit of participants, the auto-stop setting for registrations is enabled and the limit is reached, registrations will be closed.

The Participant object is not returned and directly added to the list.

Parameters:

  • member (discord.Member) – The member to register. They must be in the server.

  • send_dm (bool) – If the bot should DM the new participant for their registrations. Defaults to True.

await unregister_participant(member: Member, send_dm: bool = True)[source]

Remove a participant.

If the player is uploaded on the bracket, they will also be removed from there. If the tournament has started, member will be disqualified instead.

This removes roles and DMs the participant.

Parameters:

member (discord.Member) – The member to disqualify

Raises:

KeyError – The member is not registered

await seed_participants(remove_unchecked: bool = False)[source]

Seed the participants if ranking info is configured.

Warning

If an exception occurs, the list of participants will be rolled back to its previous state, then the error propagates.

Parameters:

remove_unchecked (bool) – If unchecked members should be removed from the internal list and the upload. Defaults to False

await send_start_messages()[source]

Send the required messages when starting the tournament.

Depending on the configured channels, announcements will be sent in:

  • The announcements channel

  • The scores channel

  • The queue channel

await announce_sets()[source]

Wraps the messages stored in matches_to_announce and sends them in the queue_channel.

await launch_sets()[source]

Launch pending matches, creating a channel and marking the match as ongoing.

This only launches 20 matches max.

This is wrapped inside asyncio.gather, so errors will not propagate.

update_streamer_list()[source]

Update the internal streamer’s list (next stream attr)

await launch_streams()[source]

Launch the streams (call the next matches in the streamer’s queue).

You must call update_streamer_list first.

await check_for_channel_timeout()[source]

Look through the ongoing/finished matches and compare durations to see if AFK check or channel deletion is required, and proceed.

await check_for_too_long_matches()[source]

Look through the ongoing matches and verifies the duration. Warn if necessary.

loop_task

A discord.ext.tasks.Loop object, started with the tournament’s start and running each 15 seconds.

Does the required background stuff, such as updating the matches list, launch new matches, update streamers, check for AFK…

Running this will acquire our lock.

See the documentation on a Loop object for more details.

Warning

Use start_loop_task for starting the task, not Loop.start.

Raises:

asyncio.TimeoutError – Running the task took more than 30 seconds

await cancel_timeouts()[source]

Sometimes relaunching the bot after too long will result in a lot of DQs due to AFK checks, so this function will cancel all AFK checks for the matches that are going to have players DQed.

await start_loop_task()[source]

Starts the internal loop task.

This will check for possible leftovers and cancel any previous task matching our name within the current asyncio loop. We do not want duplicated tasks, as this will result in the worst nightmare (RIP DashDances #36 and Super Smash Bronol #46).

Then we try to prevent abusive disqualifications with cancel_timeouts. Oh and we also set a contextual locale for i18n, see redbot.core.i18n.set_contextual_locales_from_guild.

Finally, the task is started and given the name “Tournament {tournamet_id}”

stop_loop_task()[source]

Stops the loop task. This is preferred over discord.ext.tasks.Loop.cancel.

await _get_all_rounds() → List[int][source]

Return a list of all rounds in the bracket. This is used to determine the top 8.

This is a new method because our Match class will not be created without players, so we add this new method which only fetch what we need.

Returns:

The list of rounds.

Return type:

List[int]

await _update_participants_list()[source]

Updates the internal list of participants, checking for changes such as:

  • Player DQ/removal

  • New player added (pre game)

Warning

A name change on remote is considered as a player removal + addition. If the name doesn’t match any member, they will be rejected.

await _update_match_list()[source]

Updates the internal list of changes, checking for changes such as:

  • Score set manually

  • Score modified (if there are ongoing/finished sets beyond this match in the bracket, they will be reset)

  • Match reset (the set will be relaunched, ongoing/finished sets beyond this match in the bracket will be reset)

await start()[source]

Starts the tournament.

Raises:

RuntimeError – The tournament is already started.

await stop()[source]

Stops the tournament.

Raises:

RuntimeError – The tournament is already stopped or not started.

await add_participant(name: str, seed: int | None = None)[source]

Adds a participant to the tournament.

Parameters:

  • name (str) – The name of the participant

  • seed (int) – The participant’s new seed. Must be between 1 and the current number of participants (including the new record). Omit to place at the bottom.

await add_participants(participants: List[Participant] | None = None, force: bool = False) → int[source]

Adds a list of participants to the tournament, ordered as you want them to be seeded. The participants will have their Participant.player_id updated as needed.

Parameters:

  • participants (Optional[List[Participant]]) – The list of participants. The first element will be seeded 1. If not provided, will use the instance’s participants attribute instead.

  • force (bool) –

    If you want the bot to override the previous list of participants on the bracket. Defaults to False.

    • If set to True: All manually added participants and seeding will be lost, and the new list will be exactly the same as what’s provided. All player IDs will be modified.

    • If set to False: The bot will call list_participants and remove all elements from the list where the player ID is already inside the upstream list. Then we bulk add what’s remaining, without clearing the rest.

      Participants are still seeded, but at the end, separated from the rest.

Returns:

How many members were appended to the list. Can be useful for knowing if the bot appended participants or if it was an initial upload (or forced).

Return type:

int

Raises:

RuntimeError – The list of participants provided was empty, or there was nothing new to upload.

await destroy_player(player_id: str)[source]

Destroys a player. This is the same call as Player.destroy, but only the player ID is needed. Useful for unavailable discord member.

Parameters:

player_id (str) – The player to remove.

await list_participants() → List[Participant][source]

Returns the list of participants from the tournament host.

Returns:

The list of participants.

Return type:

List[str]

await list_matches() → List[Match][source]

Returns the list of matches from the tournament host.

Returns:

The list of matches.

Return type:

List[str]

await reset()[source]

Resets the bracket.

Participant

class tournaments.objects.Participant(member: Member, tournament: Tournament)[source]

Bases: Member

Defines a participant in the tournament.

This inherits from discord.Member and adds the necessary additional methods.

If you’re implementing this for a new provider, the following methods need to be implemented:

Parameters:

  • member (discord.Member) – The member participating to the tournament

  • tournament (Tournament) – The current tournament

member

The member participating to the tournament

Type:

discord.Member

tournament

The current tournament

Type:

Tournament

elo

An integer representing the player’s elo (seeding from braacket)

Type:

int

checked_in

Defines if the member checked in

Type:

bool

match

The player’s current match. None if not in game.

Type:

Optional[Match]

spoke

Defines if the member spoke once in their channel (used for AFK check)

Type:

bool

reset()[source]

Resets the match attribute to None and spoke to False (match ended).

await check(send_dm: bool = True)[source]

Checks the member in.

In addition to changing the checked_in attribute, it also DMs the member and saves the config.

property player_id

Returns an identifier for the player, specific to the bracket.

This should be overwritten.

await destroy()[source]

Removes the participant from the tournament.

Represents an API call and should be overwritten.

Match

class tournaments.objects.Match(tournament: Tournament, round: int, set: str, id: int, underway: bool, player1: Participant, player2: Participant)[source]

Bases: object

Defines a match in the tournament, with two players facing each other.

This should only be created when convenient, aka when a match needs to be started. Matches with no players yet or finished are not builded.

If you’re implementing this for a new provider, the following methods need to be implemented:

Parameters:

  • tournament (Tournament) – The match’s tournament.

  • round (str) – The round of this match in the bracket (e.g. 1 for first round of winner bracket, -1 for first round of loser bracket).

  • set (str) – The number of the match. Challonge calls this the suggested play order (goes from 1 to N, the number of matches in the bracket).

  • id (int) – A unique identifier for the API

  • underway (bool) – If the match is underway (provided by API)

  • player1 (Participant) – The first player of this match.

  • player2 (Participant) – The second player of this match.

tournament

The match’s tournament.

Type:

Tournament

round

The round of this match in the bracket (e.g. 1 for first round of winner bracket, -1 for first round of loser bracket).

Type:

str

set

The number of the match. Challonge calls this the suggested play order (goes from 1 to N, the number of matches in the bracket).

Type:

str

id

A unique identifier for the API

Type:

int

player1

The first player of this match.

Type:

Participant

player2

The second player of this match.

Type:

Participant

channel

The channel for this match. May be None if the match hasn’t started yet, or if it couldn’t be created and is therefore in DM.

Type:

Optional[discord.TextChannel]

start_time

Start time of this match. None if it hasn’t started yet.

Type:

Optional[datetime]

end_time

End time of this match, or time of the latest message. None if it hasn’t started or ended yet. This is updated as soon as a message is sent in the channel. Used for knowing when to delete the channel (5 min after last message).

Type:

Optional[datetime]

status

Defines the current state of the match.

  • "pending": Waiting to be launched (no channel or stream pending)

  • "ongoing": Match started

  • "finished": Score set, awaiting channel deletion

Type:

str

warned

Defines if there was a warn for duration. None if no warn was sent, datetime.datetime if there was one first warn sent (correspond to the time when it was send, we rely on that to know when to send the second warn), and finally True when the second warn is sent (to the T.O.s).

Type:

Optional[Union[datetime, bool]]

streamer

The streamer assigned to this match, if any.

Type:

Optional[Streamer]

on_hold

True if the match is not started but on hold, awaiting something (most likely inside a stream queue, waiting for its turn)

Type:

bool

is_top8

True if the match is in the top 8 of the tournament

Type:

bool

is_bo5

True if the match is in BO5 format instead of BO3

Type:

bool

round_name

Name of the round (ex: Winner semi-finals, Loser round -2)

Type:

str

checked_dq

If we performed AFK checks. Setting this to True is possible and will disable further AFK checks for this match.

Type:

bool

property duration: timedelta | None

Returns the duration of this match, or None if it hasn’t started.

await send_message(reset: bool = False) → bool[source]

Send a message in the created channel.

Parameters:

reset (bool) – True if the match is started because of a reset.

Returns:

False if the message couldn’t be sent, and was sent in DM instead.

Return type:

bool

await start_stream()[source]

Send a pending set, awaiting for its turn, on stream. Only call this if there’s a streamer.

await stream_queue_add()[source]

Modify the status of an ongoing match to tell that it is now on stream.

This is called when a streamer adds an ongoing match to its queue, then the following things are done:

  • AFK checks are cancelled

  • If the match is the first one in the stream queue: Nothing is cancelled, we just ping the players with the stream informations.

  • If the match is not the first one in the stream queue: We mark the match as not underway, change the status to pending, and tell the players.

await cancel_stream()[source]

Call if the stream is cancelled (streamer left of match removed from queue).

A message will be sent, telling players to start playing, and AFK checks will be re-enabled.

await create_channel(category: CategoryChannel, *allowed_roles: list) → TextChannel[source]

Creates a channel for the match and returns its object.

Returns:

The created text channel

Return type:

discord.TextChannel

await launch(*, category: CategoryChannel | None = None, restart: bool = False, allowed_roles: List[Role] = [])[source]

Launches the set.

This does the following:

  • Try to create a text channel with permissions for the two players and the given roles

  • Send a DM to both members

  • Mark the set as ongoing

Parameters:

  • category (Optional[discord.CategoryChannel]) – The category where to put the channel. If this is not provided, one will be found. If you’re launching multiple sets at once with asyncio.gather, use this to prevent seeing one category per channel

  • restart (bool) – If the match is restarted.

  • allowed_roles (List[discord.Role]) – A list of roles with read_messages permission in the text channel.

await relaunch()[source]

This is called in case of a match reset (usually from remote).

We inform the players they need to play their set again, eventually re-use their old channel if it still exists.

await check_inactive()[source]

Checks for inactive players (reads Participant.spoke only), and DQ them if required.

Warning

This doesn’t check durations and assumes it’s been done already.

Will set checked_dq to True.

await warn_length()[source]

Warn players in their channels because of the duration of their match.

await warn_to_length()[source]

Warn T.O.s because of the duration of this match. Also tell the players

await end(player1_score: int, player2_score: int, upload: bool = True)[source]

Set the score and end the match.

The winner is determined by comparing the two scores (defaults to player 1 if equal).

Parameters:

  • player1_score (int) – First player’s score.

  • player2_score (int) – Second player’s score.

  • upload (bool) – If the score should be uploaded to the bracket. Set False to only send the message with a note “score set on bracket” added. Defaults to True.

await force_end()[source]

Called when a set is cancelled (remove bracket modifications or reset).

The channel is deleted, a DM is sent, and the instance will most likely be deleted soon after.

await disqualify(player: Participant | int)[source]

Called when a player in the set is destroyed.

There is no API call, just messages sent to the players.

player: Union[Participant, int]

The disqualified player. Provide an int if the member left.

await forfeit(player: Participant)[source]

Called when a player in the set forfeits this match.

This doesn’t always mean that the player quits the tournament, as they may continue in the loser bracket.

Sets a score of -1 0

Parameters:

player (Participant) – The player that forfeits.

cancel()[source]

Mark a match as finished (updated status and end_time + calls Participant.reset)

await set_scores(player1_score: int, player2_score: int, winner: Participant | None = None)[source]

Set the score for the set.

Parameters:

  • player1_score (int) – The score of the first player.

  • player2_score (int) – The score of the second player.

  • winner (Optional[Participant]) – The winner of the set. If not provided, the player with the highest score will be selected.

await mark_as_underway()[source]

Marks the match as underway.

await unmark_as_underway()[source]

Unmarks the match as underway.

This shouldn’t ever be needed, just here in case of.

Streamer

class tournaments.objects.Streamer(tournament: Tournament, member: Member, channel: str, respect_order: bool = False)[source]

Bases: object

Represents a streamer in the tournament. Will be assigned to matches. Does not necessarily exists on remote depending on the provider.

There is no API call in this class for now.

Parameters:

  • tournament (Tournament) – The current tournament

  • member (discord.Member) – The streamer on Discord. Must be in the tournament’s guild.

  • channel (str) – The streamer’s channel. Must only be the last part of the URL, not full. (e.g. for https://twitch.tv/el_laggron use channel="el laggron")

tournament

The current tournament

Type:

Tournament

member

The streamer on Discord. Must be in the tournament’s guild.

Type:

discord.Member

channel

The streamer’s channel. Must only be the last part of the URL, not full. (e.g. for https://twitch.tv/el_laggron use channel="el laggron")

Type:

str

The streamer’s full channel URL

Type:

str

room_id

Streamer’s room ID, specific to Smash Bros.

Type:

str

room_code

Streamer’s room code, specific to Smash Bros.

Type:

str

matches

The list of matches in the streamer’s queue. Can be Match if it exists (both players available, on hold) or int, representing the set.

Type:

List[Union[Match, int]]

current_match

The streamer’s current match.

Type:

Optional[Match]

get_set(x)[source]

Return the set number of a match in the streamer’s queue. Accepts Match or int.

Parameters:

x (Union[Match, int]) – The match you need

set_room(room_id: str, code: str | None = None)[source]

Set streamer’s room info (specific to Smash Bros.)

Parameters:

  • room_id (str) – Streamer’s room ID

  • code (Optional[str]) – Streamer’s room code

await check_integrity(sets: int, *, add: bool = False)[source]

Verify if the list of sets provided is valid before adding them to the list.

Parameters:

  • sets (int) – The list of sets you want to check (and add). Only int, no Match instance.

  • add (bool) – If you want to add the valid sets to the queue at the same time.

Returns:

A dictionnary of the errors that occured (set -> translated error msg). If this is empty, it’s all good.

Return type:

dict

await add_matches(*sets)[source]

Add matches to the streamer’s queue.

Parameters:

*sets (Union[Match, int]) – The matches you want to add.

await remove_matches(*sets: int)[source]

Remove a list of matches from the streamer’s queue.

Parameters:

*sets (int) – The list of sets you want to remove. Only int, no Match instance.

Raises:

KeyError – The list was unchanged.

swap_match(set1: int, set2: int)[source]

Swap the position of two matches in the streamer’s queue.

Parameters:

  • set1 (int) – The first set.

  • set2 (int) – The second set.

Raises:

KeyError – One or more sets not found

insert_match(set: int, *, set2: int | None = None, position: int | None = None)[source]

Insert a match in the list. The match must already exist in the list.

Provide either set2 or position as keyword argument.

Parameters:

  • set (int) – The set you want to move. Only int type, not Match.

  • set2 (int) – The set you want to use to define the position. Only int type, not Match.

  • position (int) –

    The new position in the list. 0 = first ; 1 = second …

    Providing a number out of bounds will move the item at the limit, it’s just Python’s magic. (eg: -5 moves to first place)

Raises:
await end()[source]

Cancels all streams for the streamer’s queue, telling the players.

Basically calls Match.cancel_stream for existing matches.

Challonge API

class tournaments.objects.ChallongeTournament(bot: Red, guild: Guild, config: Config, custom_config: str, name: str, game: str, url: str, id: str, limit: int | None, status: str, tournament_start: datetime, bot_prefix: str, cog_version: str, data: dict)[source]

Bases: Tournament

classmethod build_from_api(bot: Red, guild: Guild, config: Config, custom_config: str, prefix: str, cog_version: str, data: dict, config_data: dict)[source]

Builds a new Tournament from Challonge raw data.

Parameters:

  • bot (redbot.core.bot.Red) – The bot object

  • guild (discord.Guild) – The current guild for the tournament

  • config (redbot.core.Config) – The cog’s Config object

  • prefix (str) – A prefix to use for displaying commands without context.

  • cog_version (str) – Current version of Tournaments

  • data (dict) – Data as provided by the API.

  • config_data (dict) – A dict with all the config required for the tournament (combines guild and game settings)

await request(method, *args, **kwargs)[source]

An util adding the credentials to the args before sending an API call.

Also wraps the request in a retry loop (max 3 then raise).

class tournaments.objects.ChallongeParticipant(member: Member, tournament: Tournament)[source]

Bases: Participant

classmethod build_from_api(tournament: Tournament, data: dict)[source]

Builds a new member from Challonge raw data.

Parameters:

  • tournament (Tournament) – The current tournament

  • data (dict) – Data as provided by the API.

property player_id

Challonge player ID.

await destroy()[source]

If the tournament has started, disqualifies a player on the bracket, else he’s removed from the list of participants.

class tournaments.objects.ChallongeMatch(tournament: Tournament, round: int, set: str, id: int, underway: bool, player1: Participant, player2: Participant)[source]

Bases: Match

classmethod await build_from_api(tournament: Tournament, data: dict)[source]

Builds a new member from Challonge raw data.

This will also disqualify participants from the match not found in the server.

Parameters:

  • tournament (Tournament) – The current tournament

  • data (dict) – Data as provided by the API.