Основной класс плагина: `CactusUtils.Plugin`¶

Наследование от CactusUtils.Plugin (или его псевдонимов CactusModule, CactusPlugin) является ключевым моментом в разработке, так как это наделяет ваш класс множеством полезных методов и атрибутов.

🗄️ База данных¶

Каждый плагин, использующий CactusLib, получает собственное персистентное хранилище в виде JSON-файла. Вам не нужно заботиться о его создании или загрузке — просто используйте встроенные методы.

self.get(key: str, default: Any = None) -> Any Получает значение по ключу. Если ключ не найден, возвращает default.
self.set(key: str, value: Any) Сохраняет значение по ключу.
self.pop(key: str) -> Any Удаляет ключ и возвращает его значение.
self.clear_db() Полностью очищает базу данных вашего плагина.

Пример: счетчик использований команды

class MyPlugin(CactusUtils.Plugin):
    @command(doc="Увеличивает и показывает счетчик")
    def count(self, cmd: CactusUtils.Command):
        # Получаем текущее значение, если его нет, то 0
        current_count = self.get("usage_count", 0)
        current_count += 1
        # Сохраняем новое значение
        self.set("usage_count", current_count)

        cmd.answer(f"Эту команду использовали {current_count} раз.")

        return HookResult(strategy=HookStrategy.CANCEL)

🌍 Локализация (i18n)¶

CactusLib имеет встроенную поддержку нескольких языков. Вы можете определить строки для разных языков, и библиотека автоматически выберет нужную в зависимости от настроек пользователя.

Для этого в вашем классе нужно определить словарь strings:

class MyPlugin(CactusUtils.Plugin):
    strings = {
        "en": {
            "GREETING": "Hello, {}!",
            "__doc__": "This is a plugin description."
        },
        "ru": {
            "GREETING": "Привет, {}!",
            "__doc__": "Это описание плагина."
        }
    }
    # ...

self.string(key: str, *args, default: str = None, **kwargs) -> str Получает строку по ключу для текущего языка пользователя, форматируя ее с переданными аргументами.
self.lstrings() -> dict Возвращает весь словарь строк для текущего языка.

Пример использования self.string:

    @command(doc="Персональное приветствие")
    def greet(self, cmd: CactusUtils.Command):
        if not cmd.args:
            cmd.answer("Пожалуйста, укажите имя.")
            return HookResult(strategy=HookStrategy.CANCEL)

        user_name = cmd.args[0]
        # Автоматически выберет "Привет" или "Hello"
        greeting_text = self.string("GREETING", user_name)
        cmd.answer(greeting_text)

        return HookResult(strategy=HookStrategy.CANCEL)

📥/📤 Управление данными при импорте/экспорте¶

Вы можете определять собственную логику для сохранения и восстановления сложных данных.

export_data(self) -> dict Вызывается, когда пользователь экспортирует плагины с данными. Верните словарь с данными, которые вы хотите сохранить.
import_data(self, data: dict) Вызывается при импорте. В data будет словарь, который вы вернули из export_data.

Примечание

Встроенная база данных хранится на устройстве в папке exteraGram в виде .json файла, а также экспортируются и импортируются самостоятельно при экспорте/импорте плагина или его загрузке.

Пример:

class MyPlugin(CactusUtils.Plugin):
    def on_plugin_load(self):
        super().on_plugin_load()
        self.non_db_data = set() # Данные, которые не хранятся в JSON DB

    def export_data(self) -> dict:
        # Конвертируем set в list для JSON-сериализации
        return {"my_custom_set": list(self.non_db_data)}

    def import_data(self, data: dict):
        # Получаем данные и конвертируем обратно в set
        self.non_db_data = set(data.get("my_custom_set", []))

📝 Другие полезные атрибуты и методы¶

self.utils: Прямой доступ к объекту CactusUtils со всеми его статическими методами.
self.log(msg), self.info(msg), self.debug(msg), self.warn(msg), self.error(msg): Методы для записи в logcat с автоматической подстановкой ID вашего плагина.
__min_lib_version__: Строка, указывающая минимально требуемую версию CactusLib (например, "1.7.0"). Если версия у пользователя ниже, плагин не загрузится.
UPDATE_DATA: Словарь с данными для обновления плагина.