Upload Limits¶

`maxapi.utils.upload_limits` ¶

Ограничения MAX API на загрузку медиафайлов.

Значения взяты из документации метода POST /uploads: https://dev.max.ru/docs-api/methods/POST/uploads

Тип	Форматы	Лимиты
`image`	JPG/JPEG/PNG/GIF/TIFF/BMP/HEIC	до 50 МБ, ≤7680×7680 px
`video`	MP4, MOV, MKV, WEBM	до 250 МБ
`audio`	MP3, WAV, M4A и др.	до 256 МБ, ≤60 мин
`file`	TXT, DOC, PDF и др.	до 4 ГБ

Для image и audio оба условия должны выполняться одновременно. Списки форматов не исчерпывающие: MAX принимает и другие распространённые форматы, здесь перечислены только явно указанные в документации.

Единицы измерения — явное допущение библиотеки. Документация MAX не уточняет, двоичные единицы имеются в виду или десятичные; здесь принимаются двоичные (МБ = 1024 ** 2, ГБ = 1024 ** 3). Если сервер трактует их как десятичные, файлы в диапазоне ~47.7–50 MiB предупреждения не получат, хотя сервер может их отклонить.

Заявленный лимит для file — 4 ГБ — это лимит сервера, а не библиотеки. BaseConnection.upload_file читает файл целиком в память перед отправкой, поэтому практический потолок ограничен доступной процессу оперативной памятью и обычно заметно ниже.

Проверка размера (check_upload_size) не бросает исключений: это осознанное решение. Ограничения на стороне API могут меняться, и библиотека не должна блокировать загрузку валидных файлов. При превышении лимита пишется предупреждение в логгер bot, а решение остаётся за сервером MAX. Проверка вызывается автоматически из BaseConnection.upload_file и BaseConnection.upload_file_buffer, то есть на любом пути загрузки.

Разрешение изображений и длительность аудио не проверяются: для этого потребовались бы внешние зависимости (декодеры медиа).

`UploadLimits(formats, max_size, max_dimensions=None, max_duration=None)` `dataclass` ¶

Ограничения на загрузку файла одного типа.

Attributes:

Name	Type	Description
`formats`	`tuple[str, ...]`	Форматы файлов, явно указанные в документации MAX. Список не исчерпывающий.
`max_size`	`int`	Максимальный размер файла в байтах (МБ = 1024 * 1024, ГБ = 1024 ** 3).
`max_dimensions`	`tuple[int, int] \| None`	Максимальные размеры изображения (ширина, высота) в пикселях, если ограничение есть.
`max_duration`	`int \| None`	Максимальная длительность в секундах, если ограничение есть.

`check_upload_size(size, type, *, name=None)` ¶

Проверяет размер файла против лимитов MAX API.

Исключений не бросает: лимиты на стороне API могут меняться, и библиотека не должна блокировать загрузку валидных файлов. При превышении лимита пишется предупреждение в логгер bot. Неизвестный тип загрузки считается допустимым — решение остаётся за сервером MAX.

Parameters:

Name	Type	Description	Default
`size`	`int`	Размер файла в байтах.	required
`type`	`UploadType \| str`	Тип загружаемого файла или его строковое значение.	required
`name`	`str \| None`	Имя файла для сообщения в логе.	`None`

Returns:

Type	Description
`bool`	True, если размер в пределах лимита, иначе False.

Source code in maxapi/utils/upload_limits.py

def check_upload_size(
    size: int,
    type: UploadType | str,
    *,
    name: str | None = None,
) -> bool:
    """
    Проверяет размер файла против лимитов MAX API.

    Исключений не бросает: лимиты на стороне API могут меняться, и
    библиотека не должна блокировать загрузку валидных файлов. При
    превышении лимита пишется предупреждение в логгер `bot`.
    Неизвестный тип загрузки считается допустимым — решение
    остаётся за сервером MAX.

    Args:
        size: Размер файла в байтах.
        type: Тип загружаемого файла или его строковое значение.
        name: Имя файла для сообщения в логе.

    Returns:
        True, если размер в пределах лимита, иначе False.
    """
    if not isinstance(type, UploadType):
        try:
            type = UploadType(type)
        except ValueError:
            return True

    limits = UPLOAD_LIMITS.get(type)
    if limits is None or size <= limits.max_size:
        return True

    file_desc = f" {name}" if name else ""
    logger_bot.warning(
        "Файл%s типа %s превышает лимит загрузки MAX: "
        "%s (%d байт) > %s (%d байт). "
        "Сервер может отклонить загрузку.",
        file_desc,
        type.value,
        _format_size(size),
        size,
        _format_size(limits.max_size),
        limits.max_size,
    )
    return False

Пример¶

from maxapi.enums.upload_type import UploadType
from maxapi.utils.upload_limits import (
    UPLOAD_LIMITS,
    check_upload_size,
)

limits = UPLOAD_LIMITS[UploadType.IMAGE]
print(limits.max_size, limits.max_dimensions)

# Мягкая проверка: пишет предупреждение в логгер `bot`
# и возвращает False, исключение не бросается.
ok = check_upload_size(
    100 * 1024 * 1024,
    UploadType.IMAGE,
    name="photo.png",
)

Проверка вызывается автоматически в BaseConnection.upload_file и BaseConnection.upload_file_buffer, то есть на любом пути загрузки: bot.upload_media, InputMedia/InputMediaBuffer в attachments, а также ручной bot.upload_file. Предупреждение появится в логах и без явного вызова check_upload_size.

Upload Limits¶

maxapi.utils.upload_limits ¶

UploadLimits(formats, max_size, max_dimensions=None, max_duration=None) dataclass ¶

check_upload_size(size, type, *, name=None) ¶

Пример¶

`maxapi.utils.upload_limits` ¶

`UploadLimits(formats, max_size, max_dimensions=None, max_duration=None)` `dataclass` ¶

`check_upload_size(size, type, *, name=None)` ¶