API Reference¶

Bot¶

class telegrampy.ext.commands.Bot(token: str, *, description: str = None, owner_id: int = None, owner_ids: list = None, help_command: telegrampy.ext.commands.help.HelpCommand = <telegrampy.ext.commands.help.DefaultHelpCommand object>)¶

Represents a Telegram bot.

Parameters

token (str) – The API token.
description (Optional[str]) – The bot’s description.
owner_id (Optional[int]) – The owner’s ID.
owner_ids (Optional[List[int]]) – The owner IDs.
help_command (Optional[telegrampy.ext.commands.HelpCommand]) – The bot’s help command. Defaults to telegrampy.ext.commands.DefaultHelpCommand

description¶

The bot’s description.

Type: Optional[str]

owner_id¶

The owner’s ID.

Type: Optional[int]

owner_ids¶

The owner IDs.

Type: Optional[List[int]]

cogs¶

A dictonary of cogs that are loaded.

Type: Mapping[str: telegrampy.ext.commands.Cog]

extensions¶

A dictonary of extensions that are loaded.

Type: Mapping[str: types.ModuleType]

add_cog(cog: telegrampy.ext.commands.cog.Cog)¶

Adds a cog to the bot.

Parameters: cog (telegrampy.ext.commands.Cog) – The cog to add.
Raises: TypeError – The cog is not a subclass of telegrampy.ext.commands.Cog or the cog check is not a method.

add_command(command)¶

Adds a command.

Parameters

command (telegrampy.ext.commands.Command) – The command to add.

Returns

The command added.

Return type

telegrampy.ext.commands.Command

Raises

telegrampy.ext.commands.CommandRegistrationError – The command name or one if its aliases is already registered by a different command.
TypeError – The command is not an instance of telegrampy.ext.commands.Command.

add_listener(func, name: str = None)¶

Registers a function as a listener.

Parameters

func – The function to register.
name (Optional[str]) – The name of the event to register the function as.

command(*args, **kwargs)¶

Turns a function into a command.

Parameters

*args – The arguments.
**kwargs – The keyword arguments.

commands¶: list: A list of the commands.

event(func)¶

Turns a function into an event handler.

Parameters: func – The function to make an event handler.

await get_chat(chat_id: int)¶

This function is a coroutine.

Fetches a chat by ID.

Parameters: chat_id (int) – The ID of the chat to fetch.
Returns: The chat that was fetched.
Return type: telegrampy.Chat
Raises: telegrampy.HTTPException – Fetching the chat failed.

get_command(name: str)¶

Gets a command by name.

Parameters: name (str) – The command name.
Returns: The command with the name.
Return type: telegrampy.ext.commands.Command

await get_context(message: telegrampy.message.Message)¶

Gets context for a given message.

Parameters: message (telegrampy.Message) – The message to get context from.
Returns: The context created.
Return type: telegrampy.ext.commands.Context
Raises: telegrampy.ext.commands.CommandNotFound – The command specified was not found.

help_command¶: telegrampy.ext.commands.HelpCommand: The bot’s help command.

listen(name=None)¶

A decorator that registers a function as a listener.

Parameters: name (Optional[str]) – The name of the event to register the function as.

load_extension(location: str)¶

Loads an extension.

Parameters

location (str) – The location of the extension.

Raises

telegrampy.ExtensionAlreadyLoaded – The extension is already loaded.
AttributeError – The extension has no setup function.

await on_command_error(ctx, error)¶: The default command error handler.

await on_error(error)¶

This function is a coroutine.

Default error handler.

reload_extension(location: str)¶

Reloads an extension.

Parameters: location (str) – The location of the extension.

remove_cog(cog: str)¶

Removes and cog from the bot.

Parameters: cog (str) – The name of the cog to remove.

remove_command(name: str)¶

Removes a command by name.

Parameters: name (str) – The name of the command to remove.
Returns: The command removed.
Return type: telegrampy.ext.commands.Command

remove_listener(func)¶

Removes a listener.

Parameters: func – The function that is registered as a listener.

run()¶: Runs the bot.

await start()¶: This function is a coroutine. Starts the bot.

await stop()¶: This function is a coroutine. Stops the bot.

unload_extension(location: str)¶

Unloads an extension.

Parameters: location (str) – The location of the extension.

await user()¶

This function is a coroutine.

The user of the bot.

await wait_for(event: str, check=None, timeout=None)¶

This function is a coroutine.

Waits for an event.

Parameters: event (str) – The name of the event to wait for.

Events¶

telegrampy.on_command_error(ctx, error)¶: Called when an error occurs in a command.

Command¶

telegrampy.ext.commands.command(*args, **kwargs)¶

Turns a function into a command.

See telegrampy.ext.commands.Command for parameters.

class telegrampy.ext.commands.Command(func, **kwargs)¶

Represents a command.

name¶

The name of the command.

Type: str

description¶

The description of the command.

Type: str

usage¶

The usage of the command.

Type: str

aliases¶

The aliases for the command.

Type: str

callback¶: The callback of the command.

hidden¶

If the command is hidden.

Type: bool

cog¶

The cog the command is in.

Type: telegrampy.ext.commands.Cog

bot¶

The bot the command is in.

Type: telegrampy.ext.commands.Bot

add_check(func)¶

Adds a check.

Parameters: func – The function to add to the checks.

clean_params¶: OrderedDict[str, inspect.Parameter]: Returns a mapping similar to inspect.Signature.parameters, but without self or context.

await invoke(ctx: telegrampy.ext.commands.context.Context)¶

This function is a coroutine.

Invokes the command with given context.

Parameters: ctx (telegrampy.ext.commands.Context) – The context to invoke the command with.

remove_check(func)¶

Removes a check.

Parameters: func – The function to remove from the checks.

signature¶

Returns a signature for a command that can be used in help commands

<required> required param [optional] optional param [params…] optional list of params [optional=0] optional param defaults to 0

Type: str

Checks¶

telegrampy.ext.commands.check(check_function)¶: Makes a check for a command.

telegrampy.ext.commands.telegrampy.ext.commands.is_owner()¶: A command check for checking that the user is the owner.

telegrampy.ext.commands.is_private_chat()¶: A command check for checking that the chat is a private chat.

telegrampy.ext.commands.is_not_private_chat()¶: A command check for checking that the chat is not a private chat.

Help Command¶

class telegrampy.ext.commands.HelpCommand(**options)¶

Help command template.

ctx¶

The telegrampy.ext.commands.Context for the command

Type: telegrampy.ext.commands.Context

bot¶

The telegrampy.ext.commands.Bot from the Context

Type: telegrampy.ext.commands.Bot

await get_command_signature(command)¶

The method that gets a formatted command signature

Example: /help [command]

await help_callback(query: Optional[str])¶

The callback that searches for a matching commmand or cog.

This should not be overridden unless it is necessary.

Parameters: query (Optional[str]) – The user’s query. Defaults to None.

await send_bot_help()¶

The method that sends help for the bot.

This is called when no query is provided. This method should handle the sending of the help message.

await send_cog_help(cog: telegrampy.ext.commands.cog.Cog)¶

The method that sends help for a cog.

This is called when a cog matches the query. This method should handle the sending of the help message.

Parameters: cog (telegrampy.ext.commands.Cog) – The cog that matched the query

await send_command_help(command: telegrampy.ext.commands.core.Command)¶

The method that sends help for a command.

This is called when a command matches the query. This method should handle the sending of the help message.

Parameters: command (telegrampy.ext.commands.Command) – The command that matched the query

await send_not_found(query: str)¶

The method that sends a ‘not found’ message or similar.

This method is called when no match is found for the query.

Parameters: query (str) – The user’s query

class telegrampy.ext.commands.DefaultHelpCommand(**options)¶

The default help command.

This help command mimics BotFather’s help command look.

Parameters

no_category (Optional[str]) – The heading for commands without a category. Defaults to “No Category”.
sort_commands (Optional[bool]) – Whether to sort the commands. Defaults to True.

await format_command(command)¶

The method that formats an indivitual command.

Parameters: command (Command) – The command to format.

await format_commands(commands: List[telegrampy.ext.commands.core.Command], *, heading: str)¶

The method that formats a given list of commands.

Parameters

commands (List[:class`telegrampy.ext.commands.Command`]) – The list of commands to format.
heading (str) – The heading to display.

get_ending_note()¶: Returns the command’s ending note.

await send_bot_help()¶

The method that sends help for the bot.

This is called when no query is provided. This method should handle the sending of the help message.

await send_cog_help(cog: telegrampy.ext.commands.cog.Cog)¶

The method that sends help for a cog.

This is called when a cog matches the query. This method should handle the sending of the help message.

Parameters: cog (telegrampy.ext.commands.Cog) – The cog that matched the query

await send_command_help(command: telegrampy.ext.commands.core.Command)¶

The method that sends help for a command.

This is called when a command matches the query. This method should handle the sending of the help message.

Parameters: command (telegrampy.ext.commands.Command) – The command that matched the query

Cog¶

class telegrampy.ext.commands.Cog¶

Base cog class.

commands¶

The cog’s commands.

Type: List[telegrampy.Command]

listeners¶

The cog’s listeners.

Type: list

description¶

The cog’s description.

Type: str

classmethod listener(name: str = None)¶

Makes a method in a cog a listener.

Parameters: name (Optional[str]) – The name of the event to register the function as.

qualified_name¶

The cog’s name.

Type: str

Context¶

class telegrampy.ext.commands.Context(command, **kwargs)¶

Context for a command.

bot¶

The bot that created the context.

Type: telegrampy.ext.commands.Bot

message¶

The message the context is for.

Type: telegrampy.Message

chat¶

The chat the context is for.

Type: telegrampy.Chat

author¶

The author of the message.

Type: telegrampy.User

command_failed¶

Whether the command failed or not.

Type: bool

args¶

The arguments passed into the command.

Type: list

kwargs¶

The kwargs passed into the command.

Type: dict

await reply(content: str, parse_mode: str = None)¶

This function is a coroutine.

Replys to the message.

Parameters

content (str) – The content of the message to send.
parse_mode (str) – The parse mode of the message to send.

Returns

The message sent.

Return type

telegrampy.Message

Raises

telegrampy.HTTPException – Sending the message failed.

await send(content: str = None, file: telegrampy.file.File = None, parse_mode=None)¶

This function is a coroutine.

Sends a message in the chat.

Parameters

content (str) – The content of the message to send.
file (telegrampy.File) – The file to send.
parse_mode (str) – The parse mode of the message to send.

Returns

The message sent.

Return type

telegrampy.Message

Raises

telegrampy.HTTPException – Sending the message failed.

await send_action(action: str)¶

This function is a coroutine.

Sends an action to the chat.

Parameters: action (str) – The action to send.
Raises: telegrampy.HTTPException – Sending the action failed.

await send_poll(question: str, options: list)¶

This function is a coroutine.

Sends a poll to the chat.

Parameters

question (str) – The question of the poll.
options (List[str]) – The options in the poll.

Returns

The poll sent.

Return type

telegrampy.Poll

Raises

telegrampy.HTTPException – Sending the poll failed.

Converters¶

class telegrampy.ext.commands.UserConverter¶

Converts an argument into a user.

await convert(ctx, arg)¶: Does the converting.

class telegrampy.ext.commands.ChatConverter¶

Converts an argument into a chat.

await convert(ctx, arg)¶: Does the converting.

Exceptions¶

class telegrampy.ext.commands.CommandError¶: Base exception for all command errors.

class telegrampy.ext.commands.CommandNotFound¶: Raised when a command is not found.

class telegrampy.ext.commands.CommandRegistrationError¶: Raised when a command cannot be registered.

class telegrampy.ext.commands.ExtensionNotLoaded(name)¶

Raised when an extension is not loaded.

name¶

The name of the extension that is not loaded.

Type: str

class telegrampy.ext.commands.ExtensionAlreadyLoaded(name)¶

Raised when an extension is already loaded.

name¶

The name of the extension that is already loaded.

Type: str

class telegrampy.ext.commands.MissingRequiredArgument(param)¶

Raised when a required argument is missing.

param¶

The argument that is missing.

Type: str

class telegrampy.ext.commands.BadArgument(arg, converter, message=None)¶

Raised when a bad argument is given.

arg¶

The bad argument.

Type: str

converter¶

The name of the converter that failed.

Type: str

class telegrampy.ext.commands.CheckFailure¶: Raised when a check fails.

class telegrampy.ext.commands.NotOwner¶: Raised when a user is not the owner of the bot.

class telegrampy.ext.commands.CommandInvokeError(error)¶

Raised when a command fails.

error¶

The original error that was raised.

Type: Exception

class telegrampy.ext.commands.PrivateChatOnly(message=None)¶: Raised when a command can only be used in private chats.

class telegrampy.ext.commands.GroupOnly(message=None)¶: Raised when a command can only be used in groups.