extergram 0.4.1

Простая и удобная библиотека для создания Telegram-ботов.

Extergram (English Version)

A simple and convenient library for creating Telegram bots in Python.

Installation

To install the library, use the following command in your terminal:

pip install extergram

Core Components and How to Use Them

The library provides several simple tools for creating a bot.

1. Bot - This is the main object for your bot. You create it first by passing your token: bot = Bot('YOUR_TOKEN')

2. Decorators - This is how you tell the bot how to react to events.

   • @bot.on_message() This decorator is placed on a function that should run whenever a user sends any message to the bot.

   • @bot.on_callback_query() This decorator is used for functions that respond to clicks on inline buttons under a message.

3. Message and CallbackQuery Objects When your handler function is called, it receives a special object with information about the event.

   • The on_message handler receives a Message object. From it, you can get the message text (message.text) or the chat ID (message.chat.id).
   • The on_callback_query handler receives a CallbackQuery object. From it, you can find out which button was pressed (callback.data) and in which message (callback.message).

4. ButtonsDesign - This is a builder for creating keyboards. You can add rows of buttons for the user to click.

5. bot.polling() - This is the command to start the bot. It starts an infinite loop where the bot constantly checks for new messages and calls the appropriate handlers.

Example Usage

Here is a complete example of a simple bot. Create a file named main.py:

import extergram
from extergram import Bot, ButtonsDesign, Message, CallbackQuery
from extergram import errors
import datetime

# IMPORTANT: Replace 'YOUR_BOT_TOKEN' with your actual token
bot = Bot('YOUR_BOT_TOKEN')

# First, let's create a keyboard we will use
main_menu = ButtonsDesign().add_row(
    ButtonsDesign.create_button("Show time", "show_time"),
    ButtonsDesign.create_button("About", "about")
).add_row(
    ButtonsDesign.create_button("Delete this message", "delete")
)

# This function will trigger when a user sends a message
@bot.on_message()
def handle_messages(message: Message):

    if message.text == '/start':
        user_name = message.from_user.first_name
        text = f"Hello, {user_name}! I am your new bot."

        bot.send_message(
            chat_id=message.chat.id,
            text=text,
            reply_markup=main_menu
        )
    else:
        bot.send_message(
            chat_id=message.chat.id,
            text=f"You wrote: {message.text}"
        )

# This function will trigger when a user clicks an inline button
@bot.on_callback_query()
def handle_callbacks(callback: CallbackQuery):

    # First, answer the callback to remove the "loading" state on the user's side
    bot.answer_callback_query(callback.id)

    if callback.data == 'show_time':
        now = datetime.datetime.now().strftime("%H:%M:%S")
        bot.edit_message_text(
            chat_id=callback.message.chat.id,
            message_id=callback.message.message_id,
            text=f"The current time is: {now}",
            reply_markup=main_menu
        )

    elif callback.data == 'about':
        bot.edit_message_text(
            chat_id=callback.message.chat.id,
            message_id=callback.message.message_id,
            text="This bot was created using the Extergram library!",
            reply_markup=main_menu
        )
    
    elif callback.data == 'delete':
        bot.delete_message(
            chat_id=callback.message.chat.id,
            message_id=callback.message.message_id
        )

# This line starts the bot's continuous operation
if __name__ == '__main__':
    bot.polling()

Running the Bot

To run the bot, simply execute the following command in your terminal:

python main.py