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

Scope

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

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

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

scope = app.db.scope("notes/")

__init__

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

def __init__(app: App, prefix: str = '', module: str | None = None, slot: str | None = None) -> None: ...

Аргументы

• app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
• prefix: str, по умолчанию ''. Префикс ключей, добавляется без автоматического разделителя.
• module: str | None, по умолчанию None. ID публикации модуля. None выбирает текущий раздел там, где это предусмотрено.
• slot: str | None, по умолчанию None. Имя профиля экземпляра. None использует выбор зависимости или текущий профиль.

Результат

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

Права

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

Ошибки

• TypeError('A string prefix is required'): условие проверяется до продолжения операции.

Пример

# Обычный способ получения объекта:
scope = app.db.scope("notes/")

key

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

def key(key: str) -> str: ...

Аргументы

• key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.

Результат

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

Права

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

Ошибки

• ValueError('A record key is required'): условие проверяется до продолжения операции.

Пример

result = scope.key("count")

scope

Создаёт вложенный раздел с дополнительным префиксом и возможной заменой module или slot.

def scope(prefix: str = '', **target: JSON) -> Scope: ...

Аргументы

• prefix: str, по умолчанию ''. Префикс ключей, добавляется без автоматического разделителя.
• target: JSON, произвольные именованные аргументы. Допустимые именованные параметры: module, slot. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

Scope. Создаёт вложенный раздел с дополнительным префиксом и возможной заменой module или slot.

Права

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

Ошибки

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

Пример

result = scope.scope(module=None, slot=None)

record

Создаёт версионированную запись в этом разделе.

def record(key: str, default: JSON = None) -> Record: ...

Аргументы

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

Результат

Record. Создаёт версионированную запись в этом разделе.

Права

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

Ошибки

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

Пример

result = scope.record("count")

batch

Создаёт пакет изменений в этом разделе.

def batch() -> Batch: ...

Аргументы

Нет.

Результат

Batch. Создаёт пакет изменений в этом разделе.

Права

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

Ошибки

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

Пример

result = scope.batch()

get

Читает значение с префиксом; для отсутствующего ключа возвращает default.

async def get(key: str, default: JSON = None) -> JSON: ...

Аргументы

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

Результат

JSON. Читает значение с префиксом; для отсутствующего ключа возвращает default.

Права

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

Ошибки

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

Пример

result = await scope.get("count")

set

Записывает значение с префиксом и необязательным сроком хранения.

async def set(key: str, value: JSON, ttl: int | None = None) -> bool: ...

Аргументы

• key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.
• value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.
• ttl: int | None, по умолчанию None. Срок хранения в секундах 1..315360000; None без срока. У Record.save() пропуск отличается от None и сохраняет прежний срок.

Результат

bool. Записывает значение с префиксом и необязательным сроком хранения.

Права

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

Ошибки

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

Пример

result = await scope.set("count", {"count": 1})

delete

Удаляет ключ с префиксом и возвращает прежнее наличие.

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

Аргументы

• key: str, обязательный. Непустой ключ записи либо постоянный ключ кнопки в указанном объекте.

Результат

bool. Удаляет ключ с префиксом и возвращает прежнее наличие.

Права

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

Ошибки

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

Пример

result = await scope.delete("count")

items

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

async def items(limit: int = 100) -> AsyncIterator[tuple[str, JSON]]: ...

Аргументы

• limit: int, по умолчанию 100. Размер порции. Для db.keys: 1..1000; файлов и договоров: 1..100. get_messages: смотри ограничения Telegram-клиента.

Результат

AsyncIterator[tuple[str, JSON]]. Перебирает подходящие ключи и значения, удаляя префикс из выдаваемых имён. Чтения не образуют общий снимок.

Права

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

Ошибки

• RuntimeError('The database cursor did not advance'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

async for value in scope.items():
    break