Components creation API

Creating components is one of the most useful features of botogram, since they allows you to reuse parts of your code in multiple bots. You can learn more about how to create them in the “Creating custom components” chapter.

class botogram.Component(name)

This class contains all the information about your component. You can either create an instance of it (providing a name), or subclass the class if you want your custom component to be instanceable. In the latter case, you don’t need to call the parent’s init method, and you can remove the name argument.

You can get more information about how to create components in the “Creating custom components” chapter.

Parameters:name (str) – The name of the component.
component_name

The name of the component. If you subclass the class in order to create a custom component, be sure to set it to an appropriate value.

add_before_processing_hook(func)

The function provided to this method will be called before an update is processed by a bot which uses the component. This allows you, for example, to set up a filter on who can send messages to the bot. Provided functions will be called with two parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for that update.

Parameters:func (callable) – The function you want to add.
add_process_message_hook(func)

The function provided to this method will be called while processing an update. You can then do everything you want in it. Provided functions will be called with two parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for that update.

Parameters:func (callable) – The function you want to add.
add_message_equals_hook(string, func[, ignore_case=True])

The function provided to this method will be called only if the processed message is equal to the string you provided. You may also define if you want to ignore the casing. Provided functions will be called with two parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message).

If the function returns True, then the message processing is stopped, and no more functions will be called for that update.

Parameters:
  • string (str) – The string you want equals to the message
  • func (callable) – The function you want to use.
  • ignore_case (bool) – If the check should be ignore-case
add_message_contains_hook(string, func[, ignore_case=True, multiple=False])

The function provided to this method will be called only if the processed message matches the string you provided. You may also define if you want to ignore the casing, and if the function should be called multiple times when multiple matches are found in the same message. Provided functions will be called with two parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message)

If the function returns True, then the message processing is stopped, and no more functions will be called for that update.

Parameters:
  • string (str) – The string you want contained in the message
  • func (callable) – The function you want to use.
  • ignore_case (bool) – If the match should be ignore-case
  • multiple (bool) – If the function should be called multiple times on multiple matches.
add_message_matches_hook(regex, func[, flags=0, multiple=False])

The function provided to this method will be called only if the processed message matches the regex you provided. You may also pass the re module’s flags, and if the function should be called when multiple matches are found in the same message. Provided functions will be called with three parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message)
  • A matches parameter with a tuple containing the matched groups

If the function returns True, then the message processing is stopped, and no more functions will be called for that update.

Parameters:
  • regex (str) – The regular expression the message should match
  • func (callable) – The function you want to use.
  • flags (int) – re module’s flags
  • multiple (bool) – If the function should be called multiple times on multiple matches.
add_message_edited_hook(func)

All the functions provided to this method will be called when an user edits a message the bot knows about. This allows you, for example, to update the preview of a message if the user edits the request, or to enforce a no-edits policy on groups by banning whoever edits a message.

You can request the following arguments in the provided functions:

  • chat: the chat in which the message was orignally sent (instance of Chat)
  • message: the edited message (instance of Message)
class NoEditsComponent(botogram.Component):
    component_name = "noedits"

    def __init__(self):
        self.add_message_edited_hook(self.no_edits)

    def no_edits(self, chat, message):
        message.reply("You can't edit messages! Bye.")
        chat.ban(message.sender)
Parameters:func (callable) – The function you want to use.

New in version 0.3.

add_channel_post_hook(func)

All the functions provided to this method will receive all the messages posted to channels the bot is a member of. This allows you to act when certain messages are received, as an example.

You can request the following arguments in the provided functions:

  • chat: the chat in which the channel post was originally sent (instance of Chat)
  • message: the message (instance of Message)
class ChannelAckComponent(botogram.Component):
    component_name = "channel-ack"

    def __init__(self):
        self.add_channel_post_hook(self.reply)

   def reply(self, chat, message):
       message.reply("I read this post!")
Parameters:func (callable) – The function you want to use.

New in version 0.4.

add_channel_post_edited_hook(func)

All the functions provided to this method will receive all the messages edited in channels the bot is a member of. This allows you to act when certain messages are changed, as an example.

You can request the following arguments in the provided functions:

  • chat: the chat in which the channel post was originally sent (instance of Chat)
  • message: the (new) edited message (instance of Message)
class ChannelAlertComponent(botogram.Component):
    component_name = "channel-alert"

    def __init__(self):
        self.add_channel_post_edited_hook(self.reply)

   def reply(self, chat, message):
       message.reply("This post is changed!")
Parameters:func (callable) – The function you want to use.

New in version 0.4.

add_command(name, func[, hidden=False, order=0])

This function registers a new command, and calls the provided function when someone issues the command in a chat. The command will also be added to the /help message. The provided function will be called with three parameters:

  • A chat parameter with the representation of the chat in which the message was sent (an instance of botogram.Chat)
  • A message parameter with the representation of the received message (an instance of botogram.Message)
  • An args parameter with the list of parsed arguments

If you put a docstring on the provided function, that will be used as extended description of the command in the /help command.

Also, if you don’t want this command to appear in the /help, you can set the hidden argument to True.

Note

Commands defined in custom components can be overridden by other components or by the bot developer.

Parameters:
  • name (str) – The name of the command.
  • func (callable) – The function you want to use.
  • hidden (bool) – If the command should be hidden from /help
  • order (int) – The order in which the commands are shown in /help

Changed in version 0.4: Added the order argument.

Changed in version 0.3: Added the hidden argument.

add_callback(name, func)

This method adds an handler for the callback with the provided name. See the chapter about buttons and callbacks for more information about them.

You can request the following arguments in the provided function:

  • query: the received CallbackQuery
  • chat: the Chat from which the callback query was sent
  • message: the Message related to the callback query
  • data: the custom information provided by you along with the call
class GreeterComponent(botogram.Component):
    component_name = "greeter"

    def __init__(self):
        self.add_command("greeter", self.command)
        self.add_callback("say-hi", self.say_hi)

    def greeter(self, chat, message):
        """Say hi to the user"""
        btns = botogram.Buttons()
        btns[0].callback("Click me", "say-hi", message.sender.name)

        chat.send("Click the button below", attach=btns)

    def say_hi(self, query, data):
        query.notify("Hi " + data)
Parameters:
  • name (str) – the name of the callback
  • func (callable) – The function you want to use

New in version 0.4.

add_chat_unavailable_hook(func)

The provided function is called when you try to send a message to a chat you can’t send messages to. There are currently multiple reasons why that can happen, and you can see all of them in the narrative documentation.

The provided function will be called with the following parameters:

  • chat_id: the ID of the chat which you can’t contact.
  • reason: the reason why you can’t contact the chat, as a string.

If you want to learn more about unavailable chats check out their documentation.

Parameters:func (callable) – The function you want to use.
add_timer(interval, func)

Execute the provided function periodically, at the provided interval, which must be in seconds. You can learn more in the Repeated execution section of the docs.

class SpammerComponent:

    component_name = "spammer"

    def __init__(self, user_id=None, message="Hey!"):
        self.user_id = user_id
        self.message = message

        self.add_timer(1, self.spam)

    def spam(self, bot):
        bot.send(self.user_id, self.message)
Parameters:
  • interval (int) – The execution interval, in seconds.
  • func (callable) – The function you want to use.
add_memory_preparer(func)

The function provided to this method will be called the first time you access your component’s shared memory. This allows you to set the initial state of the memory, without having to put initialization code in every function which uses the shared memory. Please don’t use this function as a “when the component is added to a bot” hook, because it’s not guaranteed to be called if you don’t use shared memory in all of your hooks.

The provided function will be called providing as first argument a dict-like object representing your bot’s shared memory. Use it to initialize the things you want in the shared memory.

class CountComponent(botogram.Component):

    component_name = "counter"

    def __init__(self):
        self.add_memory_preparer(self.initialize)
        self.add_process_message_hook(self.increment)
        self.add_command("count", self.count)

    def initialize(self, shared):
        shared["messages"] = 0

    def increment(self, shared, chat, message):
        if message.text is None:
            return
        shared["messages"] += 1

    def count(self, shared, chat, message, args):
        chat.send("This bot received %s messages" % shared["messages"])

Changed in version 0.2: Before it was called add_shared_memory_initializer.

add_shared_memory_initializer(func)

This method was renamed to add_memory_preparer() in botogram 0.2. Please use that instead of this.

Deprecated since version 0.2: it will be removed in botogram 1.0