Users storage

Users storage#

Хранилище пользователей.

Примечание

А как же SPMessages?

SPMessages Лишилась методов для работы с пользователями. Поскольку задача класса представления - только предсоставлять расписание в удобном для платформы формате.

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

Осторожно

Начальная фаза храналища

Данное хранилища всё ещё находится на этапер аразработке. Формат данных пользоваеля всё ещё омжет изменяться. Однако большая часть API уде меняться не будет. Внимательно следите за выпусками обновлений.

Вспомогательные контейнеры#

class sp.users.storage.UserData(create_time: int | None = 1724439380, cl: str | None = None, set_class: bool | None = False, last_parse: int | None = 0, notifications: bool | None = True, hours: list[int] = [])#

Данные пользователя внутри храналища.

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

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

Параметры:

  • create_time (Optional[int]) – Когда была создана учётная запись.

  • cl (Optional[str]) – Класс пользователя по умолчанию.

  • set_class (Optional[bool]) – Устанавливал ли пользователь класс.

  • last_parse (Optional[int]) – Временная метка последнего просмотренного обновления в расписании

  • notifications (Optional[bool]) – Включены ли уведомления у пользователя.

  • hours (list[int]) – В какие часы следует отправлять расписание

class sp.users.storage.CountedUsers(active: int, cl: Counter)#

Результат подсчёта пользователей.

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

active (int): Сколько пользователей использую обёртку. cl (Counter): Счётчик классов пользователей.

Хранилище пользователей#

class sp.users.storage.FileUserStorage(path: str | Path)#

Хранилище пользователей в JSON файле.

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

Является компонентом платформы.

Также стоит обратить вниманеи что данные в хранилище сохраняются вручную.

Параметры:

path (Path | str) – Путь к хранилищу пользователей.

Файл хранилища#

get_users() → dict[str, UserData]#

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

Подгружает даныне всех пользователей в словарь. Как ключ указывается id пользователя, как значение - UserData.

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

Результат:

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

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

dict[str, UserData]

remove_users(user_ids: list[str]) → None#

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

Используется для прочистки списка пользователей. Напрмиер в сприпте проверки обновлений. Когда можно пользователей могут заблокировать бота или исключить его из чатов. Данный метод исключает всех пользователей, а после один раз сохраняет файл базы пользователй.

Параметры:

user_ids (list[str]) – Список ID пользователей для удаления из базы.

save_users() → None#

Сохраняет данные пользователй в храналище.

Переводит все даныне из словарява в понятный для храналища формат. Если файл не был создан, то создаёт его. После перезаписыват полностью данныее в файл.

count_users(sc: Schedule) → CountedUsers#

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

Вспомогательная статистическая функиця. Используется для сбора различной информации о пльзователях. К примеруц число пользователей, которые считаются активными. Также считает количество польователей по классам по умолчанию.

Параметры:

sc – Относительно какого расписания производить подсчёт.

Type:

sc: Schedule

Результат:

Статистическая информация о хранилище.

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

CountedUsers

Управление пользователями#

create_user(uid: str) → None#

Создает нового пользователя.

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

Параметры:

uid (str) – Уникальный ID пользователя.

get_user(uid: str) → UserData#

Получает данные пользователя по его UID.

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

Параметры:

uid (str) – Уникальный ID пользователя.

Результат:

Данные пользователя из хранилища.

set_class(uid: str, cl: str | None, sc: Schedule) → bool#

Устанавливает класс по умолчанию пользователю.

Для начала вам нужно передать относительно какого расписнаия устанавливается класс. Вы можеет передать как строку, так и None. Последнее, чтобы явно отвзяать пользователя от класса. Если такого класса нет в расписнаии, вам вернётся False. Иначе же произойдёт следующее.

  • Класс будет установлен на заданный.

  • Флаг утсановки класса станет положительным.

  • Время последней проверки соотнесётся с проверкой расписнаия.

Параметры:

  • uid (str) – Для какого пользователя из базы установить класс.

  • cl (Optional[str]) – Какой класс установить пользователю.

  • sc (Schedule) – Относительно какого расписания установить класс.

Результат:

Стутус смены класса. True - класс был изменён.

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

bool

unset_class(uid: str) → None#

переводит пользователя в режим выбора класса.

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

  • Снимает флаг выбора класса пользователя.

  • Сбрасывает класс по умолчанию.

  • Не трогает все остальные параментры пользовтеля.

Параметры:

uid (str) – Для какого пользователя нужно снять класс.

update_user(uid: str, user: UserData) → None#

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

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

Параметры:

  • uid (str) – ID пользователя в хранилище.

  • user (UserData) – Новые данные пользователя для перезаписи.

class sp.users.storage.User(storage: FileUserStorage, uid: str)#

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

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

Параметры:

  • storage (FileUserStorage) – Хранилише пользователя.

  • uid (str) – ID пользователь для работы с хранилищем.

create() → None#

Создает нового пользователя.

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

remove() → None#

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

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

set_class(cl: str, sc: Schedule) → bool#

Устанавливает класс пользователя.

Если класс будет установлен, то сохраняет данные хранилища. Также как и с методов хранилищаЮ, возвращает стасус смены класса.

  • Класс будет установлен на заданный.

  • Флаг утсановки класса станет положительным.

  • Время последней проверки соотнесётся с проверкой расписнаия.

Параметры:

  • cl (str) – Какой класс необходимо устновить.

  • sc – Относительно какого расписнаия изменять класс.

Результат:

Стутс смены класса. True - класс изменён.

unset_class() → None#

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

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

save(save_users: bool | None = True) → None#

Сохраняет текушие локальные данные пользователя.

Устарело, начиная с версии 6.0: Данные метод может быть в любое время удалёен. Поскольку логично его не должно быть.

update() → None#

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

get_updates(sc: Schedule, save_users: bool | None = True) → dict[str, int | list[dict]] | None#

Возаращает все не просмотренные записи об изменениях.

Полчает все новые записи об изменниях в расписании, начиная с текущей отметки last_parse пользователя. Все записи об изменениях сживаются при помощи sp.sp.utils.compact_updates(). После получения всех имзенений, метка последней проверки сдвигается до времени последней записи об изменениях.

Примечание

Хранилище изменений

В скором времени этот метоб будет перенесён в хранилище списка изменений.

Параметры:

  • sc (Schedule) – Относительно какогор расписания получать изменения.

  • save_users (Optional[bool]) – Обноявлять ли временную метку обновления.

Результат:

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

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

Optional[dict[str, Union[int, list[dict]]]]

Настройка оповещений#

set_notify_on() → None#

Включает уведомления пользователя.

set_notify_off() → None#

Выключает уведомления пользователя.

add_notify_hour(hour: int) → None#

Добавляет рассылку в укзаанный час.

Обратите вниманеи что на данынй момент не происходит валидация числовых значений, так что самостоятельно убедитесь что вы передаёте час от 6-ти утра и 20-ти вечера.

Параметры:

hour (int) – _description_

remove_notify_hour(hour: int) → None#

Удаляет рассылку расписнаия в указанное время.

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

Параметры:

hour (int) – Час, для которого отключить уведомления.

reset_notify() → None#

Сбрасывает часы рассылка расписания расписания.

Содержание