Утилиты для Aiogram 3.x

Инструменты для быстрой интеграции ОП (Обязательной Подписки) в бота.

Middleware

Автоматическая проверка подписки перед обработкой сообщений.

aiosubgram.utils.middleware.OPMiddleware

OPMiddleware(client: SubgramClient, max_sponsors: int = 5, sub_text: str = 'Чтобы получить доступ к боту, подпишитесь:', channel_text: str = '➕ Подписаться', bot_text: str = '➕ Перейти в бота', smart_link_text: str = '➕ Перейти', resource_text: str = '➕ Перейти', done_button_text: str = '✅ Я подписался!')

Bases: BaseMiddleware

Миддлварь для aiogram, которая добавляет клавиатуру с кнопками подписки на каналы, боты, смарт-ссылки и внешние ресурсы.

Parameters:

Name	Type	Description	Default
client	SubgramClient	Экземпляр SubgramClient.	required
max_sponsors	int	Максимальное количество спонсоров. По умолчанию: 5.	5
sub_text	str	Текст на кнопке подписки. По умолчанию: "Чтобы получить доступ к боту, подпишитесь:".	'Чтобы получить доступ к боту, подпишитесь:'
channel_text	str	Текст на кнопке для каналов. По умолчанию: "➕ Подписаться".	'➕ Подписаться'
bot_text	str	Текст на кнопке для ботов. По умолчанию: "➕ Перейти в бота".	'➕ Перейти в бота'
smart_link_text	str	Текст на кнопке для смарт-ссылок. По умолчанию: "➕ Перейти".	'➕ Перейти'
resource_text	str	Текст на кнопке для внешних ресурсов. По умолчанию: "➕ Перейти".	'➕ Перейти'
done_button_text	str	Текст на кнопке "Я подписался!". По умолчанию: "✅ Я подписался!"	'✅ Я подписался!'

Source code in aiosubgram\utils\middleware.py

def __init__(self, client: SubgramClient, max_sponsors: int = 5,
             sub_text: str = "Чтобы получить доступ к боту, подпишитесь:",
             channel_text: str = "➕ Подписаться", bot_text: str = "➕ Перейти в бота",
             smart_link_text: str = "➕ Перейти", resource_text: str = "➕ Перейти",
             done_button_text: str = "✅ Я подписался!"):
    """Миддлварь для aiogram, которая добавляет клавиатуру с кнопками подписки на каналы, боты, смарт-ссылки и внешние ресурсы.

    Args:
        client (SubgramClient): Экземпляр SubgramClient.
        max_sponsors (int): Максимальное количество спонсоров. По умолчанию: 5.
        sub_text (str): Текст на кнопке подписки. По умолчанию: "Чтобы получить доступ к боту, подпишитесь:".
        channel_text (str): Текст на кнопке для каналов. По умолчанию: "➕ Подписаться".
        bot_text (str): Текст на кнопке для ботов. По умолчанию: "➕ Перейти в бота".
        smart_link_text (str): Текст на кнопке для смарт-ссылок. По умолчанию: "➕ Перейти".
        resource_text (str): Текст на кнопке для внешних ресурсов. По умолчанию: "➕ Перейти".
        done_button_text (str): Текст на кнопке "Я подписался!". По умолчанию: "✅ Я подписался!"
    """
    self.client = client
    self.max_sponsors = max_sponsors
    self.sub_text = sub_text
    self.channel_text = channel_text
    self.bot_text = bot_text
    self.smart_link_text = smart_link_text
    self.resource_text = resource_text
    self.done_button_text = done_button_text

Attributes

bot_text instance-attribute

bot_text = bot_text

channel_text instance-attribute

channel_text = channel_text

client instance-attribute

client = client

done_button_text instance-attribute

done_button_text = done_button_text

max_sponsors instance-attribute

max_sponsors = max_sponsors

resource_text instance-attribute

resource_text = resource_text

smart_link_text instance-attribute

smart_link_text = smart_link_text

sub_text instance-attribute

sub_text = sub_text

Functions

__call__ async

__call__(handler, event, data)

Source code in aiosubgram\utils\middleware.py

async def __call__(self, handler, event, data):
    if not hasattr(event, "from_user"):
        return
    try:
        sponsors_response = await self.client.get_sponsors(
            event.from_user.id,
            event.from_user.id,
            event.from_user.first_name,
            event.from_user.username,
            event.from_user.language_code,
            event.from_user.is_premium,
            max_sponsors=self.max_sponsors
        )
        if sponsors_response.status == "warning":
            keyboard = await create_op_keyboard(
                sponsors_response,
                self.client,
                self.channel_text,
                self.bot_text,
                self.smart_link_text,
                self.resource_text,
                self.done_button_text
            )
            await event.bot.send_message(event.from_user.id, self.sub_text, reply_markup=keyboard)
            return
        return await handler(event, data)
    except Exception as e:
        print(e)
        return await handler(event, data)

Клавиатуры

Генерация кнопок для подписки.

aiosubgram.utils.keyboard

Classes

Functions

create_op_keyboard async

create_op_keyboard(sponsors_response: Optional[GetSponsors] = None, client: Optional[SubgramClient] = None, channel_text: str = '➕ Подписаться', bot_text: str = '➕ Перейти в бота', smart_link_text: str = '➕ Перейти', resource_text: str = '➕ Перейти', done_button_text: Optional[str] = '✅ Я подписался!', **kwargs: Any) -> InlineKeyboardMarkup

Генерирует клавиатуру (InlineKeyboardMarkup) для aiogram на основе списка спонсоров. Если sponsors_response не передан, функция сама сделает запрос к API через client.

Parameters:

Name	Type	Description	Default
sponsors_response	GetSponsors	Объект ответа от get_sponsors (если уже есть).	None
client	SubgramClient	Экземпляр SubgramClient (нужен, если sponsors_response is None).	None
channel_text	str	Текст на кнопке для каналов (можно использовать {name}).	'➕ Подписаться'
bot_text	str	Текст на кнопке для ботов.	'➕ Перейти в бота'
smart_link_text	str	Текст на кнопке для смарт-ссылок.	'➕ Перейти'
resource_text	str	Текст на кнопке для внешних ресурсов.	'➕ Перейти'
done_button_text	Optional[str]	Текст кнопки проверки подписки (callback_data: "subgram-done").	'✅ Я подписался!'
**kwargs	Any	Аргументы для get_sponsors (chat_id, user_id и т.д.), если запрос делается внутри.	{}

Returns:

Name	Type	Description
InlineKeyboardMarkup	InlineKeyboardMarkup	Готовая клавиатура со ссылками на спонсоров.

Source code in aiosubgram\utils\keyboard.py

async def create_op_keyboard(
    sponsors_response: Optional[GetSponsors] = None,
    client: Optional[SubgramClient] = None,
    channel_text: str = "➕ Подписаться",
    bot_text: str = "➕ Перейти в бота",
    smart_link_text: str = "➕ Перейти",
    resource_text: str = "➕ Перейти",
    done_button_text: Optional[str] = "✅ Я подписался!",
    **kwargs: Any
) -> InlineKeyboardMarkup:
    """
    Генерирует клавиатуру (InlineKeyboardMarkup) для aiogram на основе списка спонсоров.
    Если `sponsors_response` не передан, функция сама сделает запрос к API через `client`.

    Args:
        sponsors_response (GetSponsors): Объект ответа от get_sponsors (если уже есть).
        client (SubgramClient): Экземпляр SubgramClient (нужен, если sponsors_response is None).
        channel_text (str): Текст на кнопке для каналов (можно использовать {name}).
        bot_text (str): Текст на кнопке для ботов.
        smart_link_text (str): Текст на кнопке для смарт-ссылок.
        resource_text (str): Текст на кнопке для внешних ресурсов.
        done_button_text (Optional[str]): Текст кнопки проверки подписки (callback_data: "subgram-done").
        **kwargs (Any): Аргументы для get_sponsors (chat_id, user_id и т.д.), если запрос делается внутри.

    Returns:
        InlineKeyboardMarkup: Готовая клавиатура со ссылками на спонсоров.
    """
    if not sponsors_response:
        sponsors_response = await client.get_sponsors(**kwargs)

    kb_builder = InlineKeyboardBuilder()

    buttons = []

    for sponsor in sponsors_response.sponsors:
        if sponsor.status != "unsubscribed":
            continue
        if sponsor.type == "channel":
            buttons.append(
                InlineKeyboardButton(text=channel_text, url=sponsor.link)
            )
        elif sponsor.type == "bot":
            buttons.append(
                InlineKeyboardButton(text=bot_text, url=sponsor.link)
            )
        elif sponsor.type == "smart_link":
            buttons.append(
                InlineKeyboardButton(text=smart_link_text, url=sponsor.link)
            )
        elif sponsor.type == "resource":
            buttons.append(
                InlineKeyboardButton(text=resource_text, url=sponsor.link)
            )
    if buttons:
        kb_builder.row(*buttons)

        if done_button_text:
            kb_builder.row(
                InlineKeyboardButton(text=done_button_text, callback_data="subgram-done")
            )
        return kb_builder.as_markup()