Cardinal

Архитектурная роль

Модуль cardinal является центральным компонентом системы FunPayCardinal, отвечающим за инициализацию и управление основными функциями бота, включая взаимодействие с Telegram API, обработку событий и плагинов. Он также обеспечивает доступ к конфигурационным данным и управляет жизненным циклом бота.

Компоненты и логика

get_cardinal()

• Назначение: Возвращает существующий экземпляр кардинала.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

PluginData

• Назначение: Класс, описывающий плагин.
• Аргументы и связи:
• name (str): название плагина.
• version (str): версия плагина.
• desc (str): описание плагина.
• credentials (str): авторы плагина.
• uuid (str): UUID плагина.
• path (str): путь до плагина.
• plugin (ModuleType): как модуля.
• settings_page (bool): есть ли страница настроек у плагина.
• delete_handler (Callable | None): хэндлер, привязанный к удалению плагина.
• enabled (bool): включен ли плагин.
• pinned (bool): закреплен ли плагин в списке плагинов.
• Взаимодействие: Нет.

Cardinal

• Назначение: Основной класс, управляющий работой бота.
• Аргументы и связи:
• main_config (): основной конфигурационный файл.
• auto_delivery_config (): конфигурационный файл для авто выдачи.
• auto_response_config (): конфигурационный файл для авто передачи.
• raw_auto_response_config (): сырой конфигурационный файл для авто передачи.
• version (str): версия бота.

• Экземпляр класса кардинал содержит в себе следующие важные глобальные переменные, которые необходимы для написания плагинов:
• BIND_TO_PRE_INIT – До старта основных подсистем fp api
• BIND_TO_INIT – После полной инициализации fp api, tg bot
• BIND_TO_POST_START – После того как запущен Runner
• BIND_TO_NEW_ORDER – Как только появляется заказ (NewOrderEvent )
• BIND_TO_ORDER_STATUS_CHANGED – Как только изменился статус заказа (OrderStatusChangedEvent)
• BIND_TO_NEW_MESSAGE – Как только пришло сообщение (NewMessageEvent )
• BIND_TO_DELETE – Удаление плагина через меню в tg bot

• Взаимодействие:
• Вызывает __init_account
• Вызывает __init_telegram
• Вызывает __update_profile
• Вызывает TGBot

__init_account

• Назначение: Инициализирует класс аккаунта (self.account).
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

__update_profile

• Назначение: Загружает данные о лотах категориях аккаунта.
• Аргументы и связи:
• infinite_polling (bool): бесконечно посылать запросы, пока не будет получен ответ (игнорировать макс. кол-во попыток).
• attempts (int): максимальное кол-во попыток.
• update_telegram_profile (bool): обновить информацию о профиле для TG ПУ.
• update_main_profile (bool): обновить информацию о профиле для всего кардинала (+ хэндлеров).
• Взаимодействие: Нет.

__init_telegram

• Назначение: Инициализирует Telegram бота.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Вызывает TGBot.

get_balance

• Назначение: Получает баланс аккаунта.
• Аргументы и связи:
• attempts (int): кол-во попыток на получение баланса.
• Взаимодействие: Нет.

raise_lots

• Назначение: Попытка поднять лоты.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

get_order_from_object

• Назначение: Получает заказ из объекта.
• Аргументы и связи:
• obj (OrderShortcut | Message | ChatShortcut): объект, содержащий информацию о заказе.
• order_id (str | None): ID заказа.
• Взаимодействие: Нет.

split_text

• Назначение: Разбивает текст на суб-тексты по 20 строк.
• Аргументы и связи:
• text (str): исходный текст.
• Взаимодействие: Нет.

parse_message_entities

• Назначение: Разбивает сообщения по 20 строк, отделяет изображения от текста.
• Аргументы и связи:
• msg_text (str): текст сообщения.
• Взаимодействие: Нет.

send_message

• Назначение: Отправляет сообщение в чат FunPay.
• Аргументы и связи:
• chat_id (int | str): ID чата.
• message_text (str): текст сообщения.
• chat_name (str | None): название чата (необязательно).
• interlocutor_id (int | None): ID собеседника (необязательно).
• attempts (int): кол-во попыток на отправку сообщения.
• watermark (bool): добавлять ли водяной знак в начало сообщения.
• Взаимодействие: Нет.

get_exchange_rate

• Назначение: Получает курс обмена между двумя указанными валютами.
• Аргументы и связи:
• base_currency (Currency): исходная валюта.
• target_currency (Currency): целевая валюта.
• min_interval (int): минимальное время в секундах между проверками курса обмена.
• Взаимодействие: Нет.

update_session

• Назначение: Обновляет данные аккаунта (баланс, токены и т.д.).
• Аргументы и связи:
• attempts (int): кол-во попыток.
• Взаимодействие: Нет.

process_events

• Назначение: Запускает хэндлеры, привязанные к тому или иному событию.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

lots_raise_loop

• Назначение: Запускает бесконечный цикл поднятия категорий (если autoRaise в _main.cfg == 1).
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

update_session_loop

• Назначение: Запускает бесконечный цикл обновления данных о пользователе.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

init

• Назначение: Инициализирует кардинал: регистрирует хэндлеры, инициализирует и запускает Telegram бота, получает данные аккаунта и профиля.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Вызывает telegram как класс TGBot .

run

• Назначение: Запускает кардинал после инициализации. Используется для первого старта.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

start

• Назначение: Запускает кардинал после остановки. Не используется.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

stop

• Назначение: Останавливает кардинал. Не используется.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

update_lots_and_categories

• Назначение: Парсит лоты (для ПУ TG).
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

switch_msg_get_mode

• Назначение: Смена режима получения сообщений.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

save_config

• Назначение: Сохраняет конфиг в указанный файл.
• Аргументы и связи:
• config (): объект конфига.
• file_path (str): путь до файла, в который нужно сохранить конфиг.
• Взаимодействие: Нет.

is_uuid_valid

• Назначение: Проверяет, является ли UUID плагина валидным.
• Аргументы и связи:
• uuid (str): UUID4.
• Взаимодействие: Нет.

is_plugin

• Назначение: Проверяет, есть ли “noplug” в начале файла плагина.
• Аргументы и связи:
• file (str): файл плагина.
• Взаимодействие: Нет.

load_plugin

• Назначение: Создает модуль из переданного файла-плагина и получает необходимые поля для PluginData.
• Аргументы и связи:
• from_file (str): путь до файла-плагина.
• Взаимодействие: Нет.

load_plugins

• Назначение: Импортирует все плагины из папки plugins.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

add_handlers_from_plugin

• Назначение: Добавляет хэндлеры из плагина + присваивает каждому хэндлеру UUID плагина.
• Аргументы и связи:
• plugin (ModuleType): модуль (плагин).
• uuid (str | None): UUID плагина (None для встроенных хэндлеров).
• Взаимодействие: Нет.

add_handlers

• Назначение: Регистрирует хэндлеры из всех плагинов.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

run_handlers

• Назначение: Выполняет функции из списка handlers.
• Аргументы и связи:
• handlers_list (list: Callable): список хэндлеров.
• args: аргументы для хэндлеров.
• Взаимодействие: Нет.

add_telegram_commands

• Назначение: Добавляет команды в список команд плагина.
• Аргументы и связи:
• uuid (str): UUID плагина.
• commands (list[tuple[str, str, bool]]): список команд (без ”/”).
• Взаимодействие: Нет.

toggle_plugin

• Назначение: Активирует / деактивирует плагин.
• Аргументы и связи:
• uuid (str): UUID плагина.
• Взаимодействие: Нет.

pin_plugin

• Назначение: Закрепляет / открепляет плагин в списке плагинов.
• Аргументы и связи:
• uuid (str): UUID плагина.
• Взаимодействие: Нет.

autoraise_enabled

• Назначение: Возвращает, включена ли автозапуск категорий.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

autoresponse_enabled

• Назначение: Возвращает, включена ли автопередача.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

autodelivery_enabled

• Назначение: Возвращает, включена ли автовыдача.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

multidelivery_enabled

• Назначение: Возвращает, включена ли многократная выдача.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

autorestore_enabled

• Назначение: Возвращает, включена ли автозагрузка.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

autodisable_enabled

• Назначение: Возвращает, включена ли автодеактивация.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

old_mode_enabled

• Назначение: Возвращает, включена ли старый режим.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

keep_sent_messages_unread

• Назначение: Возвращает, сохраняются ли отправленные сообщения как непрочитанные.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

show_image_name

• Назначение: Возвращает, показывается ли имя изображения.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

bl_delivery_enabled

• Назначение: Возвращает, включена ли блокировка доставки.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

bl_response_enabled

• Назначение: Возвращает, включена ли блокировка ответа.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

bl_msg_notification_enabled

• Назначение: Возвращает, включена ли блокировка уведомлений о сообщениях.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

bl_order_notification_enabled

• Назначение: Возвращает, включена ли блокировка уведомлений о заказах.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

bl_cmd_notification_enabled

• Назначение: Возвращает, включена ли блокировка уведомлений о командах.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

include_my_msg_enabled

• Назначение: Возвращает, включены ли сообщения пользователя.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

include_fp_msg_enabled

• Назначение: Возвращает, включены ли сообщения FunPay.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

include_bot_msg_enabled

• Назначение: Возвращает, включены ли сообщения бота.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

only_my_msg_enabled

• Назначение: Возвращает, включены ли только сообщения пользователя.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

only_fp_msg_enabled

• Назначение: Возвращает, включены ли только сообщения FunPay.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

only_bot_msg_enabled

• Назначение: Возвращает, включены ли только сообщения бота.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

block_tg_login

• Назначение: Возвращает, заблокирован ли вход в Telegram.
• Аргументы и связи:
• Нет аргументов.
• Взаимодействие: Нет.

Граф зависимостей

• Входящие зависимости: Bot, Handlers, Utils
• Исходящие зависимости: Bot, Enums, Exceptions, Handlers, Types, Utils