Вся структура класса CactusUtils.

Просьба посмотреть всех методы и все классы, вы можете найти вспомогающие вам штуки.

Методы

Все методы являются статичными, то есть не требуют инициализации класса и можно вызывать напрямую: CactusUtils.copy_to_clipboard("Hello, exteraGram!")

version_bigger_or_equal

def version_bigger_or_equal(a, b) -> bool

Сравнивает версию a с версией b. На выход идёт a >= b.

Пример использования

v1 = "1.6.5"
v2 = "1.8"
is_upgrade = CactusUtils.version_bigger_or_equal(v1, v2)
if not is_upgrade:
  raise Exception("v1 < v2")

all_plugins

def all_plugins() -> list[BasePlugin | CactusUtils.Plugin]

Возвращает список классов всех плагинов из PluginsController.pluginInstances.

plugin

def plugin(plugin_id: str) -> BasePlugin | CactusUtils.Plugin

Возвращает класс плагина по его ID.

gen

def gen(java_class: JavaClass, method_name: str, return_value: bool = False) -> type

Этот метод генерирует новый прокси-класс, который расширяет данный java_class и переопределяет определенный метод.

type(jclass("java.lang.Object"))

required

Класс-интерфейс для создания своего класс через dynamic_proxy.

str

required

Имя метода, который будет переопределен в прокси-классе.

bool

default:"False"

Возвращать ли значение вашей функции в ответ в переопределенном методе.

Пример использования

from org.telegram.messenger import Utilities

# Функция для переопределения
def function(arg1, arg2, test):
    ...

# Это создает прокси, который переопределяет 'run'
MyProxyClass = CactusUtils.gen(Utilities.Callback2, "run")

# Создание экземпляра прокси
proxy_instance = MyProxyClass(function, test="value")

gen2

def gen2(java_class: JavaClass, return_value: bool = False, **methods) -> type

Этот метод похож на gen, но позволяет переопределять несколько методов в сгенерированном прокси-классе.

type(jclass("java.lang.Object"))

required

Класс-интерфейс для создания своего класс через dynamic_proxy.

bool

default:"False"

Возвращать ли значение ваших функций в ответ в переопределенных методах.

dict[str, callable]

required

Именованные аргументы, где ключ - это имя метода, а значение - это вызываемый объект Python, который заменит исходную реализацию метода.

Пример использования

from com.example import AnotherJavaClass

# Предположим, что AnotherJavaClass имеет методы 'methodA' и 'methodB'б которые нам нужно переопределить
MyMultiProxyClass = CactusUtils.gen2(
    AnotherJavaClass,
    return_value=True,
    methodA=lambda *args: print(f"Метод A вызван с: {args}"),
    methodB=lambda *args, **kwargs: print(f"Метод B вызван с: {args}, {kwargs}")
)

proxy_instance = MyMultiProxyClass("аргумент1", test="аргумент2")

from android.text import TextWatcher

def handle_changed_text(text):
    ...

text_watcher = CactusUtils.gen2(TextWatcher, **{
    "onTextChanged": lambda text, *_: handle_changed_text(text),
    "beforeTextChanged": lambda *_: None,
    "afterTextChanged": lambda *_: None
})()

compress_and_encode

def compress_and_encode(data: Union[bytes, str], level: int = 7) -> str

Метод для сжатия данных. Оборачивает в base64 сжатые через zlib данные.

bytes | str

required

Данные для упаковывания.

int

default:"7"

Уровень сжатия. Подробнее

Пример использования

compressed = CactusUtils.compress_and_encode("hello from [dev-cat] den!")
# eNrLSM3JyVdIK8rPVYhOSS3TTU4siVVISc1TBAB3zAjd

decode_and_decompress

def decode_and_decompress(encoded_data: Union[bytes, str]) -> bytes

Метод для распаковки данных, сжатых с помощью метода decode_and_decompress.

bytes | str

required

Данные для распаковки.

Пример использования

compressed = CactusUtils.compress_and_encode("hello from [dev-cat] den!")
string = CactusUtils.decode_and_decompress(compressed).decode("utf-8")
# "hello from [dev-cat] den!"

pluralization_string

def pluralization_string(number: int, words: List[str]) -> str

Возвращает множественную строку, основанную на заданном числе.

int

required

Число, определяющее форму множественного числа.

list[str]

required

Список из 3 слов, представляющих формы единственного, двойственного и множественного числа.

Пример использования

num = 5
pluralization_string(num, ["жизнь", "жизни", "жизней"])
# 1 -> 1 жизнь, 2 -> 2 жизни, 5 -> 5 жизней
pluralization_string(num, ["рубль", "рубля", "рублей"])
# 1 -> 1 рубль, 2 -> 2 рубля, 5 -> 5 рублей
pluralization_string(num, ["ручка", "ручки", "ручек"])
# 1 -> 1 ручка, 2 -> 2 ручки, 5 ручек
pluralization_string(num, ["апельсин", "апельсина", "апельсинов"])
# 1 -> 1 апельсин, 2 -> 2 апельсина, 5 -> 5 апельсинов

escape_html

def escape_html(text: str) -> str

Экранирует html-теги

str

required

Текст для экранирования

Пример использования

escaped = CactusUtils.escape_html("Test <html> string!")
# Test &lt;html&gt; string!

copy_to_clipboard

def copy_to_clipboard(text: str) -> None

Копирует заданный текст в буфер обмена и выводит информацию об этом

str

required

Текст для копирования.

prefix

def prefix() -> str

Возвращает текущий префикс системы команд в CactusLib.

get_locale

def get_locale() -> str

Возвращает текущую локаль. Например, en или ru.

log | debug | warn | info | error

def log(message: str, level: str = "INFO", __id__: Optional[str] = "cactuslib") -> None: ...
def debug(message: str, __id__: Optional[str] = "cactuslib") -> None: ...
def warn(message: str, __id__: Optional[str] = "cactuslib") -> None: ...
def info(message: str, __id__: Optional[str] = "cactuslib") -> None: ...
def error(message: str, __id__: Optional[str] = "cactuslib") -> None: ...

Рекомендуется использовать методы в классе плагина.Методы для логирования по уровню и ID. На выход в logcat идёт лог формата: [level] [__id__] {message}

str

required

Текст лога

str

Уровень логов. DEBUG | INFO | WARN | ERROR Одноименные методы автоматически выставляют данный параметр.

str

required

ID плагина.

get_logs

def get_logs(
    __id__: Optional[str] = None,
    times: Optional[int] = None,
    lvl: Optional[str] = None,
    as_list: bool = False
) -> list[str] | str

Метод для получения логов по ID, уровню и времени.

array_list

def array_list(*args) -> ArrayList

Метод для легкого создания ArrayList. Можно привести список в качестве первого и единственного аргумента, тогда он преобразует данный список в ArrayList.

Пример использования

plist = ["test", "values", "123"]
alist = CactusUtils.array_list(plist)

alist2 = CactusUtils.array_list(
  "first",
  "and",
  "second",
  "value",
)

edit_message

def edit_message(
    message_object: MessageObject,
    text: str, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    markup: Any = None, **kwargs
)

Метод для редактирования сообщения.

org.telegram.messenger.MessageObject

required

Объект изменяемого сообщения.

str

required

Новый текст сообщения.

bool

default:"True"

Разбирать ли текст на HTML-разметку или Markdown-разметку.

str

default:"HTML"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

list[dict] | CactusUtils.Inline.Markup | ...

default:"None"

Объект с Inline клавиатурой.

Дополнительные параметры, которые передаются в editMessage

Дополнительные параметры

bool

default:"False"

Добавлять ли предпросмотр ссылке (наверное).Используется в реквесте TLRPC.TL_messages_editMessage() в качестве параметра no_webpage:

req.no_webpage = !searchLinks

org.telegram.ui.ActionBar.BaseFragment

default:"None"

Фрагмент. Рекомендуется указывать fragment=client_utils.get_last_fragment().

int

default:"0"

Schedule datetime timestamp.

edit_message_markup

def edit_message_markup(cell: ChatMessageCell, markup: Optional[Any] = None)

Метод для редактирования Inline-клавиатуры сообщения.

org.telegram.ui.Cells.ChatMessageCell

required

UI-Объект сообщения, который нужно отредактировать.

list[dict] | CactusUtils.Inline.Markup | ...

default:"None"

Объект с Inline клавиатурой (None для удаления клавиатуры у сообщения).

send_message

def send_message(
    cls,
    peer: int,
    text: str, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    markup: Optional[Any] = None,
    on_sent: Optional[Callable] = None,
    **kwargs
)

Важный частоиспользуемый метод для отправки сообщений. Текст может быть разобран на HTML-разметку или Markdown-разметку. К сообщению могут быть добавлены Inline кнопки, а также можно отследить отправку сообщения.

int

required

ID чата, в который нужно отправить сообщение.

str

required

Текст отправляемого сообщения.

bool

default:"True"

Разбирать ли текст на HTML-разметку или Markdown-разметку.

str

default:"HTML"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

list[dict] | CactusUtils.Inline.Markup | ...

default:"None"

Объект с Inline клавиатурой.

Callable[[CactusUtils.Inline.CallbackParams], None]

default:"None"

Функция, которая будет вызвана после отправки сообщения. Принимает один аргумент — объект CactusUtils.Inline.CallbackParams (button=None).

Дополнительные параметры, которые передаются в send_message

Дополнительные параметры

org.telegram.tgnet.TLRPC.MessageMedia

org.telegram.tgnet.TLRPC.TL_photo

org.telegram.messenger.VideoEditedInfo

org.telegram.tgnet.TLRPC.User

org.telegram.tgnet.TLRPC.TL_document

org.telegram.tgnet.TLRPC.TL_game

org.telegram.tgnet.TLRPC.TL_messageMediaPoll

Torg.telegram.tgnet.LRPC.TL_messageMediaToDo

TLRPC.TL_messageMediaInvoice

TLRPC.TL_messageMediaWebPage

String

org.telegram.messenger.MessageObject

TLRPC.WebPage

bool

default:"True"

org.telegram.messenger.MessageObject

bool

default:"True"

int

default:"0"

int

default:"0"

java.lang.Object

org.telegram.messenger.MessageObject.SendAnimationData

bool

default:"False"

bool

default:"False"

org.telegram.tgnet.tl.TL_stories.StoryItem

ChatActivity.ReplyQuote

String

int

long

default:"not set"

bool

default:"False"

bool

default:"?"

MessageSuggestionParams

send_file

def send_file(
    peer: int, path: str,
    caption: Optional[str] = None, *,
    parse_markdown: bool = True,
    parse_mode: str = "HTML",
    **kwargs
)

Отправляет документ (файл) с возможностью добавить форматированную подпись.

int

required

ID чата.

str

required

Путь к файлу

str

default:"None"

Текст-описание к файлу.

bool

default:"True"

Разбирать ли текст на HTML-разметку или Markdown-разметку.

str

default:"HTML"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

Дополнительные параметры, которые передаются в send_message

Дополнительные параметры

Параметры, которые передаются в метод SendMessagesHelper.prepareSendingDocumentInternal

str

default:"text/plain"

MIME type of the file

MessageObject

default:"None"

Message to reply to (maybe params.replyToMsg)

MessageObject

default:"None"

top message to reply to (maybe params.replyToTopMsg)

TL_stories.StoryItem

default:"None"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

ChatActivity.ReplyQuote

default:"None"

Quote

bool

default:"True"

Send message with notification

org.telegram.messenger.MessageObject

default:"None"

Message to edit/add file

int

default:"0"

Schedule datetime

str

default:"None"

Quick reply shortcut

int

default:"0"

Quick reply shortcut ID

int

default:"0"

Message effect ID

bool

default:"False"

Invert media

int

default:"0"

Pay stars

org.telegram.messenger.AccountInstance

default:"client_utils.get_account_instance()"

Current Account instance

ArrayList<TLRPC.MessageEntity>

default:"False"

Message caption entities (Если parse_message=True, данный параметр будет сгенерирован автоматически)

long[]

default:"jarray(jlong)([0])"

Group ID

bool

default:"True"

Is final document in group

Integer[]

default:"jarray(Integer)([0])"

Doc type ID

int

default:"0"

MonoForum peer ID

org.telegram.messenger.MessageSuggestionParams

default:"None"

Suggestion message params

Пример:

logs.plugin

@command("getlogs")
def handle_logs(self, command: CactusUtils.Command):
    log_content = "some log data..."
    # Записываем контент во временный файл
    file_path = self.utils.FileSystem.write_temp_file("logs.txt", log_content.encode("utf-8"), delete_after=60)

    self.answer_file(command.params, file_path, caption="Вот ваши логи:")

    return HookResult(strategy=HookStrategy.CANCEL)

send_files

def send_files(
    peer: int, paths: List[str],
    caption: Optional[str] = None, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    **kwargs
)

Отправляет документы (файлы) с возможностью добавить форматированную подпись к первому из них.

int

required

ID чата.

list[str]

required

Пути к файлам.

str

default:"None"

Текст-описание к файлу.

bool

default:"True"

Разбирать ли текст на HTML-разметку или Markdown-разметку.

str

default:"HTML"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

Дополнительные параметры, которые передаются в send_message

Дополнительные параметры

Параметры, которые передаются в метод SendMessagesHelper.prepareSendingDocumentInternal

str

default:"text/plain"

MIME type of the file

MessageObject

default:"None"

Message to reply to (maybe params.replyToMsg)

MessageObject

default:"None"

top message to reply to (maybe params.replyToTopMsg)

TL_stories.StoryItem

default:"None"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

ChatActivity.ReplyQuote

default:"None"

Quote

bool

default:"True"

Send message with notification

org.telegram.messenger.MessageObject

default:"None"

Message to edit/add file

int

default:"0"

Schedule datetime

str

default:"None"

Quick reply shortcut

int

default:"0"

Quick reply shortcut ID

int

default:"0"

Message effect ID

bool

default:"False"

Invert media

int

default:"0"

Pay stars

org.telegram.messenger.AccountInstance

default:"client_utils.get_account_instance()"

Current Account instance

ArrayList<TLRPC.MessageEntity>

default:"False"

Message caption entities (Если parse_message=True, данный параметр будет сгенерирован автоматически)

long[]

default:"jarray(jlong)([0])"

Group ID

bool

default:"True"

Is final document in group

Integer[]

default:"jarray(Integer)([0])"

Doc type ID

int

default:"0"

MonoForum peer ID

org.telegram.messenger.MessageSuggestionParams

default:"None"

Suggestion message params

Пример:

logs.plugin

@command("getlogs")
def handle_logs(self, command: CactusUtils.Command):
    log_content = "some log data..."
    # Записываем контент во временный файл
    file_path = self.utils.FileSystem.write_temp_file("logs.txt", log_content.encode("utf-8"), delete_after=60)

    self.answer_file(command.params, file_path, caption="Вот ваши логи:")

    return HookResult(strategy=HookStrategy.CANCEL)

Классы

JsonDB

class JsonDB(dict)

Класс для управления данными в JSON-файле, наследующий от dict. Он автоматически загружает данные из указанного файла при инициализации и сохраняет изменения при вызове методов, таких как set, pop или update_from.

str

required

Путь к JSON-файлу.

method _load

def _load(self) -> Dict[str, Any]

Загружает данные из JSON-файла, указанного при инициализации. Если файл не существует, возвращает пустой словарь.

method save

def save(self) -> None

Сохраняет текущее состояние словаря в JSON-файл.

method set

def set(self, key: str, value: Any) -> None

Устанавливает значение для заданного ключа, а затем сохраняет изменения в JSON-файл.

str

required

Ключ для установки.

Any

required

Значение, которое будет связано с ключом.

method get

def get(self, key: str, default=None)

Извлекает значение, связанное с заданным ключом. Работает идентично стандартному методу dict.get().

str

required

Ключ для извлечения.

Any

default:"None"

Значение, которое будет возвращено, если ключ не найден.

method pop

def pop(self, key: str) -> Any

Удаляет указанный ключ и связанное с ним значение из словаря, а затем сохраняет изменения в JSON-файл.

str

required

Ключ для удаления.

method reset

def reset(self) -> None

Очищает все данные из словаря и JSON-файла.

method update_from

def update_from(self, **kwargs)

Обновляет словарь парами ключ-значение из kwargs, а затем сохраняет изменения в JSON-файл.

Command

@dataclass
class Command

Класс, который возвращается в callback функцию команде.

str

Имя команды или псевдоним, который был использован.

list[str]

Список разделенных аргументов после команды.Разделение в основном через пробел, но если нужно передать одним аргументом текст с пробелами, можно использовать ковычки: .test arg1 arg2 "arg3 with many words" -> args = ["arg1", "arg2", "arg3 with many words"] .test arg1 arg2 param="value with many words" -> args = ["arg1", "arg2", "param=value with many words"]

str

Все, что идет после команды, в виде одной строки.

str

Полный текст исходного сообщения.

org.telegram.messenger.SendMessagesHelper$SendMessageParams

Объект с параметрами исходного сообщения (peer, replyToMsg и т.д.).

int

Текущий аккаунт

func

Функция, возвращающая текст исходного сообщения с HTML-разметкой.

func

Функция, возвращающая текст исходного сообщения с Markdown-разметкой.

method answer

def answer(text: str, **kwargs)

Отправляет ответное сообщение по заданным параметрам. replyToMsg и replyToTopMsg подставляются автоматически.

str

required

Текст нового сообщения

Дополнительные параметры, которые передаются в CactusUtils.send_message.

method html

def html(self) -> str

Функция, возвращающая текст исходного сообщения с HTML-разметкой.Возвращает CactusUtils.HTML.unparse(self.text, list(self.params.entities.toArray()))

method markdown

def markdown(self) -> str

Функция, возвращающая текст исходного сообщения с Markdown-разметкой.Возвращает CactusUtils.Markdown.unparse(self.text, list(self.params.entities.toArray()))

UriCallback

@dataclass
class UriCallback

Класс, который возвращается в callback функцию MessageUri ссылки.

MessageObject

Объект сообщения, к которому привязана клавиатура.

ChatMessageCell

UI-элемент сообщения.

str

Метод из ссылки, который сработал.

str

Ссылка, на которую было произведено нажатие

bool

Длительное нажатие на кнопку.

method edit (edit_message)

def edit_message(self, text: str, **kwargs) -> None

Изменяет сообщение по заданным параметрам.

str

required

Текст нового сообщения

Дополнительные параметры, которые передаются в CactusUtils.edit_message.

method edit_markup

def edit_markup(self, markup: Optional[Any] = None)

Изменяет Inline-клавиатуру текущему сообщению, автоматически подставляя в CactusUtils.edit_message_markup UI-объект сообщения.

method delete (delete_message)

def delete_message(self) -> None

Удаляет сообщение.

class Telegram

Класс Telegram предоставляет статические методы для взаимодействия с Telegram API, включая отправку запросов TLRPC, поиск сообщений и получение информации о пользователях, чатах, каналах и стикерпаках.

class Result

class Result:

Внутренний класс, используемый для хранения результатов асинхронных запросов TLRPC.

int

Идентификатор запроса. Уникальный номер, присвоенный отправленному запросу.

TLObject

Объект ответа от Telegram API. Содержит данные, полученные в случае успешного выполнения запроса.

TLRPC.TL_error

Объект ошибки TLRPC. Содержит информацию об ошибке, если запрос завершился неудачей.

class TLRPCException

class TLRPCException(Exception):

Исключение, вызываемое при получении ошибки TLRPC от Telegram API.

int

required

Идентификатор запроса. Уникальный номер запроса, который вызвал данную ошибку.

TLRPC.TL_error

required

Объект ошибки TLRPC. Полный объект ошибки, возвращенный Telegram API.

int

Код ошибки. Числовой код ошибки TLRPC.

str

Текст ошибки. Подробное текстовое описание ошибки TLRPC.

method tlrpc_object

@staticmethod
def tlrpc_object(request_class, **kwargs)

Создает объект запроса TLRPC, устанавливая предоставленные аргументы как атрибуты класса запроса. Это удобный способ инициализировать объекты запросов.

Any

required

Класс запроса TLRPC. Например, TLRPC.TL_messages_search для поиска сообщений.

Any

Аргументы запроса. Именованные аргументы, которые будут установлены как атрибуты создаваемого объекта запроса.

method send

@classmethod
def send(
    cls,
    req,
    callback: Optional[callable] = None, *,
    wait_response: bool = True,
    timeout: int = 10,
    raise_errors: bool = True
) -> Union[int, Result]

Отправляет запрос TLRPC в Telegram API. Позволяет выбрать синхронное или асинхронное выполнение, а также настроить обработку ошибок и тайм-аутов.

Any

required

Объект запроса TLRPC. Сам запрос, который вы хотите отправить (например, TLRPC.TL_messages_getMessages).

Optional[callable]

default:"None"

Функция обратного вызова. Если wait_response равно False, эта функция будет вызвана с результатом и ошибкой после получения ответа.

bool

default:"True"

Ожидать ли ответ. Если True, метод будет блокироваться до получения ответа и возвращать объект Result. Если False, метод вернет идентификатор запроса немедленно.

int

default:"10"

Тайм-аут. Максимальное время в секундах, которое метод будет ждать ответа, если wait_response равно True.

bool

default:"True"

Вызывать ли исключения. Если True и запрос завершился ошибкой, будет вызвано исключение TLRPCException. Если False, ошибка будет возвращена внутри объекта Result.

class SearchFilter

class SearchFilter(Enum):

Перечисление, представляющее различные фильтры для поиска сообщений. Используется для уточнения типа сообщений, которые вы ищете.

str

GIF. Фильтр для поиска GIF-изображений.

str

MUSIC. Фильтр для поиска музыкальных файлов.

str

CHAT_PHOTOS. Фильтр для поиска фотографий, отправленных в чат.

str

PHOTOS. Фильтр для поиска любых фотографий.

str

URL. Фильтр для поиска сообщений, содержащих URL-адреса.

str

DOCUMENT. Фильтр для поиска документов.

str

PHOTO_VIDEO. Фильтр для поиска фотографий и видео.

str

PHOTO_VIDEO_DOCUMENT. Фильтр для поиска фотографий, видео и документов.

str

GEO. Фильтр для поиска сообщений с геолокациями.

str

PINNED. Фильтр для поиска закрепленных сообщений.

str

MY_MENTIONS. Фильтр для поиска сообщений, в которых упомянут текущий пользователь.

str

ROUND_VOICE. Фильтр для поиска голосовых круглых сообщений.

str

CONTACTS. Фильтр для поиска сообщений с контактами.

str

VOICE. Фильтр для поиска голосовых сообщений.

str

VIDEO. Фильтр для поиска видеосообщений.

str

PHONE_CALLS. Фильтр для поиска информации о телефонных звонках.

str

ROUND_VIDEO. Фильтр для поиска видео круглых сообщений.

str

EMPTY. Пустой фильтр, не применяет специфических ограничений по типу.

method to_TLRPC_object

def to_TLRPC_object(self)

Преобразует элемент перечисления SearchFilter в соответствующий объект TLRPC-фильтра сообщений, который можно использовать в запросах к Telegram API.

method search_messages

@classmethod
def search_messages(
    cls,
    dialog_id: int,
    query: Optional[str] = None,
    from_id: Optional[int] = None,
    offset_id: int = 0,
    limit: int = 20,
    reply_message_id: Optional[int] = None,
    top_message_id: Optional[int] = None,
    filter: SearchFilter = SearchFilter.EMPTY,
    **kwargs
) -> Union[List[MessageObject], int]

Осуществляет поиск сообщений в указанном диалоге, позволяя фильтровать по запросу, отправителю, смещению и типу содержимого.

int

required

Идентификатор диалога. ID чата, пользователя или канала, где будет производиться поиск.

Optional[str]

default:"None"

Текст запроса. Строка для поиска в содержимом сообщений.

Optional[int]

default:"None"

Идентификатор отправителя. ID пользователя, от которого должны быть получены сообщения.

int

default:"0"

ID смещения. Сообщения будут возвращены, начиная с этого ID (или после него).

int

default:"20"

Лимит. Максимальное количество сообщений, которое будет возвращено.

Optional[int]

default:"None"

ID сообщения-ответа. Если указано, поиск будет ограничен сообщениями, которые являются ответами на это конкретное сообщение.

Optional[int]

default:"None"

ID верхнего сообщения. Используется в контексте тематических групп (форумов) для указания ID главного сообщения темы.

SearchFilter

default:"SearchFilter.EMPTY"

Фильтр поиска. Тип содержимого, по которому нужно фильтровать сообщения (например, SearchFilter.PHOTOS).

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send, такие как wait_response или timeout.

method get_user

@staticmethod
def get_user(user_id: int)

Получает объект пользователя по его идентификатору.

int

required

Идентификатор пользователя. Уникальный ID пользователя, информацию о котором вы хотите получить.

method input_user

@staticmethod
def input_user(user_id: int)

Получает объект InputUser по идентификатору пользователя. Этот объект используется в других запросах к Telegram API, которым требуется ссылка на пользователя.

int

required

Идентификатор пользователя. Уникальный ID пользователя.

method peer

@staticmethod
def peer(peer_id: int)

Получает объект Peer по идентификатору пира (пользователя, чата или канала). Peer представляет собой общую сущность в Telegram.

int

required

Идентификатор пира. ID пользователя, чата или канала.

method input_peer

@staticmethod
def input_peer(peer_id: int)

Получает объект InputPeer по идентификатору пира (пользователя, чата или канала). InputPeer — это объект, который API использует для идентификации целевого диалога.

int

required

Идентификатор пира. ID пользователя, чата или канала.

method get_sticker_set_by_short_name

@classmethod
def get_sticker_set_by_short_name(cls, short_name: str, **kwargs)

Получает информацию о наборе стикеров по его короткому имени (например, t.me/addstickers/example).

str

required

Короткое имя набора стикеров. Имя, используемое в ссылках для добавления стикеров.

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.

method get_chat

@classmethod
def get_chat(cls, chat_id: int, **kwargs)

Получает информацию о групповом чате по его идентификатору.

int

required

Идентификатор чата. ID группового чата, информацию о котором вы хотите получить.

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.

method get_channel

@classmethod
def get_channel(cls, channel_id: int, **kwargs) -> int

Получает информацию о канале по его идентификатору.

int

required

Идентификатор канала. ID канала, информацию о котором вы хотите получить.

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.

method get_user_photos

@classmethod
def get_user_photos(cls, user_id: int, limit: int = 1, **kwargs)

Получает фотографии профиля пользователя.

int

required

Идентификатор пользователя. ID пользователя, чьи фотографии профиля вы хотите получить.

int

default:"1"

Лимит. Максимальное количество фотографий профиля для получения. По умолчанию 1.

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.

method get_channel_messages

@classmethod
def get_channel_messages(
    cls, channel: Union[int, str, Any], ids: Union[List[int], int], **kwargs
)

Получает конкретные сообщения из канала по их идентификаторам.

ВНИМАНИЕ: Этот метод может не возвращать ожидаемый результат в полной мере. Если у вас есть информация или предложения по исправлению, пожалуйста, свяжитесь с @chillden4ik в Telegram.

Union[int, str, Any]

required

Канал. Может быть передан как:

целое число: ID канала.
строка: короткое имя канала (username), которое будет автоматически разрешено.
любой другой объект: объект канала, который может быть преобразован в InputPeer или TL_inputChannel.

Union[List[int], int]

required

Идентификаторы сообщений. Может быть одним целым числом (ID одного сообщения) или списком целых чисел (ID нескольких сообщений).

Any

Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.

method delete_messages

@classmethod
def delete_messages(cls, ids: Union[List[int], int], chat_id: int, topic_id: int = 0, for_all: bool = True)

Удаляет одно или несколько сообщений в указанном чате.

Union[List[int], int]

required

Идентификаторы сообщений. ID одного сообщения или список ID сообщений для удаления.

int

required

Идентификатор чата. ID чата, из которого будут удалены сообщения.

int

default:"0"

Идентификатор топика. Если чат является форумом, это ID топика, из которого удаляются сообщения. По умолчанию 0 для обычных чатов.

bool

default:"True"

Удалить для всех. Если True, сообщения будут удалены для всех участников чата. Если False, сообщения будут удалены только для текущего пользователя.

method resolve_channel

@classmethod
def resolve_channel(cls, username: str, *, callback: Optional[Callable[[Any], None]] = None)

Разрешает короткое имя канала (username, например, @telegram) в полный объект канала. Может работать как синхронно (по умолчанию), так и асинхронно через обратный вызов.

str

required

Короткое имя канала. Username канала, который вы хотите разрешить (без символа @).

Optional[Callable[[Any], None]]

default:"None"

Функция обратного вызова. Если предоставлена, метод будет работать асинхронно, и эта функция будет вызвана с разрешенным объектом канала.

FileSystem

class FileSystem

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

method basedir

@classmethod
def basedir(cls, *path: str)

Возвращает базовую директорию приложения. Если предоставлены аргументы path, то будут созданы поддиректории внутри базовой директории, если они не существуют, и будет возвращен объект File для самого глубокого указанного пути.

str

Необязательные компоненты пути для добавления к базовой директории.

method cachedir

@classmethod
def cachedir(cls, *path: str)

Возвращает директорию внешнего кеша приложения. Если предоставлены аргументы path, то будут созданы поддиректории внутри директории кеша, если они не существуют, и будет возвращен объект File для самого глубокого указанного пути.

str

Необязательные компоненты пути для добавления к директории кеша.

method tempdir

@classmethod
def tempdir(cls)

Возвращает временную директорию специально для cactuslib_temp_files внутри директории кеша. Создает эту директорию, если она еще не существует.

method get_file_content

@classmethod
def get_file_content(cls, file_path, mode: str = "rb")

Читает и возвращает содержимое файла.

str

required

Путь к файлу.

str

default:"rb"

Режим открытия файла (например, "rb" для чтения бинарных данных, "r" для чтения текстовых данных).

method get_temp_file_content

@classmethod
def get_temp_file_content(
    cls, filename: str, mode: str = "rb", delete_after: int = 0
)

Читает и возвращает содержимое файла, расположенного во временной директории. При желании файл может быть запланирован на удаление через указанное количество секунд.

str

required

Имя файла во временной директории.

str

default:"rb"

Режим открытия файла (например, "rb" для чтения бинарных данных, "r" для чтения текстовых данных).

int

default:"0"

Количество секунд, по истечении которых файл должен быть удален. Если 0, файл не удаляется автоматически.

method write_file

@classmethod
def write_file(cls, file_path, content, mode: str = "wb")

Записывает содержимое в указанный файл.

str

required

Путь к файлу.

Any

required

Содержимое для записи в файл.

str

default:"wb"

Режим открытия файла (например, "wb" для записи бинарных данных, "w" для записи текстовых данных).

method write_temp_file

@classmethod
def write_temp_file(
    cls, filename: str, content, mode="wb", delete_after: int = 0
)

Записывает содержимое в файл во временной директории. При желании файл может быть запланирован на удаление через указанное количество секунд.

str

required

Имя файла для создания во временной директории.

Any

required

Содержимое для записи в файл.

str

default:"wb"

Режим открытия файла (например, "wb" для записи бинарных данных, "w" для записи текстовых данных).

int

default:"0"

Количество секунд, по истечении которых файл должен быть удален. Если 0, файл не удаляется автоматически.

method delete_file_after

@classmethod
def delete_file_after(cls, file_path, seconds: int = 0)

Удаляет файл после указанной задержки. Если seconds равно 0, файл удаляется немедленно.

str

required

Путь к файлу для удаления.

int

default:"0"

Количество секунд ожидания перед удалением файла. Если 0, удаление происходит немедленно.

Uri

@dataclass
class Uri

Класс для создания URI-ссылки для хендлера с callback’ом.

str

required

ID плагина.

str

required

Команда.

dict[str, str]

Дополнительные аргументы, передающиеся в функцию callback’а.

Пример использования

plugin_id = "testplugin"
cmd_url = CactusUtils.Uri(plugin_id=plugin_id, command="test", kwargs={"message": "hello with love from cactus!"}).string()
... # данную ссылку можно вставлять куда хотите, работать будет из любого места

... # в классе плагина
@uri("test") # from cactuslib import uri
def test_uri_callback(self, message: str):
   ...

method create

@classmethod
def create(cls, plugin: BasePlugin, cmd: str, **kwargs) -> str

Создает экземпляр Uri, автоматически подставляя plugin_id=plugin.id и возвращая сразу строку с ссылкой.

Пример использования

cmd_url = CactusUtils.Uri.create(self, "test", message="hello with love from cactus!")
...

method string

def string(self) -> str

Возвращает сгенерированную ссылку формата tg://cactus/{plugin_id}/{command}?{urlencode(kwargs)}

decorator callback

@staticmethod
def callback(method: str)

Декоратор для создания callback функции на определенный метод.

str

required

Метод

Пример использования

... # класс плагина
@CactusUtils.Uri.callback("test")
def test_uri_callback(self, **kwargs):
    ...

MessageUri

class MessageUri(Uri)

Класс для создания URI-ссылки для хендлера с callback’ом, которая будет обрабатываться только в сообщениях. Всё то же самое, что и в Uri, но есть изменения:

/cactus/ заменяется на /cactusX/.
В callback функцию возвращается экземпляр CactusUtils.UriCallback с необходимыми данными первым аргументом.

Пример использования

plugin_id = "testplugin"
cmd_url = CactusUtils.MessageUri(plugin_id=plugin_id, command="test", kwargs={"message": "hello from message with love from cactus!"}).string()
# или CactusUtils.MessageUri.create(self, "test", message="hello from message with love from cactus!")
... # отправляете сообщение с данной ссылкой, её можно также внутри текста оставлять и будет работать как "кликабельная" кнопка.

... # в классе плагина
@CactusUtils.MessageUri.callback("test")
def test_message_uri_callback(self, params: CactusUtils.UriCallback, message: str):
   ...

decorator callback

@staticmethod
def callback(method: str, support_long_click: bool = False)

Декоратор для создания callback функции на определенный метод.

str

required

Метод

bool

default:"False"

Будет ли вызываться ваша функция, если было произведено длительное нажатие на ссылку (проверять можно через параметр long_press в UriCallback)На обычное нажатие не влияет.

Пример использования

... # класс плагина
@CactusUtils.Uri.callback("test")
def test_uri_callback(self, **kwargs):
    ...

Plugin (CactusModule)

class CactusModule(BasePlugin)

Базовый класс для плагинов с разными фичами.

Обязательно нужно наследовать свой класс плагина от данного класса, иначе система плагинов может работать неправильно.

CactusUtils

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

str version X.X.X

Минимальная необходимая версия CactusLib для работы вашего плагина. Если текущая версия меньше минимальной требуемой, плагин выдаст ошибку при загрузке.

dict[str, dict[str, str]]

Локализованные строки.

method open_plugin_settings

def open_plugin_settings(self)

Метод, открывающий экран с настройками плагина.

method string

def string(self, key: str, *args, default: Optional[str] = None, locale: str = None, **kwargs) -> str | Any

Метод, позволяющий получить значение из словаря strings по ключу и текущему языку.

methods log | debug | warn | info | error

def log(self, message: str) -> None: ...
def debug(self, message: str) -> None: ...
def warn(self, message: str) -> None: ...
def info(self, message: str) -> None: ...
def error(self, message: str) -> None: ...

Методы для логирования по уровню. На выход в logcat идёт лог формата: [level] [__id__] {message} ID плагина подставляется автоматически.

str

required

Текст лога

method answer

def answer(
    self, params,
    text: str, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    markup=None, **kwargs
)

Методы для отправки ответного сообщения по параметрам.

org.telegram.messenger.SendMessagesHelper$SendMessageParams

required

Объект с параметрами исходного сообщения.

str

required

Текст отправляемого сообщения.

bool

default:"True"

Разбирать ли текст на HTML-разметку или Markdown-разметку.

str

default:"HTML"

Режим парсинга. Может быть "HTML" или "MARKDOWN".

list[dict] | CactusUtils.Inline.Markup | ...

default:"None"

Объект с Inline клавиатурой.

Дополнительные параметры, которые передаются в CactusUtils.send_message

Inline

class Inline

Класс с методами для создания Inline-клавиатуры.

method CallbackData

def CallbackData(plugin_id: str, method: str, **kwargs) -> str

Создание данных для callback data параметра кнопки.

str

required

ID плагина (self.id в плагине)

str

Имя метода, который будет вызван при нажатии.

Дополнительные аргументы, которые будут переданы в функцию.

Пример кнопки с callback функцией

# Создаем кнопку с callback'ом
callback_data=CactusUtils.Inline.CallbackData(
    plugin_id=self.id,
    method="on_button_click",
    arg1="value1",
    arg2="value2",
    # ...
)

method Button

def Button(
    text: str, *,
    url: Optional[str] = None,
    callback_data: Optional[str] = None,
    query: Optional[str] = None,
    requires_password: Optional[bool] = None,
    copy: Optional[str] = None,
    **kwargs
) -> TLRPC.KeyboardButton

Создание объекта кнопки по параметрам.Обязательно должен быть указан один любой из аргументов после text.

str

required

Текст кнопки.

str

URL-адрес, который откроется при нажатии.

str

Строка с данными, которая будет отправлена обратно вашему плагину при нажатии. Это основной способ обработки нажатий.Получаем с помощью метода CallbackData

str

Строка, которая будет вставляться напрямую в поле ввода сообщения при нажатии на кнопку.

str

Текст, который будет скопирован в буфер обмена при нажатии на кнопку.

method to_json

def to_json(btn: TLRPC.KeyboardButton) -> dict

Возвращает словарь с данными кнопки для более удобной работы.

TLRPC.KeyboardButton

required

Кнопка

class Markup

class Markup:
    def __init__(
        self, is_global: bool = False,
        on_sent: Optional[Callable] = None,
        *args, **kwargs
    )

Класс для создания Inline-клавиатуры.

bool

default:"False"

Если True, то сообщение будет отправлено в чат с метаданными внутри текста сообщения. Это позволит увидеть всем пользователям с CactusLib данную клавиатуру.

callable

Функция, которая будет вызвана после отправки сообщения с клавиатурой и полной инициализации.

Если вы используете is_global=True, то данный параметр будет проигнорирован.

Опциональные аргументы, которые будут переданы в функцию on_sent.

method add_row

def add_row(*btns) -> "Markup"

Добавляет ряд кнопок к клавиатуре.В качестве аргумента можно приводить список, тогда все кнопки из него будут добавлены в ряд.Метод возвращает себя, то есть self для удобства.

dict | list[dict | TLRPC.KeyboardButton] | TLRPC.KeyboardButton

required

Кнопки :D

method to_url_with_data

def to_url_with_data() -> str

Создает ссылку с метаданными о текущей клавиатуре внутри. Данную ссылку в сообщении будет видеть CactusLib и создавать клавиатуру из данных в ссылке.Возвращает строку типа tg://cactus/mdata/{compressed_data}

method result

@property
def result() -> TLRPC.TL_replyInlineMarkup

Получение собранной клавиатуры в виде TLRPC объекта для дальнейшего использования.

class CallbackParams

@dataclass
class CallbackParams

Класс, который возвращается в callback функцию кнопки.

MessageObject

Объект сообщения, к которому привязана клавиатура.

ChatMessageCell

UI-элемент сообщения.

Optional[TLRPC.KeyboardButton]

default:"None"

Кнопка, на которую было произведено нажатие.

bool

Длительное нажатие на кнопку.

method edit (edit_message)

def edit_message(self, text: str, **kwargs) -> None

Изменяет сообщение по заданным параметрам.

str

required

Текст нового сообщения

Дополнительные параметры, которые передаются в CactusUtils.edit_message.

method edit_markup

def edit_markup(self, markup: Optional[Any] = None)

method delete (delete_message)

def delete_message(self) -> None

Удаляет сообщение.

decorator on_click

@classmethod
def on_click(cls, method: str, support_long_click: bool = False)

Создает из метода callback-функцию для кнопки с методом, совпадающим с переданным method параметром.

str

required

Метод

bool

default:"False"

Будет ли вызываться ваша функция, если было произведено длительное нажатие на кнопку (проверять можно через параметр is_long в CallbackParams)На обычное нажатие не влияет.

Пример использования

# ... в классе плагина
@CactusUtils.Inline.on_click("testbutton")
def test_button_callback(self, params: CactusUtils.Inline.CallbackParams):
    ...

HTML

class HTML

Все методы являются статичными и их можно вызывать без инициализации класса.

method parse

def parse(text: str, custom_emoji: int = 1) -> dict

str

required

Текст для парсинга HTML разметки.

int

default:"1"

required

Тип Premium-эмодзи для распознания и отправки.0 (NOT_PREMIUM) - убрать все премиум-эмодзи и оставить только обычные, которые были внутри тега.1 (TELEGRAM_PREMIUM) - разрешить обычные премиум эмодзи.2 (CACTUS_PREMIUM) - заменить все теги типа <emoji id=123456789>❤️</emoji> на <a href='tg://cactus/emoji/123456789'>❤️</a>, которые будут преобразовываться CactusLib’ом и видны всем, у кого также установлен соответствующий плагин.

Возвращает словарь с двумя ключами:

message (str)
entities (list[CactusUtils.RawEntity])

method unparse

def unparse(text: str, entities: list) -> str

str

required

Текст для распаковывания всех энтити

list[org.telegram.tgnet.TLRPC.MessageEntity]

required

Список со всеми entity текста.

Возвращает изначальную строку со всеми тегами.

Markdown

class Markdown

Все методы являются статичными и их можно вызывать без инициализации класса.

method parse

def parse(text: str, strict: bool = False, custom_emoji: int = 1) -> dict

str

required

Текст для парсинга Markdown разметки.

bool

default:"False"

int

default:"1"

required

Тип Premium-эмодзи для распознания и отправки.0 (NOT_PREMIUM) - убрать все премиум-эмодзи и оставить только обычные, которые были внутри тега.1 (TELEGRAM_PREMIUM) - разрешить обычные премиум эмодзи.2 (CACTUS_PREMIUM) - заменить все теги типа [❤️](123456789) на [❤️](tg://cactus/emoji/123456789), которые будут преобразовываться CactusLib’ом и видны всем, у кого также установлен соответствующий плагин.

Возвращает словарь с двумя ключами:

message (str)
entities (list[CactusUtils.RawEntity])

method unparse

def unparse(text: str, entities: list) -> str

str

required

Текст для распарсивания всех энтити

list[org.telegram.tgnet.TLRPC.MessageEntity]

required

Список со всеми entity текста.

Возвращает изначальную строку со всеми delim’ами.

RawEntity

@dataclass
class RawEntity

TLEntityType

required

Тип entity

int

required

Позиция начала текста

int

required

Длина текста внутри тега

str

Язык программирования.Используется в TLRPC.TL_messageEntityPre при type == TLEntityType.PRE.

str

Ссылка.Используется в TLRPC.TL_messageEntityTextUrl при type == TLEntityType.TEXT_LINK.

int

ID Premium-эмодзи.Используется в TLRPC.TL_messageEntityCustomEmoji при type == TLEntityType.CUSTOM_EMOJI

bool

Добавить ли возможность скрывать цитату.Используется в TLRPC.TL_messageEntityBlockquote при type == TLEntityType.BLOCKQUOTE

method to_tlrpc_object

def to_tlrpc_object(self) -> TLRPC.MessageEntity

Возвращает созданный объект типа TLRPC.MessageEntity.

TLEntityType

class TLEntityType(Enum)

TLRPC.TL_messageEntityCode

TLRPC.TL_messageEntityPre

TLRPC.TL_messageEntityStrike

TLRPC.TL_messageEntityTextUrl

Tentity, TLRPC.TL_messageEntityBold

TLRPC.TL_messageEntityItalic

TLRPC.TL_messageEntityUnderline

TLRPC.TL_messageEntitySpoiler

TLRPC.TL_messageEntityCustomEmoji

TLRPC.TL_messageEntityBlockquote

method from_

@classmethod
def _from(cls, entity: TLRPC.MessageEntity) -> TLEntityType

Возвращает тип на основе переданного entity.

Начало

Пользователям

Разработка

Плагины

class CactusUtils

Методы

Классы

​Методы

​Классы

Методы

Классы