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

Album

Альбом из 2..10 элементов. Можно сочетать фото и видео либо отправить только аудио или только документы.

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

album = app.album(ctx)

Для send() добавлены 2..10 совместимых вложений. message() и close() используют уже отправленный альбом.

init

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

def __init__(app: App, context: Event | int | None = None, source: str | None = None) -> None: ...

Аргументы

app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.
context: Event | int | None, по умолчанию None. Текущее событие либо числовой чат. None допустимо, если чат будет передан позже.
source: str | None, по умолчанию None. Источник telegram или bot; None наследует контекст у конструкторов сообщений.

Результат

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

Права

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

Ошибки

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

Пример

# Обычный способ получения объекта:
album = app.album(ctx)

add

Добавляет Media или описание файла до отправки альбома.

def add(media: Media | str | bytes, kind: str = 'photo', caption: str | Text = '', **data: JSON) -> Self: ...

Аргументы

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

Результат

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

Права

Ошибки

ValueError('A sent album cannot be reordered'): условие проверяется до продолжения операции.
ValueError('An album can contain at most 10 items'): условие проверяется до продолжения операции.

Пример

result = album.add("file-id", parse_mode="HTML")

remove

Удаляет элемент до отправки и возвращает объект Media.

def remove(index: int) -> Media: ...

Аргументы

index: int, обязательный. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.

Результат

Media. Удаляет элемент до отправки и возвращает объект Media.

Права

Ошибки

ValueError('A sent album cannot be reordered'): условие проверяется до продолжения операции.

Пример

result = album.remove(0)

move

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

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

Аргументы

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

Результат

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

Права

Ошибки

ValueError('A sent album cannot be reordered'): условие проверяется до продолжения операции.
IndexError('Invalid album position'): условие проверяется до продолжения операции.

Пример

result = album.move(0, app.modules("dependency-id"))

sort

Сортирует элементы до отправки по key либо подписи без учёта регистра.

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

Аргументы

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

Результат

Self. Тот же объект после успешной операции. Сортирует элементы до отправки по key либо подписи без учёта регистра.

Права

Ошибки

ValueError('A sent album cannot be reordered'): условие проверяется до продолжения операции.

Пример

result = album.sort()

send

Отправляет совместимые вложения через Telegram или личного бота. Приватные альбомы внутри групп не поддерживаются Telegram.

async def send(chat: int | None = None, **options: JSON) -> Self: ...

Аргументы

chat: int | None, по умолчанию None. Числовой ID чата Telegram, включая отрицательный ID группы или канала. None использует контекст только у методов с таким поведением.
options: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

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

Права

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

Ошибки

ValueError('The album has already been sent'): условие проверяется до продолжения операции.
ValueError('Telegram does not support private albums inside groups'): условие проверяется до продолжения операции.
ValueError('An album needs between 2 and 10 items'): условие проверяется до продолжения операции.
ValueError('Use photos with videos, only audio, or only documents'): условие проверяется до продолжения операции.
ValueError('An album chat is required'): условие проверяется до продолжения операции.
ValueError('Unknown message source'): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await album.send(parse_mode="HTML")

message

Возвращает и кэширует объект отдельного сообщения отправленного альбома для редактирования или удаления.

def message(index: int) -> Message: ...

Аргументы

index: int, обязательный. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.

Результат

Message. Возвращает и кэширует объект отдельного сообщения отправленного альбома для редактирования или удаления.

Права

Ошибки

ValueError('The album has not been sent'): условие проверяется до продолжения операции.
IndexError('Invalid album position'): условие проверяется до продолжения операции.

Пример

result = album.message(0)

close

Удаляет ещё не удалённые сообщения отправленного альбома. При частичной ошибке повторный вызов продолжает с оставшихся.

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

Аргументы

Нет.

Результат

bool. Удаляет ещё не удалённые сообщения отправленного альбома. При частичной ошибке повторный вызов продолжает с оставшихся.

Права

Ошибки

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

Пример

result = await album.close()