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

File

Готовый или загружаемый файл Cluster. Методы с побочным эффектом выполняются через ядро.

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

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

file = app.files("file-id")

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

__init__

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

def __init__(files: Files, id: str, data: FileInfo | None = None) -> None: ...

Аргументы

• files: Files, обязательный. Служба файлов текущего приложения.
• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.
• data: FileInfo | None, по умолчанию None. Метаданные из files/upload или files/list. Если переданы, объект вычисляет их ревизию; None потребует загрузки перед редактированием.

Результат

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

Права

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

Ошибки

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

Пример

# Обычный способ получения объекта:
file = app.files("file-id")

active

Проверяет, что объект ещё не отмечен удалённым. Состояние сервера не загружает.

def active() -> None: ...

Аргументы

Нет.

Результат

None. Проверяет, что объект ещё не отмечен удалённым. Состояние сервера не загружает.

Права

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

Ошибки

• ValueError('The file has been deleted'): условие проверяется до продолжения операции.
• InvalidState для незавершённого или недоступного файла; Conflict при изменении метаданных с устаревшей ревизией.

Пример

result = file.active()

load

Получает актуальные метаданные и revision файла.

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

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Получает актуальные метаданные и revision файла.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.load()

edit

Меняет метаданные с проверкой revision; при отсутствии ревизии сначала загружает файл.

async def edit(**values: JSON) -> Self: ...

Аргументы

• values: JSON, произвольные именованные аргументы. Допустимые именованные параметры: filename, ttl. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

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

Права

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

Ошибки

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

Пример

result = await file.edit(filename="renamed.txt")

rename

Меняет подпись filename с проверкой ревизии.

async def rename(filename: str) -> Self: ...

Аргументы

• filename: str, обязательный. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().

Результат

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

Права

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

Ошибки

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

Пример

result = await file.rename("note.txt")

retain

Меняет срок хранения с проверкой ревизии. None снимает срок.

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

Аргументы

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

Результат

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

Права

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

Ошибки

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

Пример

result = await file.retain()

chunks

Читает файл порциями; целиком в память его не собирает.

async def chunks(size: int = 65536) -> AsyncIterator[bytes]: ...

Аргументы

• size: int, по умолчанию 65536. Число байт одной порции, целое от 1 до 65536.

Результат

AsyncIterator[bytes]. Читает файл порциями; целиком в память его не собирает.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

async for value in file.chunks():
    break

read_at

Читает один участок с проверкой границ и корректности смещения в ответе.

async def read_at(offset: int = 0, size: int = 65536) -> bytes: ...

Аргументы

• offset: int, по умолчанию 0. Смещение порции либо байтов, начиная с нуля.
• size: int, по умолчанию 65536. Размер в байтах либо число элементов у Pages. Предел зависит от конкретного метода.

Результат

bytes. Читает один участок с проверкой границ и корректности смещения в ответе.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.read_at()

read

Получает содержимое целиком. maximum является неотрицательным целым; размер сверяется до чтения и после каждой порции.

async def read(maximum: int = 1048576) -> bytes: ...

Аргументы

• maximum: int, по умолчанию 1048576. Положительный предел чтения в байтах либо размер страницы в элементах, согласно методу.

Результат

bytes. Получает содержимое целиком, предварительно сверяя размер с maximum.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

• ValueError('A non-negative size limit is required'): условие проверяется до продолжения операции.
• ValueError('The file exceeds the memory limit; use chunks'): условие проверяется до продолжения операции.
• ValueError('The file exceeds the memory limit'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• InvalidState для незавершённого или недоступного файла; Conflict при изменении метаданных с устаревшей ревизией.

Пример

content = await file.read(maximum=1048576)

text

Читает файл в пределах maximum и декодирует выбранной кодировкой.

async def text(encoding: str = 'utf-8', maximum: float | None = 1048576) -> str: ...

Аргументы

• encoding: str, по умолчанию 'utf-8'. Название кодировки Python для декодирования байтов.
• maximum: float | None, по умолчанию 1048576. Граница min/max поля, конечное число от -1e12 до 1e12; None снимает границу.

Результат

str. Читает файл в пределах maximum и декодирует выбранной кодировкой.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.text()

json

Читает файл как UTF-8 и разбирает JSON.

async def json(maximum: float | None = 1048576) -> JSON: ...

Аргументы

• maximum: float | None, по умолчанию 1048576. Граница min/max поля, конечное число от -1e12 до 1e12; None снимает границу.

Результат

JSON. Читает файл как UTF-8 и разбирает JSON.

Права

Нужны files.read. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.json()

copy

Потоково копирует файл в новый с выбранными именем и сроком, проверяя размер и SHA256.

async def copy(filename: str | None = None, ttl: int | None = None) -> File: ...

Аргументы

• filename: str | None, по умолчанию None. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().
• ttl: int | None, по умолчанию None. Срок хранения в секундах 1..315360000; None без срока. У Record.save() пропуск отличается от None и сохраняет прежний срок.

Результат

File. Потоково копирует файл в новый с выбранными именем и сроком, проверяя размер и SHA256.

Права

Нужны files.read + files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.copy()

delete

Удаляет файл через ядро и отмечает локальный объект удалённым.

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

Аргументы

Нет.

Результат

bool. Удаляет файл через ядро и отмечает локальный объект удалённым.

Права

Нужны files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await file.delete()

__aenter__

Вход в async with. Возвращает этот объект без дополнительной загрузки.

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

Аргументы

Нет.

Результат

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

Права

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

Ошибки

• InvalidState для незавершённого или недоступного файла; Conflict при изменении метаданных с устаревшей ревизией.

Пример

async with file 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. Удаляет файл даже при исключении в блоке. Ошибка очистки не заменяет исходную ошибку. Исключения блока не подавляются.

Права

Нужны files.write. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

async with file as active:
    pass