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

Document

Изолированная JSON-копия с вложенными путями. Методы изменения возвращают тот же объект, сохранение не выполняется.

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

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

document = app.document({"items": [3, 1], "count": 0})

__init__

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

def __init__(value: JSON = None) -> None: ...

Аргументы

• value: JSON, по умолчанию None. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.

Результат

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

Права

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

Ошибки

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

Пример

# Обычный способ получения объекта:
document = app.document({"items": [3, 1], "count": 0})

path

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

def path(path: Path) -> tuple[str | int, ...]: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.

Результат

tuple[str | int, ...]. Приводит скалярный путь, список или кортеж к кортежу. Точки в строке остаются частью одного ключа.

Права

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

Ошибки

• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.path("items")

dirty

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

def dirty() -> bool: ...

Свойство: читается без скобок и без await.

Аргументы

Нет.

Результат

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

Права

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

Ошибки

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

Пример

value = document.dirty

get

Возвращает глубокую копию значения по пути. Без default ошибка отсутствующего пути не подавляется.

def get(path: Path = (), default: JSON = missing) -> JSON: ...

Аргументы

• path: Path, по умолчанию (). Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• default: JSON, по умолчанию missing. Возвращаемое или исходное значение при отсутствии данных. Объекты JSON копируются.

Результат

JSON. Возвращает глубокую копию значения по пути. Без default ошибка отсутствующего пути не подавляется.

Права

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

Ошибки

• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.get()

parent

Возвращает непосредственный изменяемый контейнер и последний компонент пути. Для корня возвращает (None, None); это низкоуровневый доступ к локальным данным.

def parent(path: Path) -> tuple[JSON, str | int | None]: ...

Аргументы

• path: Path, обязательный. Путь; возвращаемый контейнер изменяется напрямую в локальном документе.

Результат

tuple[JSON, str | int | None]. Возвращает непосредственный изменяемый контейнер и последний компонент пути. Для корня возвращает (None, None); это низкоуровневый доступ к локальным данным.

Права

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

Ошибки

• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.parent("items")

set

Заменяет значение по пути; пустой путь заменяет весь корень.

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

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.

Результат

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

Права

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

Ошибки

• IndexError('Invalid list position'): условие проверяется до продолжения операции.
• TypeError('A dictionary key or list position is required'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.set("count", 1)

remove

Удаляет существующий ключ или элемент списка. Удалить весь корень этим методом нельзя.

def remove(path: Path) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.

Результат

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

Права

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

Ошибки

• ValueError('The document root cannot be removed'): условие проверяется до продолжения операции.
• IndexError('Invalid list position'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.remove("count")

rename

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

def rename(path: Path, name: str) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• name: str, обязательный. Имя функции, сигнала либо поля в выбранном объекте.

Результат

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

Права

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

Ошибки

• TypeError('A dictionary key is required'): условие проверяется до продолжения операции.
• ValueError('The destination key already exists'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.rename("count", "total")

append

Добавляет несколько значений в конец списка по пути.

def append(path: Path, *values: JSON) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• values: JSON, позиционные значения. Позиционные значения, которые будут добавлены в список.

Результат

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

Права

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

Ошибки

• TypeError('A list is required'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.append("items", 4, 5)

insert

Вставляет значение в список перед index, включая позицию сразу после последнего элемента.

def insert(path: Path, index: int, value: JSON) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• index: int, обязательный. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.
• value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.

Результат

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

Права

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

Ошибки

• TypeError('A list is required'): условие проверяется до продолжения операции.
• IndexError('Invalid list position'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.insert("items", 0, 4)

move

Переносит элемент списка между существующими позициями.

def move(path: Path, index: int, target: Module) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• index: int, обязательный. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.
• target: Module, обязательный. Выбранная зависимость.

Результат

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

Права

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

Ошибки

• TypeError('A list is required'): условие проверяется до продолжения операции.
• IndexError('Invalid list position'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.move("items", 0, 1)

sort

Сортирует список либо порядок ключей словаря; key для словаря получает имя ключа.

def sort(path: Path = (), key: Callable | None = None, reverse: bool = False) -> Self: ...

Аргументы

• path: Path, по умолчанию (). Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• key: Callable | None, по умолчанию None. Синхронный ключ сортировки. None использует правило класса; вызывается для каждого элемента.
• reverse: bool, по умолчанию False. Логический переключатель указанного действия.

Результат

Self. Тот же объект после успешной операции. Сортирует список либо порядок ключей словаря; key для словаря получает имя ключа.

Права

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

Ошибки

• TypeError('A list or dictionary is required'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.sort()

increment

Прибавляет число к числовому значению по пути. bool числом для этой операции не считается.

def increment(path: Path, amount: int | float = 1) -> Self: ...

Аргументы

• path: Path, обязательный. Один ключ, индекс либо последовательность ключей и индексов. () обозначает корень, строка с точками остаётся одним ключом.
• amount: int | float, по умолчанию 1. Число, прибавляемое к существующему числу. bool не принимается.

Результат

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

Права

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

Ошибки

• TypeError('Numbers are required'): условие проверяется до продолжения операции.
• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

document.increment("count", 1)

reset

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

def reset() -> Self: ...

Аргументы

Нет.

Результат

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

Права

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

Ошибки

• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.reset()

accept

Принимает текущее локальное значение за исходное. Ничего не записывает в ядро; не подменяй этим save().

def accept() -> Self: ...

Аргументы

Нет.

Результат

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

Права

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

Ошибки

• KeyError, IndexError или TypeError при неверном вложенном пути; ValueError/TypeError для неподдерживаемого JSON. См. правила JSON в TYPES.md.

Пример

result = document.accept()