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

Media

Вложение из файла Cluster или bytes. Поддерживает photo, video, animation, audio, document, voice и video_note; gif нормализуется в animation.

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

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

media = app.media(b"example", filename="note.txt")

init

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

def __init__(file: str | bytes, kind: str = 'document', caption: str | Text = '', filename: str | None = None, **options: JSON) -> None: ...

Аргументы

file: str | bytes, обязательный. ID готового файла Cluster либо байты с обязательным filename. File передавай через file.id.
kind: str, по умолчанию 'document'. Тип photo, video, animation, audio, document, voice или video_note. gif является алиасом animation.
caption: str | Text, по умолчанию ''. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
filename: str | None, по умолчанию None. Подпись файла до 255 байт UTF-8 без управляющих символов. None сохраняет исходное имя только у File.copy().
options: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

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

Права

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

Ошибки

ValueError('Invalid media type'): условие проверяется до продолжения операции.
TypeError('A Cluster file ID or bytes are required'): условие проверяется до продолжения операции.
ValueError('A filename is required for bytes'): условие проверяется до продолжения операции.
ValueError('Attachment fields are managed by the media object'): условие проверяется до продолжения операции.

Пример

media = app.media(b"Hello", filename="note.txt")

resolve

Возвращает ID файла. Байты загружает один раз на каждый App и кэширует полученный ID.

async def resolve(app: App) -> str: ...

Аргументы

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

Результат

str. Возвращает ID файла. Байты загружает один раз на каждый App и кэширует полученный ID.

Права

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

Ошибки

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

Пример

result = await media.resolve(app)

describe

Возвращает описание с file и type, при необходимости предварительно загружая bytes.

async def describe(app: App) -> dict[str, str]: ...

Аргументы

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

Результат

dict[str, str]. Возвращает описание с file и type, при необходимости предварительно загружая bytes.

Права

Ошибки

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

Пример

result = await media.describe(app)