Cluster · разработчикам

Settings

Редактируемый снимок настроек ядра, конфигурации или алиасов. secret и file через этот объект не изменяются.

Все методы SDK · Типы и ошибки

Получение объекта

settings = await app.core.settings_object().load()

settings загружен через load() в действующем личном событии овнера.

Наследует Document. Унаследованные методы: path, dirty, get, parent, remove, rename, append, insert, move, sort, increment, reset, accept.

__init__

Создаёт Settings. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(core: Core, kind: str = 'settings', instance: str | None = None) -> None: ...

Аргументы

• core: Core, обязательный. Служба настроек текущего приложения.
• kind: str, по умолчанию 'settings'. Раздел settings, configuration или commands.
• instance: str | None, по умолчанию None. Полный ID экземпляра в виде module/slot. None допустимо только там, где это задано сигнатурой.

Результат

None. Создаёт Settings. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

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

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
settings = await app.core.settings_object().load()

load

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

async def load() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Получает значения, описания полей и ревизию нужного раздела; принимает новый исходный снимок.

Права

Нужны core.configure для settings; modules.configure для commands/configuration. Требуется действующее событие овнера в личном чате; фоновой задачи недостаточно.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

result = await settings.load()

set

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

def set(path: str, value: JSON) -> Self: ...

Аргументы

• path: str, обязательный. Имя одного известного поля. Вложенные пути этим переопределённым методом не поддерживаются.
• value: JSON, обязательный. Новое значение по схеме поля; secret и file менять нельзя.

Результат

Self. Тот же объект после успешной операции. Меняет известное поле в локальном снимке с проверкой его схемы. Перед изменениями нужен load().

Права

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

Ошибки

• ValueError('Load the settings first'): условие проверяется до продолжения операции.
• KeyError(path): условие проверяется до продолжения операции.
• ValueError('Secrets and files are changed on the website'): условие проверяется до продолжения операции.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

result = settings.set("prefix", "!")

default

Локально возвращает поле к объявленному значению по умолчанию.

def default(name: str) -> Self: ...

Аргументы

• name: str, обязательный. Имя функции, сигнала либо поля в выбранном объекте.

Результат

Self. Тот же объект после успешной операции. Локально возвращает поле к объявленному значению по умолчанию.

Права

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

Ошибки

• KeyError(name): условие проверяется до продолжения операции.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

result = settings.default("status")

save

Отправляет только изменённые поля с проверкой revision. Неизменённый снимок не создаёт запрос. Набор ключей менять нельзя.

async def save() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Отправляет только изменённые поля с проверкой revision. Неизменённый снимок не создаёт запрос. Набор ключей менять нельзя.

Права

Нужны core.configure для settings; modules.configure для commands/configuration. Требуется действующее событие овнера в личном чате; фоновой задачи недостаточно.

Ошибки

• ValueError('Load the settings first'): условие проверяется до продолжения операции.
• ValueError('Settings cannot be added or removed'): условие проверяется до продолжения операции.
• ValueError('Secrets and files are changed on the website'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

result = await settings.save()

__aenter__

Вход в async with. Загружает настройки и их ревизию.

async def __aenter__() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Вход в async with. Загружает настройки и их ревизию.

Права

Нужны core.configure для settings; modules.configure для commands/configuration. Требуется действующее событие овнера в личном чате; фоновой задачи недостаточно.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

async with settings as active:
    pass

__aexit__

Выход из async with. При успешном выходе сохраняет только изменённые настройки; при исключении не сохраняет. Исключения блока не подавляются.

async def __aexit__(kind: type[BaseException] | None, error: BaseException | None, traceback: TracebackType | None) -> None: ...

Аргументы

• kind: type[BaseException] | None, обязательный. Тип исключения блока либо None. Передаётся Python автоматически.
• error: BaseException | None, обязательный. Исключение блока async with либо None; контекстный протокол передаёт автоматически.
• traceback: TracebackType | None, обязательный. Трассировка исключения контекстного блока; передаётся Python автоматически.

Результат

None. Выход из async with. При успешном выходе сохраняет только изменённые настройки; при исключении не сохраняет. Исключения блока не подавляются.

Права

Нужны core.configure для settings; modules.configure для commands/configuration. Требуется действующее событие овнера в личном чате; фоновой задачи недостаточно.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• ValueError при неизвестном поле, изменении secret/file или неверном значении; Conflict при устаревшей ревизии.

Пример

async with settings as active:
    pass