tgbotzero 0.0.9

A zero-boilerplate simple telegram bots

TgBotZero

Телеграм-боты в пару строчек кода. Простые телеграм-боты должно быть очень просто делать!

Примеры

Бот, показывающий твоё сообщение:

Сначала нужно импортировать всё из библиотеки: from tgbotzero import *. Токен нужно указать в глобальной переменной TOKEN. Для обработки текстовых сообщений нужно создать функцию on_message(msg: str). Функция принимает текст сообщения, и может вернуть либо строку с текстом ответа, либо список из сообщений, описаний кнопок и картинок. Про кнопки и картинки будет дальше. Для запуска бота нужно выполнить команду run_bot() без параметров.

import tgbotzero

TOKEN = '123:tokenHereFromBotFatherInTelegram'

def on_message(msg: str):
    return "Твоё сообщение: " + msg
    
run_bot()

Установка

Введите в терминале:

pip install tgbotzero --upgrade --user

Или запустите эту программу:

import os, sys

python = sys.executable
user = '--user' if 'venv' not in python and 'envs' not in python else ''
cmd = f'"{python}" -m pip install tgbotzero --upgrade {user}'
os.system(cmd)

Бот с кнопками:

Для того чтобы добавить к любому сообщению кнопку, нужно в список артефактов ответа добавить кнопки: Button(text_on_button, button_handler_suffix, callback_data). Для обработки нажатий на кнопку нужно реализовать функцию on_button_NAME(data), где NAME=button_handler_suffix. В качестве data будет передано callback_data.

from tgbotzero import *

TOKEN = '123:tokenHereFromBotFatherInTelegram'

def on_message(msg: str):
    return [
        "Твоё сообщение: " + msg,
        Button('Кнопка', 'btn'),
    ]

def on_button_btn(data):
    return 'Нажата кнопка. Отправьте любое сообщение для продолжения'

run_bot()

Бот с командами:

Чтобы обрабатывать команды, нужно создать функцию вида on_command_NAME(cmd: str), где NAME — это собственно команда. Например, для обработки команд /start нужна функция on_command_start. Функция может возвращать текст, кнопки и т.п. точно так же, как и on_message и другие хендлеры-обработчики. При вызове команды /start все команды будут автоматом добавлены в меню пользователя. Для указания описания команды функции нужно указать doc-string:

def on_command_plus(cmd: str):
    """Add 1 to counter"""

from tgbotzero import *

TOKEN = '123:tokenHereFromBotFatherInTelegram'


def on_message(msg: str):
    return '''Доступны команды:
/show — показать
/plus — прибавить 1
/minus — вычесть 1'''

counter = 0

def on_command_show(cmd: str):
    """Показать значение"""
    return f'{counter=}'

def on_command_plus(cmd: str):
    """Прибавить 1"""
    global counter
    counter += 1
    return f'{counter=}'

def on_command_minus(cmd: str):
    """Вычесть 1"""
    global counter
    counter -= 1
    return f'{counter=}'

run_bot()

Бот с картинками:

Для отправки изображения нужно добавить в возвращаемый список Image(image_filename). Можно отправлять несколько изображений в одном сообщении, в том числе отправлять изображения из обработчиков кнопок и команд.

from tgbotzero import *

TOKEN = '123:tokenHereFromBotFatherInTelegram'

def on_message(msg: str):
    return [
        f"Мяу-гав!",
        Image('cat.png'),
        Image('dog.png'),
        Button('Класс!', 'btn')
    ]

def on_button_btn(data):
    return 'Ага!'

run_bot()

Обработка и модификация картинок:

Для обработки сообщений с картинками нужно создать функцию on_image(msg: str, img: Image). Изображения можно модифицировать. На данный момент поддерживается только добавление текста. Синтаксис: img.put_text(text, color), гдеcolor — это RGB-кортеж, например, (255, 0, 0). Изображения можно модифицировать даже если они открыты из файла: Image(image_filename).put_text(text, color)

from tgbotzero import *

TOKEN = '123:tokenHereFromBotFatherInTelegram'

def on_message(msg: str):
    return 'Жду картинку с подписью!'

def on_image(msg: str, img: Image):
    return img.put_text(msg, (255, 0, 0))

run_bot()

Получение chat_id:

К любой функции-обработчику можно добавить ещё один параметр chat_id: int, если хочется различать пользователей.

from tgbotzero import *

TOKEN = '123:tokenHereFromBotFatherInTelegram'


def on_message(msg: str, chat_id: int):
    return f"Текущий chat id: {chat_id}"


run_bot()

Contributing