Перейти к основному содержимому
Версия: Latest

Utils - все дополнительные функции RimTUB

get_root​

Возвращает путь к директории, в которой находится RimTUB.

Аргументы:

  • as_path (bool) = False - Если True то результат вернется в виде pathlib.Path. Если False - в виде строки

Возвращает: str|Path - путь к корню RimTUB

Пример:

print(get_root()) # D:\RimTUB

get_args​

Извлекает аргументы из текста.

Аргументы:

  • text (str) - исходный текст с аргументами.
  • default (Any) = '' значение по умолчанию, если аргумент отсутствует.

Возвращает: str|Any - строка с аргументом или значение по умолчанию.

Пример:

# msg.text = '.command some text'
text = get_args(msg.text)
print(text) # some text

parse_args​

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

warning

на данный момент даная функция работает некорректно 👍

Аргументы:

  • input_str (str) - строка с аргументами, разделёнными пробелами.

Возвращает: Tuple[List[str], List[str], Dict[str, Any]] - список позиционных аргументов, список флагов, словарь параметров.

Пример:

# msg.text = '.command some text -photo -size X'
args, flags, kwargs = parse_args(get_args(msg.text))
print(args) # ['some', 'text']
print(flags) # ['-photo']
print(kwargs) # {'-size': 'X'}

pnum​

Приводит число к целому, если оно эквивалентно по значению, иначе оставляет дробным.
Если простыми словами, убирает .0

Аргументы:

  • num (int | float) - число для преобразования.

Возвращает: int | float - преобразованное число.

Пример:

print(pnum(5.5)) # 5.0
print(pnum(9.0)) # 9

fnum​

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

Аргументы:

  • num (int) - число для преобразования.
  • threshold (int) - пороговое значение для разделения тысяч.

Возвращает: int | float - отформатированное число в виде строки.

Пример:

sec_to_str​

Преобразует количество секунд в строковое представление формата "д.ч.м.с."

Аргументы:

  • seconds (int) - количество секунд для преобразования.
  • round (bool) = True - округлять ли число секунд до целого (по умолчанию True).

Возвращает: str - строка, представляющая время.

Пример:

print(sec_to_str(66666)) # 18ч. 31m. 6c.

plural​

Определяет правильную форму слова в зависимости от количества.

Аргументы:

  • count (int) - количество объектов.
  • words (List[str]) - список форм слова (ед.ч., дв., мн.).

Возвращает: str - правильная форма слова.

Пример:

module = ['модуль', 'модуля', 'модулей']
plural(1,  module) # модуль
plural(3,  module) # модуля
plural(15, module) # модулей

restart​

Перезапускает RimTUB

warning

Это системная функция. Трогать её не рекомендуется.

Аргументы:

  • app_id (int) - ID клиента
  • chat_id (int) = None - (опционально) идентификатор чата для изменения сообщения.
  • msg_id (int) = None - (опционально) идентификатор сообщения для изменения.

Возвращает: None

async check_ping​

Проверяет пинг, отправляя сообщение самому себе и измеряя задержку.

Аргументы:

  • app (Client) - объект приложения, через который выполняется отправка сообщения.

Возвращает: float - значение пинга в миллисекундах.

Пример:

await check_ping(app) # 82.3

get_numbers_from_string​

Извлекает все числа из строки.

Аргументы:

  • string (str) - строка для поиска чисел.

Возвращает: List[float] - список чисел

Пример:

text = "Было 15 яблок по 123.4 г каждое, и 1 бан весом 200 грамм"
get_numbers_from_string(text) # [15.0, 123.4, 1.0, 200.0]

find_function_by_id​

Ищет функцию по её идентификатору в памяти.

Аргументы:

  • func_id (int) - идентификатор функции.

Возвращает: Callable | None - функция, если найдена. None если нет. `

tail​

Получает последние n строк из файла.

Аргументы:

  • f (TextIO) - объект файла.
  • lines (int) = 1 - количество строк для извлечения.
  • _buffer (int) = 4098 - размер буфера чтения.

Возвращает: __ -

Пример:

file.txt
Какой-то
текст
где много
срок и
вот тут
есть
последние
две строки
with open('file.txt', 'r', encoding='utf-8') as f:
    print(tail(f, 2)) # последние\nдве строки

try_​

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

Аргументы:

  • func_to_try (Callable) - основная функция, которую нужно выполнить.
  • func_to_except (Callable) = None - функция, выполняемая при исключении (по умолчанию None).
  • func_to_else (Callable) = None - функция, выполняемая, если исключение не возникло (по умолчанию None).
  • func_to_finally (Callable) = None - функция, выполняемая в любом случае после завершения основной функции (по умолчанию None).
  • default (Any) = None - значение по умолчанию, возвращаемое при исключении (по умолчанию None).

Возвращает: Any - результат выполнения функций.

Пример:

try_(os.remove(path)) # Пробуем удалить. Если будет ошибка (файл не найден) нам все равно.

get_tree​

Рекурсивно строит дерево файлов и директорий в указанной папке.
Аналог команды TREE на Windows

Аргументы:

  • directory (str) - путь к директории, для которой строится дерево.
  • prefix (str) = "" - строка префикса для отображения уровней вложенности (по умолчанию пустая строка).
  • html (bool) = False - форматировать ли результат как HTML (по умолчанию False).

Возвращает: str - строковое представление дерева директорий и файлов.

Пример:

print(get_tree(get_root() / 'plugins' / 'MineEvoMiner'))
Вывод
├── .rimtubignore
├── helplist.py
├── manifest.yaml
├── miner
│   ├── inline.py
│   ├── mine.py
│   ├── scripts.py
│   └──__init__.py
├── stats
│   └── stat.py
├── utils
│   ├── emj.py
│   ├── prettier.py
│   ├── scripts.py
│   ├── types.py
│   └── __init__.py
└── __init__.py

find_file​

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

Аргументы:

  • filename (str) - имя файла, который необходимо найти.
  • search_path (str) - путь к директории, в которой будет осуществляться поиск.
  • max_depth (int) = None - максимальная глубина рекурсивного поиска (по умолчанию нет ограничения).
  • extensions (List[str]) = None - список расширений для фильтрации (по умолчанию любые файлы).
  • case_sensitive (bool) = False - учитывать ли регистр имени файла (по умолчанию False).
  • default (Any) = None - значение по умолчанию, возвращаемое при отсутствии файла.

Возвращает: str | Any - полный путь к самому похожему файлу или значение default, если файл не найден.

Пример:

UBLog/__init__.py, lines 27-28
logfile = get_args(msg.text, 'general')
file = find_file(logfile, 'logs', 1, ['.log'])

find_directory​

Ищет директорию с самым похожим именем в указанной директории и её подпапках.

Аргументы:

  • dirname (str) - имя директории, которую необходимо найти.
  • search_path (str) - путь к директории, в которой будет осуществляться поиск.
  • max_depth (int) = None - максимальная глубина рекурсивного поиска (по умолчанию нет ограничения).
  • case_sensitive (bool) = False - учитывать ли регистр имени директории (по умолчанию False).
  • default (Any) = None - значение по умолчанию, возвращаемое при отсутствии директории.

Возвращает: str | Any - полный путь к самой похожей директории или значение default, если директория не найдена.

Пример:

ModuleHelper/__init__.py, line 316
module_path = Path(find_directory(name, 'plugins', 1))

install_requirements​

Аргументы:

  • requirements (dict) - Словарь, где ключи это то, как библиотеку импортировать, а значения - как скачивать через pip

Возвращает: None

Пример:

requirements = {
    "telebot": "pyTelegramBotAPI==4.26.0"
}
install_requirements(requirements)

read_yaml​

Чтение YAML файла

Аргументы:

  • file_path (str) - Путь к YAML файлу

Возвращает: dict - Данные в виде словаря

Ошибки:

  • FileNotFoundError - когда файл не найден
  • yaml.scanner.ScannerError - при ошибке парсинга

Пример:

/utils/modify_pyrogram_client.py, line 228, in load_module
manifest = read_yaml(Path(get_root(), 'plugins', module_name, 'manifest.yaml')) or {}

singleton​

Декоратор для реализации паттерна Singleton.

Аргументы: нет

Возвращает: type - Класс-обертка для получения единственного экземпляра класса.

Пример:

/utils/helplist.py, lines 220-221
@singleton
class HelpList:
   ...

save_pickle​

Сохраняет данные в pickle storage

См. Хранилища данных > Pickle хранилище (pickle storage)

Аргументы:

  • path (pathlib.Path|str) - путь к файлу.
    подсказка

    Сохранять файлы желательно либо в папке /storage, либо в папке модуля.

  • data (Any) - Python объект который нужно сохранить
  • ttl (int) = Значение в конфиге (DEFAULT_PICKLE_STORAGE_FILES_TTL) (= 259200 = 3 дня) - Время жизни файла в секундах. По прошествии этого времени файл будет автоматически удалён. Рекомендуется устанавливать не более 7 дней (604800 секунд)

Возвращает: pathlib.Path - полный путь к файлу.

Пример:

SomeModule/__init__.py
data = mod # сохраним весь объект модуля, почему бы и нет ¯\_(ツ)_/¯

storage_folder = mod.path / 'storage'
storage_folder.mkdir(parents=True, exist_ok=True) # создаем папку если ее еще нет
path = storage_folder / "module_obj.pkl"

# Сохраняю данные без указания TTL,  
# чтобы использовалось значение по умолчанию  
# (пользователь может изменить его в конфиге)
path = save_pickle(path, data)

mod.logger.info(f"Сохранил объект модуля в {path}")

load_pickle​

Загружает данные из pickle storage

См. Хранилища данных > Pickle хранилище (pickle storage)

Аргументы:

  • path (pathlib.Path|str) - путь к файлу.

Возвращает: Any - данные

Пример:

SomeModule/__init__.py
path = mod.path / 'storage' / 'module_obj.pkl'
loaded_mod = load_pickle(path)

cleanup_expired_storage_files​

Удаляет устаревшие storage pickle файлы по TTL

warning

Это системная функция. Трогать её не рекомендуется.

Аргументы: нет

Возвращает: None

generate_random_identifier​

Генерирует случайную комбинацию чисел указанной длинны

Аргументы:

  • length (int) = 10 - длинна строки

Возвращает: str - сгенерированная комбинация

Пример:

print(generate_random_identifier()) # GXNgL0VQYV