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

Record

Версионированная запись базы. load() получает исходное состояние; save() и delete() сверяют ревизию.

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

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

record = await app.db.record("counter", {"count": 0}).load()

record загружен через load(); в примерах редактируется запись counter с полем count.

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

__init__

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

def __init__(db: Scope, key: str, default: JSON = None) -> None: ...

Аргументы

• db: Scope, обязательный. Выбранный раздел базы.
• key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.
• default: JSON, по умолчанию None. Возвращаемое или исходное значение при отсутствии данных. Объекты JSON копируются.

Результат

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

Права

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

Ошибки

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

Пример

# Обычный способ получения объекта:
record = await app.db.record("counter", {"count": 0}).load()

load

Загружает значение, exists, expires и revision. При отсутствии записи использует default и принимает снимок без записи default в базу.

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

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Загружает значение, exists, expires и revision. При отсутствии записи использует default и принимает снимок без записи default в базу.

Права

Нужны db.read. Для другого раздела своего юзербота дополнительно db.full.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• Conflict при изменённой ревизии; save() до load() вызывает ValueError. Локальные изменения при конфликте остаются в объекте.

Пример

result = await record.load()

save

Сохраняет локальное значение с проверкой revision. Без ttl сохраняет прежний срок; None явно снимает срок. После успеха принимает новый снимок.

async def save(ttl: int | None = missing) -> Self: ...

Аргументы

• ttl: int | None, по умолчанию missing. Срок хранения в секундах 1..315360000; None без срока. У Record.save() пропуск отличается от None и сохраняет прежний срок.

Результат

Self. Тот же объект после успешной операции. Сохраняет локальное значение с проверкой revision. Без ttl сохраняет прежний срок; None явно снимает срок. После успеха принимает новый снимок.

Права

Нужны db.write. Для другого раздела своего юзербота дополнительно db.full.

Ошибки

• ValueError('Load the record before saving'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• Conflict при изменённой ревизии; save() до load() вызывает ValueError. Локальные изменения при конфликте остаются в объекте.

Пример

result = await record.save()

delete

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

async def delete() -> bool: ...

Аргументы

Нет.

Результат

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

Права

db.write; если запись ещё не загружена, предварительный load() также требует db.read. Для другого раздела своего юзербота дополнительно db.full.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• Conflict при изменённой ревизии; save() до load() вызывает ValueError. Локальные изменения при конфликте остаются в объекте.

Пример

result = await record.delete()

__aenter__

Вход в async with. Загружает запись.

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

Аргументы

Нет.

Результат

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

Права

Нужны db.read. Для другого раздела своего юзербота дополнительно db.full.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• Conflict при изменённой ревизии; save() до load() вызывает ValueError. Локальные изменения при конфликте остаются в объекте.

Пример

async with record 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. При успешном выходе сохраняет только изменённый снимок; при исключении не сохраняет. Исключения блока не подавляются.

Права

Нужны db.write при изменении. Для другого раздела своего юзербота дополнительно db.full.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• Conflict при изменённой ревизии; save() до load() вызывает ValueError. Локальные изменения при конфликте остаются в объекте.

Пример

async with record as active:
    pass