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

Методы

Все методы являются статичными, то есть не требуют инициализации класса и можно вызывать напрямую: CactusUtils.copy_to_clipboard("Hello, exteraGram!")
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")
def all_plugins() -> list[BasePlugin | CactusUtils.Plugin]
Возвращает список классов всех плагинов из PluginsController.pluginInstances.
def plugin(plugin_id: str) -> BasePlugin | CactusUtils.Plugin
Возвращает класс плагина по его ID.
def gen(java_class: JavaClass, method_name: str, return_value: bool = False) -> type
Этот метод генерирует новый прокси-класс, который расширяет данный java_class и переопределяет определенный метод.
java_class
type(jclass("java.lang.Object"))
required
Класс-интерфейс для создания своего класс через dynamic_proxy.
method_name
str
required
Имя метода, который будет переопределен в прокси-классе.
return_value
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")
def gen2(java_class: JavaClass, return_value: bool = False, **methods) -> type
Этот метод похож на gen, но позволяет переопределять несколько методов в сгенерированном прокси-классе.
java_class
type(jclass("java.lang.Object"))
required
Класс-интерфейс для создания своего класс через dynamic_proxy.
return_value
bool
default:"False"
Возвращать ли значение ваших функций в ответ в переопределенных методах.
**methods
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
})()
def compress_and_encode(data: Union[bytes, str], level: int = 7) -> str
Метод для сжатия данных. Оборачивает в base64 сжатые через zlib данные.
data
bytes | str
required
Данные для упаковывания.
level
int
default:"7"
Уровень сжатия. Подробнее
Пример использования
compressed = CactusUtils.compress_and_encode("hello from [dev-cat] den!")
# eNrLSM3JyVdIK8rPVYhOSS3TTU4siVVISc1TBAB3zAjd
def decode_and_decompress(encoded_data: Union[bytes, str]) -> bytes
Метод для распаковки данных, сжатых с помощью метода decode_and_decompress.
data
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!"
def pluralization_string(number: int, words: List[str]) -> str
Возвращает множественную строку, основанную на заданном числе.
number
int
required
Число, определяющее форму множественного числа.
words
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 апельсинов
def escape_html(text: str) -> str
Экранирует html-теги
text
str
required
Текст для экранирования
Пример использования
escaped = CactusUtils.escape_html("Test <html> string!")
# Test &lt;html&gt; string!
def copy_to_clipboard(text: str) -> None
Копирует заданный текст в буфер обмена и выводит информацию об этом
text
str
required
Текст для копирования.
def prefix() -> str
Возвращает текущий префикс системы команд в CactusLib.
def get_locale() -> str
Возвращает текущую локаль. Например, en или ru.
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}
message
str
required
Текст лога
level
str
Уровень логов. DEBUG | INFO | WARN | ERROR Одноименные методы автоматически выставляют данный параметр.
__id__
str
required
ID плагина.
def get_logs(
    __id__: Optional[str] = None,
    times: Optional[int] = None,
    lvl: Optional[str] = None,
    as_list: bool = False
) -> list[str] | str
Метод для получения логов по ID, уровню и времени.
def array_list(*args) -> ArrayList
Метод для легкого создания ArrayList. Можно привести список в качестве первого и единственного аргумента, тогда он преобразует данный список в ArrayList.
Пример использования
plist = ["test", "values", "123"]
alist = CactusUtils.array_list(plist)

alist2 = CactusUtils.array_list(
  "first",
  "and",
  "second",
  "value",
)
def edit_message(
    message_object: MessageObject,
    text: str, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    markup: Any = None, **kwargs
)
Метод для редактирования сообщения.
message_object
org.telegram.messenger.MessageObject
required
Объект изменяемого сообщения.
text
str
required
Новый текст сообщения.
parse_message
bool
default:"True"
Разбирать ли текст на HTML-разметку или Markdown-разметку.
parse_mode
str
default:"HTML"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
markup
list[dict] | CactusUtils.Inline.Markup | ...
default:"None"
**kwargs
Дополнительные параметры, которые передаются в editMessage
Добавлять ли предпросмотр ссылке (наверное).Используется в реквесте TLRPC.TL_messages_editMessage() в качестве параметра no_webpage:
req.no_webpage = !searchLinks
fragment
org.telegram.ui.ActionBar.BaseFragment
default:"None"
Фрагмент. Рекомендуется указывать fragment=client_utils.get_last_fragment().
scheduleDate
int
default:"0"
Schedule datetime timestamp.
def edit_message_markup(cell: ChatMessageCell, markup: Optional[Any] = None)
Метод для редактирования Inline-клавиатуры сообщения.
cell
org.telegram.ui.Cells.ChatMessageCell
required
UI-Объект сообщения, который нужно отредактировать.
markup
list[dict] | CactusUtils.Inline.Markup | ...
default:"None"
Объект с Inline клавиатурой (None для удаления клавиатуры у сообщения).
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 кнопки, а также можно отследить отправку сообщения.
peer
int
required
ID чата, в который нужно отправить сообщение.
text
str
required
Текст отправляемого сообщения.
parse_message
bool
default:"True"
Разбирать ли текст на HTML-разметку или Markdown-разметку.
parse_mode
str
default:"HTML"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
markup
list[dict] | CactusUtils.Inline.Markup | ...
default:"None"
on_sent
Callable[[CactusUtils.Inline.CallbackParams], None]
default:"None"
Функция, которая будет вызвана после отправки сообщения. Принимает один аргумент — объект CactusUtils.Inline.CallbackParams (button=None).
**kwargs
Дополнительные параметры, которые передаются в send_message
location
org.telegram.tgnet.TLRPC.MessageMedia
photo
org.telegram.tgnet.TLRPC.TL_photo
videoEditedInfo
org.telegram.messenger.VideoEditedInfo
user
org.telegram.tgnet.TLRPC.User
document
org.telegram.tgnet.TLRPC.TL_document
game
org.telegram.tgnet.TLRPC.TL_game
poll
org.telegram.tgnet.TLRPC.TL_messageMediaPoll
todo
Torg.telegram.tgnet.LRPC.TL_messageMediaToDo
invoice
TLRPC.TL_messageMediaInvoice
mediaWebPage
TLRPC.TL_messageMediaWebPage
path
String
replyToMsg
org.telegram.messenger.MessageObject
replyToTopMsg
org.telegram.messenger.MessageObject
webpage
TLRPC.WebPage
retryMessageObject
org.telegram.messenger.MessageObject
notify
bool
default:"True"
scheduleDate
int
default:"0"
ttl
int
default:"0"
parentObject
java.lang.Object
sendAnimationData
org.telegram.messenger.MessageObject.SendAnimationData
updateStickersOrder
bool
default:"False"
hasMediaSpoilers
bool
default:"False"
replyToStoryItem
org.telegram.tgnet.tl.TL_stories.StoryItem
sendingStory
org.telegram.tgnet.tl.TL_stories.StoryItem
replyQuote
ChatActivity.ReplyQuote
quick_reply_shortcut
String
quick_reply_shortcut_id
int
effect_id
long
default:"not set"
invert_media
bool
default:"False"
sendingHighQuality
bool
default:"?"
suggestionParams
MessageSuggestionParams
def send_file(
    peer: int, path: str,
    caption: Optional[str] = None, *,
    parse_markdown: bool = True,
    parse_mode: str = "HTML",
    **kwargs
)
Отправляет документ (файл) с возможностью добавить форматированную подпись.
peer
int
required
ID чата.
path
str
required
Путь к файлу
caption
str
default:"None"
Текст-описание к файлу.
parse_message
bool
default:"True"
Разбирать ли текст на HTML-разметку или Markdown-разметку.
parse_mode
str
default:"HTML"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
**kwargs
Дополнительные параметры, которые передаются в send_message
Параметры, которые передаются в метод SendMessagesHelper.prepareSendingDocumentInternal
mime
str
default:"text/plain"
MIME type of the file
replyToMsg
MessageObject
default:"None"
Message to reply to (maybe params.replyToMsg)
replyToTopMsg
MessageObject
default:"None"
top message to reply to (maybe params.replyToTopMsg)
storyItem
TL_stories.StoryItem
default:"None"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
quote
ChatActivity.ReplyQuote
default:"None"
Quote
notify
bool
default:"True"
Send message with notification
editingMessageObject
org.telegram.messenger.MessageObject
default:"None"
Message to edit/add file
scheduleDate
int
default:"0"
Schedule datetime
quickReplyShortcut
str
default:"None"
Quick reply shortcut
quickReplyShortcutId
int
default:"0"
Quick reply shortcut ID
effect_id
int
default:"0"
Message effect ID
invertMedia
bool
default:"False"
Invert media
payStars
int
default:"0"
Pay stars
accountInstance
org.telegram.messenger.AccountInstance
default:"client_utils.get_account_instance()"
Current Account instance
entities
ArrayList<TLRPC.MessageEntity>
default:"False"
Message caption entities (Если parse_message=True, данный параметр будет сгенерирован автоматически)
groupId
long[]
default:"jarray(jlong)([0])"
Group ID
isGroupFinal
bool
default:"True"
Is final document in group
docType
Integer[]
default:"jarray(Integer)([0])"
Doc type ID
monoForumPeerId
int
default:"0"
MonoForum peer ID
suggestionParams
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)
def send_files(
    peer: int, paths: List[str],
    caption: Optional[str] = None, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    **kwargs
)
Отправляет документы (файлы) с возможностью добавить форматированную подпись к первому из них.
peer
int
required
ID чата.
paths
list[str]
required
Пути к файлам.
caption
str
default:"None"
Текст-описание к файлу.
parse_message
bool
default:"True"
Разбирать ли текст на HTML-разметку или Markdown-разметку.
parse_mode
str
default:"HTML"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
**kwargs
Дополнительные параметры, которые передаются в send_message
Параметры, которые передаются в метод SendMessagesHelper.prepareSendingDocumentInternal
mime
str
default:"text/plain"
MIME type of the file
replyToMsg
MessageObject
default:"None"
Message to reply to (maybe params.replyToMsg)
replyToTopMsg
MessageObject
default:"None"
top message to reply to (maybe params.replyToTopMsg)
storyItem
TL_stories.StoryItem
default:"None"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
quote
ChatActivity.ReplyQuote
default:"None"
Quote
notify
bool
default:"True"
Send message with notification
editingMessageObject
org.telegram.messenger.MessageObject
default:"None"
Message to edit/add file
scheduleDate
int
default:"0"
Schedule datetime
quickReplyShortcut
str
default:"None"
Quick reply shortcut
quickReplyShortcutId
int
default:"0"
Quick reply shortcut ID
effect_id
int
default:"0"
Message effect ID
invertMedia
bool
default:"False"
Invert media
payStars
int
default:"0"
Pay stars
accountInstance
org.telegram.messenger.AccountInstance
default:"client_utils.get_account_instance()"
Current Account instance
entities
ArrayList<TLRPC.MessageEntity>
default:"False"
Message caption entities (Если parse_message=True, данный параметр будет сгенерирован автоматически)
groupId
long[]
default:"jarray(jlong)([0])"
Group ID
isGroupFinal
bool
default:"True"
Is final document in group
docType
Integer[]
default:"jarray(Integer)([0])"
Doc type ID
monoForumPeerId
int
default:"0"
MonoForum peer ID
suggestionParams
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)

Классы

class JsonDB(dict)
Класс для управления данными в JSON-файле, наследующий от dict. Он автоматически загружает данные из указанного файла при инициализации и сохраняет изменения при вызове методов, таких как set, pop или update_from.
loc
str
required
Путь к JSON-файлу.
def _load(self) -> Dict[str, Any]
Загружает данные из JSON-файла, указанного при инициализации. Если файл не существует, возвращает пустой словарь.
def save(self) -> None
Сохраняет текущее состояние словаря в JSON-файл.
def set(self, key: str, value: Any) -> None
Устанавливает значение для заданного ключа, а затем сохраняет изменения в JSON-файл.
key
str
required
Ключ для установки.
value
Any
required
Значение, которое будет связано с ключом.
def get(self, key: str, default=None)
Извлекает значение, связанное с заданным ключом. Работает идентично стандартному методу dict.get().
key
str
required
Ключ для извлечения.
default
Any
default:"None"
Значение, которое будет возвращено, если ключ не найден.
def pop(self, key: str) -> Any
Удаляет указанный ключ и связанное с ним значение из словаря, а затем сохраняет изменения в JSON-файл.
key
str
required
Ключ для удаления.
def reset(self) -> None
Очищает все данные из словаря и JSON-файла.
def update_from(self, **kwargs)
Обновляет словарь парами ключ-значение из kwargs, а затем сохраняет изменения в JSON-файл.
@dataclass
class Command
Класс, который возвращается в callback функцию команде.
command
str
Имя команды или псевдоним, который был использован.
args
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"]
raw_args
str
Все, что идет после команды, в виде одной строки.
text
str
Полный текст исходного сообщения.
params
org.telegram.messenger.SendMessagesHelper$SendMessageParams
Объект с параметрами исходного сообщения (peer, replyToMsg и т.д.).
account
int
Текущий аккаунт
html() -> str
func
Функция, возвращающая текст исходного сообщения с HTML-разметкой.
markdown() -> str
func
Функция, возвращающая текст исходного сообщения с Markdown-разметкой.
def answer(text: str, **kwargs)
Отправляет ответное сообщение по заданным параметрам. replyToMsg и replyToTopMsg подставляются автоматически.
text
str
required
Текст нового сообщения
kwargs
Дополнительные параметры, которые передаются в CactusUtils.send_message.
def html(self) -> str
Функция, возвращающая текст исходного сообщения с HTML-разметкой.Возвращает CactusUtils.HTML.unparse(self.text, list(self.params.entities.toArray()))
def markdown(self) -> str
Функция, возвращающая текст исходного сообщения с Markdown-разметкой.Возвращает CactusUtils.Markdown.unparse(self.text, list(self.params.entities.toArray()))
@dataclass
class UriCallback
Класс, который возвращается в callback функцию MessageUri ссылки.
message
MessageObject
Объект сообщения, к которому привязана клавиатура.
cell
ChatMessageCell
UI-элемент сообщения.
method
str
Метод из ссылки, который сработал.
raw_url
str
Ссылка, на которую было произведено нажатие
long_press
bool
Длительное нажатие на кнопку.
def edit_message(self, text: str, **kwargs) -> None
Изменяет сообщение по заданным параметрам.
text
str
required
Текст нового сообщения
kwargs
Дополнительные параметры, которые передаются в CactusUtils.edit_message.
def edit_markup(self, markup: Optional[Any] = None)
Изменяет Inline-клавиатуру текущему сообщению, автоматически подставляя в CactusUtils.edit_message_markup UI-объект сообщения.
def delete_message(self) -> None
Удаляет сообщение.
class Telegram
Класс Telegram предоставляет статические методы для взаимодействия с Telegram API, включая отправку запросов TLRPC, поиск сообщений и получение информации о пользователях, чатах, каналах и стикерпаках.
class Result:
Внутренний класс, используемый для хранения результатов асинхронных запросов TLRPC.
req_id
int
Идентификатор запроса. Уникальный номер, присвоенный отправленному запросу.
response
TLObject
Объект ответа от Telegram API. Содержит данные, полученные в случае успешного выполнения запроса.
error
TLRPC.TL_error
Объект ошибки TLRPC. Содержит информацию об ошибке, если запрос завершился неудачей.
class TLRPCException(Exception):
Исключение, вызываемое при получении ошибки TLRPC от Telegram API.
req_id
int
required
Идентификатор запроса. Уникальный номер запроса, который вызвал данную ошибку.
error
TLRPC.TL_error
required
Объект ошибки TLRPC. Полный объект ошибки, возвращенный Telegram API.
code
int
Код ошибки. Числовой код ошибки TLRPC.
text
str
Текст ошибки. Подробное текстовое описание ошибки TLRPC.
@staticmethod
def tlrpc_object(request_class, **kwargs)
Создает объект запроса TLRPC, устанавливая предоставленные аргументы как атрибуты класса запроса. Это удобный способ инициализировать объекты запросов.
request_class
Any
required
Класс запроса TLRPC. Например, TLRPC.TL_messages_search для поиска сообщений.
**kwargs
Any
Аргументы запроса. Именованные аргументы, которые будут установлены как атрибуты создаваемого объекта запроса.
@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. Позволяет выбрать синхронное или асинхронное выполнение, а также настроить обработку ошибок и тайм-аутов.
req
Any
required
Объект запроса TLRPC. Сам запрос, который вы хотите отправить (например, TLRPC.TL_messages_getMessages).
callback
Optional[callable]
default:"None"
Функция обратного вызова. Если wait_response равно False, эта функция будет вызвана с результатом и ошибкой после получения ответа.
wait_response
bool
default:"True"
Ожидать ли ответ. Если True, метод будет блокироваться до получения ответа и возвращать объект Result. Если False, метод вернет идентификатор запроса немедленно.
timeout
int
default:"10"
Тайм-аут. Максимальное время в секундах, которое метод будет ждать ответа, если wait_response равно True.
raise_errors
bool
default:"True"
Вызывать ли исключения. Если True и запрос завершился ошибкой, будет вызвано исключение TLRPCException. Если False, ошибка будет возвращена внутри объекта Result.
class SearchFilter(Enum):
Перечисление, представляющее различные фильтры для поиска сообщений. Используется для уточнения типа сообщений, которые вы ищете.
GIF
str
GIF. Фильтр для поиска GIF-изображений.
MUSIC
str
MUSIC. Фильтр для поиска музыкальных файлов.
CHAT_PHOTOS
str
CHAT_PHOTOS. Фильтр для поиска фотографий, отправленных в чат.
PHOTOS
str
PHOTOS. Фильтр для поиска любых фотографий.
URL
str
URL. Фильтр для поиска сообщений, содержащих URL-адреса.
DOCUMENT
str
DOCUMENT. Фильтр для поиска документов.
PHOTO_VIDEO
str
PHOTO_VIDEO. Фильтр для поиска фотографий и видео.
PHOTO_VIDEO_DOCUMENT
str
PHOTO_VIDEO_DOCUMENT. Фильтр для поиска фотографий, видео и документов.
GEO
str
GEO. Фильтр для поиска сообщений с геолокациями.
PINNED
str
PINNED. Фильтр для поиска закрепленных сообщений.
MY_MENTIONS
str
MY_MENTIONS. Фильтр для поиска сообщений, в которых упомянут текущий пользователь.
ROUND_VOICE
str
ROUND_VOICE. Фильтр для поиска голосовых круглых сообщений.
CONTACTS
str
CONTACTS. Фильтр для поиска сообщений с контактами.
VOICE
str
VOICE. Фильтр для поиска голосовых сообщений.
VIDEO
str
VIDEO. Фильтр для поиска видеосообщений.
PHONE_CALLS
str
PHONE_CALLS. Фильтр для поиска информации о телефонных звонках.
ROUND_VIDEO
str
ROUND_VIDEO. Фильтр для поиска видео круглых сообщений.
EMPTY
str
EMPTY. Пустой фильтр, не применяет специфических ограничений по типу.
def to_TLRPC_object(self)
Преобразует элемент перечисления SearchFilter в соответствующий объект TLRPC-фильтра сообщений, который можно использовать в запросах к Telegram API.
@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]
Осуществляет поиск сообщений в указанном диалоге, позволяя фильтровать по запросу, отправителю, смещению и типу содержимого.
dialog_id
int
required
Идентификатор диалога. ID чата, пользователя или канала, где будет производиться поиск.
query
Optional[str]
default:"None"
Текст запроса. Строка для поиска в содержимом сообщений.
from_id
Optional[int]
default:"None"
Идентификатор отправителя. ID пользователя, от которого должны быть получены сообщения.
offset_id
int
default:"0"
ID смещения. Сообщения будут возвращены, начиная с этого ID (или после него).
limit
int
default:"20"
Лимит. Максимальное количество сообщений, которое будет возвращено.
reply_message_id
Optional[int]
default:"None"
ID сообщения-ответа. Если указано, поиск будет ограничен сообщениями, которые являются ответами на это конкретное сообщение.
top_message_id
Optional[int]
default:"None"
ID верхнего сообщения. Используется в контексте тематических групп (форумов) для указания ID главного сообщения темы.
filter
SearchFilter
default:"SearchFilter.EMPTY"
Фильтр поиска. Тип содержимого, по которому нужно фильтровать сообщения (например, SearchFilter.PHOTOS).
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send, такие как wait_response или timeout.
@staticmethod
def get_user(user_id: int)
Получает объект пользователя по его идентификатору.
user_id
int
required
Идентификатор пользователя. Уникальный ID пользователя, информацию о котором вы хотите получить.
@staticmethod
def input_user(user_id: int)
Получает объект InputUser по идентификатору пользователя. Этот объект используется в других запросах к Telegram API, которым требуется ссылка на пользователя.
user_id
int
required
Идентификатор пользователя. Уникальный ID пользователя.
@staticmethod
def peer(peer_id: int)
Получает объект Peer по идентификатору пира (пользователя, чата или канала). Peer представляет собой общую сущность в Telegram.
peer_id
int
required
Идентификатор пира. ID пользователя, чата или канала.
@staticmethod
def input_peer(peer_id: int)
Получает объект InputPeer по идентификатору пира (пользователя, чата или канала). InputPeer — это объект, который API использует для идентификации целевого диалога.
peer_id
int
required
Идентификатор пира. ID пользователя, чата или канала.
@classmethod
def get_sticker_set_by_short_name(cls, short_name: str, **kwargs)
Получает информацию о наборе стикеров по его короткому имени (например, t.me/addstickers/example).
short_name
str
required
Короткое имя набора стикеров. Имя, используемое в ссылках для добавления стикеров.
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.
@classmethod
def get_chat(cls, chat_id: int, **kwargs)
Получает информацию о групповом чате по его идентификатору.
chat_id
int
required
Идентификатор чата. ID группового чата, информацию о котором вы хотите получить.
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.
@classmethod
def get_channel(cls, channel_id: int, **kwargs) -> int
Получает информацию о канале по его идентификатору.
channel_id
int
required
Идентификатор канала. ID канала, информацию о котором вы хотите получить.
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.
@classmethod
def get_user_photos(cls, user_id: int, limit: int = 1, **kwargs)
Получает фотографии профиля пользователя.
user_id
int
required
Идентификатор пользователя. ID пользователя, чьи фотографии профиля вы хотите получить.
limit
int
default:"1"
Лимит. Максимальное количество фотографий профиля для получения. По умолчанию 1.
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.
@classmethod
def get_channel_messages(
    cls, channel: Union[int, str, Any], ids: Union[List[int], int], **kwargs
)
Получает конкретные сообщения из канала по их идентификаторам.
ВНИМАНИЕ: Этот метод может не возвращать ожидаемый результат в полной мере. Если у вас есть информация или предложения по исправлению, пожалуйста, свяжитесь с @chillden4ik в Telegram.
channel
Union[int, str, Any]
required
Канал. Может быть передан как:
  • целое число: ID канала.
  • строка: короткое имя канала (username), которое будет автоматически разрешено.
  • любой другой объект: объект канала, который может быть преобразован в InputPeer или TL_inputChannel.
ids
Union[List[int], int]
required
Идентификаторы сообщений. Может быть одним целым числом (ID одного сообщения) или списком целых чисел (ID нескольких сообщений).
**kwargs
Any
Дополнительные параметры. Любые другие параметры, которые будут переданы базовому методу send.
@classmethod
def delete_messages(cls, ids: Union[List[int], int], chat_id: int, topic_id: int = 0, for_all: bool = True)
Удаляет одно или несколько сообщений в указанном чате.
ids
Union[List[int], int]
required
Идентификаторы сообщений. ID одного сообщения или список ID сообщений для удаления.
chat_id
int
required
Идентификатор чата. ID чата, из которого будут удалены сообщения.
topic_id
int
default:"0"
Идентификатор топика. Если чат является форумом, это ID топика, из которого удаляются сообщения. По умолчанию 0 для обычных чатов.
for_all
bool
default:"True"
Удалить для всех. Если True, сообщения будут удалены для всех участников чата. Если False, сообщения будут удалены только для текущего пользователя.
@classmethod
def resolve_channel(cls, username: str, *, callback: Optional[Callable[[Any], None]] = None)
Разрешает короткое имя канала (username, например, @telegram) в полный объект канала. Может работать как синхронно (по умолчанию), так и асинхронно через обратный вызов.
username
str
required
Короткое имя канала. Username канала, который вы хотите разрешить (без символа @).
callback
Optional[Callable[[Any], None]]
default:"None"
Функция обратного вызова. Если предоставлена, метод будет работать асинхронно, и эта функция будет вызвана с разрешенным объектом канала.
class FileSystem
Вспомогательный класс для управления файлами и директориями, предоставляющий методы для работы с базовыми, кеш- и временными директориями, а также для чтения и записи содержимого файлов. Все методы в этом классе являются статическими.
@classmethod
def basedir(cls, *path: str)
Возвращает базовую директорию приложения. Если предоставлены аргументы path, то будут созданы поддиректории внутри базовой директории, если они не существуют, и будет возвращен объект File для самого глубокого указанного пути.
*path
str
Необязательные компоненты пути для добавления к базовой директории.
@classmethod
def cachedir(cls, *path: str)
Возвращает директорию внешнего кеша приложения. Если предоставлены аргументы path, то будут созданы поддиректории внутри директории кеша, если они не существуют, и будет возвращен объект File для самого глубокого указанного пути.
*path
str
Необязательные компоненты пути для добавления к директории кеша.
@classmethod
def tempdir(cls)
Возвращает временную директорию специально для cactuslib_temp_files внутри директории кеша. Создает эту директорию, если она еще не существует.
@classmethod
def get_file_content(cls, file_path, mode: str = "rb")
Читает и возвращает содержимое файла.
file_path
str
required
Путь к файлу.
mode
str
default:"rb"
Режим открытия файла (например, &quot;rb&quot; для чтения бинарных данных, &quot;r&quot; для чтения текстовых данных).
@classmethod
def get_temp_file_content(
    cls, filename: str, mode: str = "rb", delete_after: int = 0
)
Читает и возвращает содержимое файла, расположенного во временной директории. При желании файл может быть запланирован на удаление через указанное количество секунд.
filename
str
required
Имя файла во временной директории.
mode
str
default:"rb"
Режим открытия файла (например, &quot;rb&quot; для чтения бинарных данных, &quot;r&quot; для чтения текстовых данных).
delete_after
int
default:"0"
Количество секунд, по истечении которых файл должен быть удален. Если 0, файл не удаляется автоматически.
@classmethod
def write_file(cls, file_path, content, mode: str = "wb")
Записывает содержимое в указанный файл.
file_path
str
required
Путь к файлу.
content
Any
required
Содержимое для записи в файл.
mode
str
default:"wb"
Режим открытия файла (например, &quot;wb&quot; для записи бинарных данных, &quot;w&quot; для записи текстовых данных).
@classmethod
def write_temp_file(
    cls, filename: str, content, mode="wb", delete_after: int = 0
)
Записывает содержимое в файл во временной директории. При желании файл может быть запланирован на удаление через указанное количество секунд.
filename
str
required
Имя файла для создания во временной директории.
content
Any
required
Содержимое для записи в файл.
mode
str
default:"wb"
Режим открытия файла (например, &quot;wb&quot; для записи бинарных данных, &quot;w&quot; для записи текстовых данных).
delete_after
int
default:"0"
Количество секунд, по истечении которых файл должен быть удален. Если 0, файл не удаляется автоматически.
@classmethod
def delete_file_after(cls, file_path, seconds: int = 0)
Удаляет файл после указанной задержки. Если seconds равно 0, файл удаляется немедленно.
file_path
str
required
Путь к файлу для удаления.
seconds
int
default:"0"
Количество секунд ожидания перед удалением файла. Если 0, удаление происходит немедленно.
@dataclass
class Uri
Класс для создания URI-ссылки для хендлера с callback’ом.
plugin_id
str
required
ID плагина.
command
str
required
Команда.
kwargs
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):
   ...
@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!")
...
def string(self) -> str
Возвращает сгенерированную ссылку формата tg://cactus/{plugin_id}/{command}?{urlencode(kwargs)}
@staticmethod
def callback(method: str)
Декоратор для создания callback функции на определенный метод.
method
str
required
Метод
Пример использования
... # класс плагина
@CactusUtils.Uri.callback("test")
def test_uri_callback(self, **kwargs):
    ...
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):
   ...
@staticmethod
def callback(method: str, support_long_click: bool = False)
Декоратор для создания callback функции на определенный метод.
method
str
required
Метод
support_long_click
bool
default:"False"
Будет ли вызываться ваша функция, если было произведено длительное нажатие на ссылку (проверять можно через параметр long_press в UriCallback)На обычное нажатие не влияет.
Пример использования
... # класс плагина
@CactusUtils.Uri.callback("test")
def test_uri_callback(self, **kwargs):
    ...
class CactusModule(BasePlugin)
Базовый класс для плагинов с разными фичами.
Обязательно нужно наследовать свой класс плагина от данного класса, иначе система плагинов может работать неправильно.
utils
CactusUtils
Вы всегда можете обратиться к утилитам с помощью self.utils
__min_lib_version__
str version X.X.X
Минимальная необходимая версия CactusLib для работы вашего плагина. Если текущая версия меньше минимальной требуемой, плагин выдаст ошибку при загрузке.
strings
dict[str, dict[str, str]]
def open_plugin_settings(self)
Метод, открывающий экран с настройками плагина.
def string(self, key: str, *args, default: Optional[str] = None, locale: str = None, **kwargs) -> str | Any
Метод, позволяющий получить значение из словаря strings по ключу и текущему языку.
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 плагина подставляется автоматически.
message
str
required
Текст лога
def answer(
    self, params,
    text: str, *,
    parse_message: bool = True,
    parse_mode: str = "HTML",
    markup=None, **kwargs
)
Методы для отправки ответного сообщения по параметрам.
params
org.telegram.messenger.SendMessagesHelper$SendMessageParams
required
Объект с параметрами исходного сообщения.
text
str
required
Текст отправляемого сообщения.
parse_message
bool
default:"True"
Разбирать ли текст на HTML-разметку или Markdown-разметку.
parse_mode
str
default:"HTML"
Режим парсинга. Может быть "HTML" или "MARKDOWN".
markup
list[dict] | CactusUtils.Inline.Markup | ...
default:"None"
**kwargs
Дополнительные параметры, которые передаются в CactusUtils.send_message
class Inline
Класс с методами для создания Inline-клавиатуры.
def CallbackData(plugin_id: str, method: str, **kwargs) -> str
Создание данных для callback data параметра кнопки.
plugin_id
str
required
ID плагина (self.id в плагине)
method
str
Имя метода, который будет вызван при нажатии.
**kwargs
Дополнительные аргументы, которые будут переданы в функцию.
Пример кнопки с callback функцией
# Создаем кнопку с callback'ом
callback_data=CactusUtils.Inline.CallbackData(
    plugin_id=self.id,
    method="on_button_click",
    arg1="value1",
    arg2="value2",
    # ...
)
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.
text
str
required
Текст кнопки.
url
str
URL-адрес, который откроется при нажатии.
callback_data
str
Строка с данными, которая будет отправлена обратно вашему плагину при нажатии. Это основной способ обработки нажатий.Получаем с помощью метода CallbackData
query
str
Строка, которая будет вставляться напрямую в поле ввода сообщения при нажатии на кнопку.
copy
str
Текст, который будет скопирован в буфер обмена при нажатии на кнопку.
def to_json(btn: TLRPC.KeyboardButton) -> dict
Возвращает словарь с данными кнопки для более удобной работы.
btn
TLRPC.KeyboardButton
required
Кнопка
class Markup:
    def __init__(
        self, is_global: bool = False,
        on_sent: Optional[Callable] = None,
        *args, **kwargs
    )
Класс для создания Inline-клавиатуры.
is_global
bool
default:"False"
Если True, то сообщение будет отправлено в чат с метаданными внутри текста сообщения. Это позволит увидеть всем пользователям с CactusLib данную клавиатуру.
on_sent
callable
Функция, которая будет вызвана после отправки сообщения с клавиатурой и полной инициализации.
Если вы используете is_global=True, то данный параметр будет проигнорирован.
args, kwargs
Опциональные аргументы, которые будут переданы в функцию on_sent.
def add_row(*btns) -> "Markup"
Добавляет ряд кнопок к клавиатуре.В качестве аргумента можно приводить список, тогда все кнопки из него будут добавлены в ряд.Метод возвращает себя, то есть self для удобства.
*btns
dict | list[dict | TLRPC.KeyboardButton] | TLRPC.KeyboardButton
required
Кнопки :D
def to_url_with_data() -> str
Создает ссылку с метаданными о текущей клавиатуре внутри. Данную ссылку в сообщении будет видеть CactusLib и создавать клавиатуру из данных в ссылке.Возвращает строку типа tg://cactus/mdata/{compressed_data}
@property
def result() -> TLRPC.TL_replyInlineMarkup
Получение собранной клавиатуры в виде TLRPC объекта для дальнейшего использования.
@dataclass
class CallbackParams
Класс, который возвращается в callback функцию кнопки.
message
MessageObject
Объект сообщения, к которому привязана клавиатура.
cell
ChatMessageCell
UI-элемент сообщения.
button
Optional[TLRPC.KeyboardButton]
default:"None"
Кнопка, на которую было произведено нажатие.
is_long
bool
Длительное нажатие на кнопку.
def edit_message(self, text: str, **kwargs) -> None
Изменяет сообщение по заданным параметрам.
text
str
required
Текст нового сообщения
kwargs
Дополнительные параметры, которые передаются в CactusUtils.edit_message.
def edit_markup(self, markup: Optional[Any] = None)
Изменяет Inline-клавиатуру текущему сообщению, автоматически подставляя в CactusUtils.edit_message_markup UI-объект сообщения.
def delete_message(self) -> None
Удаляет сообщение.
@classmethod
def on_click(cls, method: str, support_long_click: bool = False)
Создает из метода callback-функцию для кнопки с методом, совпадающим с переданным method параметром.
method
str
required
Метод
support_long_click
bool
default:"False"
Будет ли вызываться ваша функция, если было произведено длительное нажатие на кнопку (проверять можно через параметр is_long в CallbackParams)На обычное нажатие не влияет.
Пример использования
# ... в классе плагина
@CactusUtils.Inline.on_click("testbutton")
def test_button_callback(self, params: CactusUtils.Inline.CallbackParams):
    ...
class HTML
Все методы являются статичными и их можно вызывать без инициализации класса.
def parse(text: str, custom_emoji: int = 1) -> dict
text
str
required
Текст для парсинга HTML разметки.
custom_emoji
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])
def unparse(text: str, entities: list) -> str
text
str
required
Текст для распаковывания всех энтити
entities
list[org.telegram.tgnet.TLRPC.MessageEntity]
required
Список со всеми entity текста.
Возвращает изначальную строку со всеми тегами.
class Markdown
Все методы являются статичными и их можно вызывать без инициализации класса.
def parse(text: str, strict: bool = False, custom_emoji: int = 1) -> dict
text
str
required
Текст для парсинга Markdown разметки.
strict
bool
default:"False"
custom_emoji
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])
def unparse(text: str, entities: list) -> str
text
str
required
Текст для распарсивания всех энтити
entities
list[org.telegram.tgnet.TLRPC.MessageEntity]
required
Список со всеми entity текста.
Возвращает изначальную строку со всеми delim’ами.
@dataclass
class RawEntity
type
TLEntityType
required
Тип entity
offset
int
required
Позиция начала текста
length
int
required
Длина текста внутри тега
language
str
Язык программирования.Используется в TLRPC.TL_messageEntityPre при type == TLEntityType.PRE.
url
str
Ссылка.Используется в TLRPC.TL_messageEntityTextUrl при type == TLEntityType.TEXT_LINK.
document_id
int
ID Premium-эмодзи.Используется в TLRPC.TL_messageEntityCustomEmoji при type == TLEntityType.CUSTOM_EMOJI
collapsed
bool
Добавить ли возможность скрывать цитату.Используется в TLRPC.TL_messageEntityBlockquote при type == TLEntityType.BLOCKQUOTE
def to_tlrpc_object(self) -> TLRPC.MessageEntity
Возвращает созданный объект типа TLRPC.MessageEntity.
class TLEntityType(Enum)
CODE
TLRPC.TL_messageEntityCode
PRE
TLRPC.TL_messageEntityPre
STRIKETHROUGH
TLRPC.TL_messageEntityStrike
BOLD
Tentity, TLRPC.TL_messageEntityBold
ITALIC
TLRPC.TL_messageEntityItalic
UNDERLINE
TLRPC.TL_messageEntityUnderline
SPOILER
TLRPC.TL_messageEntitySpoiler
CUSTOM_EMOJI
TLRPC.TL_messageEntityCustomEmoji
BLOCKQUOTE
TLRPC.TL_messageEntityBlockquote
@classmethod
def _from(cls, entity: TLRPC.MessageEntity) -> TLEntityType
Возвращает тип на основе переданного entity.