Bot Subpackage

This subpackage contains the bot related modules used to run a YugiQuery bot.

Base Module

class yugiquery.bot.base.Bot

Bases: object

Bot superclass.

Parameters:

**kwargs – Additional keyword arguments.

start_time

The bot initialization timestamp.

Type:

arrow.Arrow

repo

The git repository object, if there is a repository, else None.

Type:

git.Repo

process

The variable to hold a process spawned by run_query.

Type:

multiprocessing.Process

cooldown_limit

The cooldown time in seconds to wait between consecutive calls to run_query.

Type:

Tnt

class Reports

Bases: Enum

property URLS: StrEnum

Property to get the URLs of the remote repository and webpage.

__init__(**kwargs)

Initializes the Bot base class.

Parameters:

**kwargs – Additional keyword arguments.

abort() → str

Aborts a running YugiQuery flow by terminating the process.

Returns:

The result message indicating whether the abortion was successful.

Return type:

str

async battle(callback: Callable[[str], None], atk_weight: int = 4, def_weight: int = 1) → dict

This function loads the list of all Monster Cards and simulates a battle between them. Each card is represented by its name, attack (ATK), and defense (DEF) stats. At the beginning of the battle, a random card is chosen as the initial contestant. Then, for each subsequent card, a random stat (ATK or DEF) is chosen to compare with the corresponding stat of the current winner. If the challenger’s stat is higher, the challenger becomes the new winner. If the challenger’s stat is lower, the current winner retains its position. If the stats are tied, the comparison is repeated with the other stat. The battle continues until there is only one card left standing.

Parameters:

  • callback (Callable[[str], None]) – A callback function which receives a string argument.

  • atk_weight (int, optional) – The weight to use for the ATK stat when randomly choosing the monster’s stat to compare. This affects the probability that ATK will be chosen over DEF. The default value is 4.

  • def_weight (int, optional) – The weight to use for the DEF stat when randomly choosing the monster’s stat to compare. This affects the probability that DEF will be chosen over ATK. The default value is 1.

Returns:

A dictionary containing information about the battle.

Return type:

dict

benchmark() → Dict[str, str]

Returns the average time each report takes to complete and the latest time for each report.

Returns:

A dictionary containing benchmark information.

Return type:

dict

data() → Dict[str, str]

Sends the latest data files available in the repository as direct download links.

Returns:

A dictionary containing direct links to the latest data files.

Return type:

dict

init_reports_enum() → None

Initializes and returns an Enum object containing the available reports. The reports are read from the NOTEBOOKS directories, where they are expected to be Jupyter notebooks. The Enum object is created using the reports’ file names, with the .ipynb extension removed and the first letter capitalized.

Returns:

None

latest() → Dict[str, str]

Displays the timestamp of the latest local and live reports generated. Reads the report files from dirs.REPORTS and queries the GitHub API for the latest commit timestamp for each file.

Returns:

A dictionary containing information about the latest reports.

Return type:

dict

Displays the links to the YugiQuery webpage, repository, and data.

Returns:

A dictionary containing links to YugiQuery resources.

Return type:

dict

pull(passphrase: str = '') → str

Pulls the latest data files from the repository.

Parameters:

passphrase (str, optional) – The passphrase to use for decryption. Defaults to empty.

Returns:

The result message indicating whether the pull was successful

Return type:

str

push(passphrase: str = '') → str

Pushes the latest data files to the repository.

Parameters:

passphrase (str, optional) – The passphrase to use for encryption. Defaults to empty.

Returns:

The result message indicating whether the push was successful

Return type:

str

async run_query(callback: Callable[[str], None], report: Reports = Reports.All, progress_bar: tqdm_asyncio = None, **pbar_kwargs) → Dict[str, str]

Runs a YugiQuery flow by launching a separate thread and monitoring its progress.

Parameters:

  • callback (Callable[[str], None]) – A callback function which receives a string argument.

  • report (Reports, optional) – The report to run. Defaults to All.

  • progress_bar (tqdm, optional) – A tqdm progress bar. Defaults to None.

  • **pbar_kwargs – Additional Keyword arguments to customize the progress bar..

Returns:

A dictionary containing the result of the query execution.

Return type:

dict

uptime()

Returns humanized bot uptime.

yugiquery.bot.base.load_secrets_with_args(args: Any) → Tuple[str, int | str]

Load secrets from command-line arguments, and update them with values from environment variables or a .env file, placed in the Assets directory, if necessary. If the required secrets are not found, the function will exit the program.

Parameters:

args (Any) – The parsed command-line arguments.

Returns:

The token and channel ID.

Return type:

(str, int)

yugiquery.bot.base.set_parser(parser: ArgumentParser) → None

Set the parser arguments for the bot mode.

Parameters:

  • parser (argparse.ArgumentParser) – The parser object to set the arguments on.

  • subclass (bool, optional) – Whether to include the subclass argument. Defaults to False.

Discord Module

class yugiquery.bot.discord.Discord

Bases: Bot, Bot

Discord bot subclass. Inherits from Bot class and discord.ext.commands.Bot.

Parameters:

  • token (str) – The token for the Discord bot.

  • channel_id (str | int) – The channel ID for the bot.

discord.ext.commands.Bot attributes
Bot attributes
__init__(token: str, channel_id: str | int)

Initializes the Discord bot subclass.

Parameters:

  • token (str) – The token for the Discord bot.

  • channel_id (str | int) – The channel ID for the Discord bot.

async on_command_error(ctx, error: CommandError) → None

Event callback that runs whenever a command invoked by the user results in an error. Sends a message to the channel indicating the type of error that occurred.

Parameters:

  • ctx (commands.Context) – The context of the error.

  • error (commands.CommandError) – The error received.

async on_message(message: Message) → None

Event callback that runs whenever a message is sent in a server where the bot is present. Responds with a greeting to any message starting with ‘hi’.

Parameters:

  • ctx (commands.Context) – The context of the message.

  • message (discord.Message) – The message received.

async on_ready() → None

Event callback that runs when the bot is ready to start receiving events and commands. Prints out the bot’s username and the guilds it’s connected to.

register_commands() → None

Register command handlers for the Discord bot.

Command descriptions:

abort - Aborts a running YugiQuery flow by terminating the process.

battle - Simulate a battle of all monster cards.

benchmark - Show average time each report takes to complete.

data - Send latest data files.

shutdown - Shutdown bot

latest - Show latest time each report was generated.

links - Show YugiQuery links.

ping - Test the bot connection latency.

pull - Pull latest data files from the repository.

push - Push latest data files to the repository.

run - Run full YugiQuery flow.

status - Display bot status and system information.

run() → None

Starts running the discord Bot.

Telegram Module

class yugiquery.bot.telegram.Telegram

Bases: Bot

Telegram bot subclass. Inherits from Bot class.

Parameters:

  • token (str) – The token for the Telegram bot.

  • chat_id (str | int) – The Telegram chat ID.

application

The Telegram Application bot instance.

Type:

telegram.Application

Bot attributes
__init__(token: str, chat_id: str | int)

Initialize the Telegram Bot subclass.

Parameters:

  • token (str) – The token for the Telegram bot.

  • chat_id (str | int) – The chat ID for the Telegram bot.

register_commands() → None

Register command handlers for the Telegram bot.

Command descriptions to pass to BotFather:

abort - Aborts a running YugiQuery flow by terminating the process.

battle - Simulate a battle of all monster cards.

benchmark - Show average time each report takes to complete.

data - Send latest data files.

shutdown - Shutdown bot.

latest - Show latest time each report was generated.

links - Show YugiQuery links.

ping - Test the bot connection latency.

pull - Pull latest data files from the repository.

push - Push latest data files to the repository.

run - Run full YugiQuery flow.

status - Display bot status and system information.

register_events() → None

Register event handlers for the Telegram bot.

run() → None

Start running the Telegram bot.