Users

class dublib.TelebotUtils.Users.UserData(manager: UsersManager, user_id: int)

Объектное представление данных пользователя.

add_flags(flags: Iterable[str] | str)

Добавляет флаги пользователю.

Параметры:

flags (Iterable[str] | str) – Один или несколько флагов.

add_permissions(permissions: Iterable[str] | str)

Добавляет права пользователю.

Параметры:

permissions (Iterable[str] | str) – Одно или несколько прав.

attach_object(key: str, object: Any, force: bool = True)

Прикрепляет объект к пользователю. При перезапуске объект будет удалён.

Параметры:

• key (str) – Ключ объекта.

• object (Any) – Прикрепляемый объект.

• force (bool) – Указывает, нужно ли перезаписывать уже существующий объект.

check_flags(flags: Iterable[str] | str) → bool

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

Параметры:

flags (Iterable[str] | str) – Один или несколько флагов.

Результат:

Возвращает True, если все флаги активированы.

Тип результата:

bool

clear_temp_properties()

Очищает временные свойства пользователя.

property expected_type: str | None

Тип ожидаемого значения.

property flags: tuple[str]

Набор активированных флагов.

get_object(key: str) → Any

Возвращает объект, прикреплённый к пользователю.

Параметры:

key (str) – Ключ объекта.

Исключение:

KeyError – Выбрасывается при отсутствии объекта с переданным ключом.

Результат:

Прикреплённый объект.

Тип результата:

Any

get_property(key: str, copy: bool = True) → Any

Возвращает значение свойства пользователя. При наличии одинакового ключа в постоянных и временных свойствах, приоритет отдаётся временному.

Параметры:

• key (str) – Ключ свойства.

• copy (bool) – Указывает, нужно ли создавать копию ссылочных объектов для защиты данных. Не рекомендуется отключать, если свойство будет изменяться.

Исключение:

KeyError – Выбрасывается при отсутствии свойства с переданным ключом.

Результат:

Значение свойства.

Тип результата:

Any

has_object(key: str) → bool

Проверяет, прикреплён ли к пользователю объект с переданным ключом.

Параметры:

key (str) – Ключ объекта.

Результат:

Возвращает True, если объект с таким ключом найден.

Тип результата:

bool

has_permissions(permissions: Iterable[str] | str) → bool

Проверяет, имеет ли пользователь все указанные права.

Параметры:

permissions (Iterable[str] | str) – Одно или несколько прав.

Результат:

Возвращает True, если пользователь имеет все указанные права.

Тип результата:

bool

has_property(key: str) → bool

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

Параметры:

key (str) – Ключ свойства.

Результат:

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

Тип результата:

bool

property id: int

ID пользователя.

property is_chat_forbidden: bool

Состояние: может ли бот контактировать с пользователем.

property is_premium: bool

Состояние: имеет ли пользователь Premium-подписку.

property is_saving_suppressed: bool

Состояние: подавляется ли сохранение в локальный файл.

property language: str

Код используемого клиентом языка по стандарту ISO 639-1.

property last_activity: datetime | None

Дата и время последней активности пользователя.

property objects: dict[str, Any]

Словарь прикреплённых к пользователю объектов.

property path: PathLike

Путь к файлу пользователя.

property permissions: tuple[str]

Список прав пользователя.

refresh()

Считывает данные из файла пользователя и дополняет отсутствующие поля.

Исключение:

RefreshingBlocked – Выбрасывается при попытке чтения файла пользователя во время подавления сохранений.

remove_flags(flags: Iterable[str] | str)

Удаляет флаги.

Параметры:

flags (Iterable[str] | str) – Один или несколько флагов.

remove_object(key: str)

Удаляет прикреплённый объект.

Параметры:

key (str) – Ключ объекта.

Исключение:

KeyError – Выбрасывается, если объект с указанным ключом не найден.

remove_permissions(permissions: Iterable[str] | str)

Удаляет права.

Параметры:

permissions (Iterable[str] | str) – Одно или несколько прав.

remove_property(key: str)

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

Параметры:

key (str) – Ключ свойства.

reset_expected_type()

Сбрасывает ожидаемый тип к значению None.

save(use_queue: bool = True)

Записывает данные пользователя в локальный файл.

Если значение с момента прошлого сохранения не изменено, сохранение будет пропущено.

Параметры:

use_queue (bool) – Указывает, помещать ли задачу в очередь, если доступна, или выполнить сохранение немедленно.

set_chat_forbidden(status: bool)

Задаёт состояние: может ли бот контактировать с пользователем.

Параметры:

status (bool) – Состояние.

set_expected_type(expected_type: str | Enum | None)

Задаёт ожидаемый тип данных.

Параметры:

expected_type (str | Enum | None) – Ожидаемый от пользователя тип данных. При указании элемента перечисления берётся его значение.

set_property(key: str, value: Any, force: bool = True)

Задаёт значение свойства пользователя.

Параметры:

• key (str) – Ключ свойства.

• value (Any) – Значение свойства.

• force (bool) – Указывает, нужно ли перезаписывать уже существующее свойство.

set_temp_property(key: str, value: Any, force: bool = True)

Задаёт временное значение свойства пользователя.

Временные значения могут служить для поэтапного ввода данных или непродолжительного хранения информации. Как правило их следует очищать методом clear_temp_properties().

Параметры:

• key (str) – Ключ свойства.

• value (Any) – Значение свойства.

• force (bool) – Указывает, нужно ли перезаписывать уже существующее свойство.

suppress_saving(status: bool, save_on_disabling: bool = True)

Подавляет сохранение в локальный файл.

Следует использовать для оптимизации при множественных изменениях. Во время подавления недоступен вызов метода refresh().

Параметры:

• status (bool) – Статус подавления.

• save_on_disabling (bool) – Указывает, следует ли выполнить обязательное сохранение после отключения подавления. Игнорируется при включении подавления.

update(user: User, is_chat_forbidden: bool | None = None)

Обновляет данные пользователя (язык, наличие подписки, ник) из его структуры Telegram.

Параметры:

• user (telebot.types.User) – Объект представления пользователя.

• is_chat_forbidden (bool | None) – Указывает, заблокировал ли пользователь бота.

Исключение:

IncorrectUserToUpdate – Выбрасывается при передаче несоответствующей по ID структуры пользователя.

update_acitivity() → datetime

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

Результат:

Дата и время последней активности пользователя.

Тип результата:

datetime

property username: str

Ник пользователя.

class dublib.TelebotUtils.Users.UsersManager(storage_directory: PathLike, threads: int = 1)

Менеджер пользователей.

add_flags(flags: Iterable[str] | str)

Добавляет флаги для всех пользователей.

Параметры:

flags (Iterable[str] | str) – Один или несколько флагов.

auth(user: User, update_activity: bool = True) → UserData

Выполняет авторизацию пользователя в системе.

Параметры:

• user (telebot.types.User) – Структуры данных пользователя Telegram.

• update_activity (bool) – Указывает, нужно ли обновить дату и время последней активности пользователя.

Исключение:

TypeError – Выбрасывается при передаче неверного типа структуры данных пользователя.

Результат:

Данные пользователя.

Тип результата:

UserData

clear_temp_properties()

Очищает временные свойства всех пользователей.

delete_user(user_id: int)

Удаляет данные пользователя.

Параметры:

user_id (int) – ID пользователя.

Исключение:

KeyError – Выбрасывается при отсутствии пользователя с переданным ID.

enable_atomic_writing(status: bool)

Переключает режим атомарной записи файлов, увеличивает время сохранения JSON за счёт гарантии сохранности.

Параметры:

status (bool) – Состояние использования атомарной записи.

enable_pretty_saving(status: bool)

Переключает форматирование локальных файлов с использованием отступов. Отключение может значительно ускорить операции записи.

Параметры:

status (bool) – Состояние форматирования.

enable_saving_queue(status: bool)

Переключает использование очереди сохранений.

Параметры:

status (bool) – Состояние использования очереди.

get_active_users(hours: int = 24) → tuple[UserData]

Возвращает последовательность пользователей, для которых активных за последние N часов.

Параметры:

hours (int) – Количество часов для проверки активности. По умолчанию 24.

Результат:

Последовательность данных пользователей.

Тип результата:

tuple[UserData]

get_user(user_id: int) → UserData

Возвращает данные пользователя.

Параметры:

user_id (int) – ID пользователя.

Исключение:

KeyError – Выбрасывается при отсутствии данных для пользователя с указанным ID.

Результат:

Данные пользователя.

Тип результата:

UserData

property is_atomic_writes: bool

Состояние: используется ли атомарная запись.

property is_pretty_saving_enabled: bool

Состояние: форматировать ли локальные файлы отступами.

property is_saving_queue_enabled: bool

Состояние: используется ли очередь сохранений.

is_user_exists(user_id: int) → bool

Проверяет, зарегестрирован ли пользователь в системе.

Параметры:

user_id (int) – ID пользователя.

Результат:

Возвращает True, если данные пользователя обнаружены.

Тип результата:

bool

property premium_users: tuple[UserData]

Последовательность пользователей с Premium-подпиской из числа хранящихся в памяти.

push_to_saving_queue(user: UserData)

Добавляет данные пользователя в очередь на сохранение.

Параметры:

user (UserData) – Данные пользователя.

Исключение:

SavingQueueBlocked – Выбрасывается при отключённой очереди сохранений.

reload_users(threads: int = 1)

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

Вызывается автоматически при инициализации менеджера. Повторный вызов без реализации механизмов защиты может привести к потере данных.

Параметры:

threads (int) – Число потоков, использующихся для операций чтения. По умолчанию 1.

remove_flags(flags: Iterable[str] | str)

Удаляет флаги у всех пользователей.

Параметры:

flags (Iterable[str] | str) – Один или несколько флагов.

remove_permissions(permissions: list[str] | str)

Удаляет права у всех пользователей.

Параметры:

permissions (Iterable[str] | str) – Одно или несколько прав.

remove_property(key: str)

Удаляет свойство у всех пользователей.

Параметры:

key (str) – Ключ свойства.

restore_unloaded_users()

Заново загружает в память ранее выгруженные данные неактивных пользователей.

set_property(key: str, value: Any, force: bool = True)

Задаёт свойство для всех пользователей.

Параметры:

• key (str) – Ключ свойства.

• value (Any) – Значение свойства.

• force (bool) – Указывает, нужно ли перезаписывать уже существующее свойство.

start_unloader(interval: int, days: int)

Запускает фоновую задачу по периодической выгрузке неактивных пользователей из памяти.

Параметры:

• interval (int) – Интервал в часах для срабатывания выгрузки.

• days (int) – Количество дней отсутствия активности.

stop_unloader()

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

property storage_directory: PathLike

Путь к каталогу файлов пользователей.

unload_users(days: int) → tuple[int]

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

Параметры:

days (int) – Количество дней отсутствия активности. Минимум 1.

Результат:

Последовательность ID пользователей, для которых были выгружены данные.

Тип результата:

tuple[int]

Исключение:

ValueError – Выбрасывается при неверной спецификации количества дней.

property unloaded_users_id: tuple[int]

Последовательность ID выгруженных из памяти пользователей.

property users: tuple[UserData]

Последовательность хранящихся в памяти пользователей.