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

app.files

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

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

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

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

__init__

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

def __init__(app: App) -> None: ...

Аргументы

• app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.

Результат

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

Права

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

Ошибки

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

Пример

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

__call__

Создаёт объект файла по ID. Метаданные можно передать из ранее полученного ответа.

def __call__(id: str, data: FileInfo | None = None) -> File: ...

Аргументы

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

Результат

File. Создаёт объект файла по ID. Метаданные можно передать из ранее полученного ответа.

Права

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

Ошибки

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

Пример

result = app.files("object-id")

writer

Создаёт поток загрузки с заранее известным размером и необязательной SHA256.

def writer(filename: str, size: int, sha256: str | None = None, ttl: int | None = None) -> Writer: ...

Аргументы

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

Результат

Writer. Создаёт поток загрузки с заранее известным размером и необязательной SHA256.

Права

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

Ошибки

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

Пример

result = app.files.writer("note.txt", 1024)

store

Загружает bytes и возвращает объект готового файла.

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

Аргументы

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

Результат

File. Загружает bytes и возвращает объект готового файла.

Права

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

Ошибки

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

Пример

file = await app.files.store("note.txt", b"Hello", ttl=3600)

iter

Перебирает доступные файлы с автоматическим переходом между порциями.

async def iter(limit: int = 100) -> AsyncIterator[File]: ...

Аргументы

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

Результат

AsyncIterator[File]. Перебирает доступные файлы с автоматическим переходом между порциями.

Права

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

Ошибки

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

Пример

async for value in app.files.iter():
    break

upload

Загружает bytes частями до 64 KiB, проверяет SHA256 и возвращает метаданные готового файла. При неудаче пытается удалить незавершённый файл.

async def upload(filename: str, data: JSON, ttl: int | None = None) -> FileInfo: ...

Аргументы

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

Результат

FileInfo. Загружает bytes частями до 64 KiB, проверяет SHA256 и возвращает метаданные готового файла. При неудаче пытается удалить незавершённый файл.

Права

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

Ошибки

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

Пример

file = await app.files.upload("note.txt", b"Hello", ttl=3600)

chunks

Читает файл порциями до size байт с проверкой смещения и продвижения потока.

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

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.
• size: int, по умолчанию 65536. Число байт одной порции, целое от 1 до 65536.

Результат

AsyncIterator[bytes]. Читает файл порциями до size байт с проверкой смещения и продвижения потока.

Права

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

Ошибки

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

Пример

async for value in app.files.chunks("object-id"):
    break

delete

Удаляет файл и освобождает занятое им место.

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

Аргументы

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

Результат

bool. Удаляет файл и освобождает занятое им место.

Права

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

Ошибки

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

Пример

result = await app.files.delete("object-id")

list

Получает порцию доступных файлов и курсор следующей порции.

async def list(**data: JSON) -> FilesPage: ...

Аргументы

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

Результат

FilesPage. Получает порцию доступных файлов и курсор следующей порции.

Права

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

Ошибки

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

Пример

result = await app.files.list(limit=20)