feat: добавлен метод download_file для скачивания файлов

[bish-x]

Описание

Добавлен метод download_file для скачивания файлов (документы, аудио, изображения, стикеры) с сервера MAX.

closes #64

Что добавлено

Bot.ensure_session() — гарантированное получение HTTP-сессии

Вынесена логика создания/проверки сессии в отдельный метод. Ранее эта конструкция дублировалась в request(), upload_file(), upload_file_buffer(). Метод проверяет, что сессия существует и не закрыта, при необходимости создаёт новую.

BaseConnection.download_file(url, destination) — низкоуровневое скачивание

• Потоковое чтение через iter_chunked с настраиваемым размером чанка (константа DOWNLOAD_CHUNK_SIZE = 65536)
• Retry с экспоненциальным backoff при ошибках соединения и серверных ошибках (502/503/504) — аналогично request()
• Защита от path traversal: Path(filename).name отсекает ../../
• Автоматическое определение имени файла из Content-Disposition или MIME-type
• Использует aiofiles для асинхронной записи на диск

Bot.download_file(url, destination) — высокоуровневый метод

Пример использования:

@dp.message_created()
async def handle(event):
    for att in event.message.body.attachments:
        if att.payload and hasattr(att.payload, 'url'):
            path = await event.message.bot.download_file(
                url=att.payload.url,
                destination="/tmp/downloads",
            )
            print(f"Скачан файл: {path}")

URL для скачивания доступен в attachment.payload.url для типов: image, audio, file, sticker.

Учтённые замечания из PR #90

• Магическое число 65536 вынесено в константу DOWNLOAD_CHUNK_SIZE
• Логика создания сессии вынесена в Bot.ensure_session() (DRY)
• Добавлены тесты для скачивания
• Реализован retry/backoff аналогично request()
• В docstring указано, почему метод работает не через общий request()

Тестирование

• Все существующие тесты проходят (488 passed, 4 skipped — интеграционные)
• Добавлены тесты: успешное скачивание, path traversal защита, HTTP-ошибка, retry, ensure_session
• ruff check / ruff format — без замечаний

[Olegt0rr]

Отличная работа! Осталось ещё немного причесать дублирование

[Olegt0rr]

Логика backoff теперь дублируется в нескольких местах. Опять нарушаем dry. В идеале вынести в отдельный декоратор и навешивать его на нужные функции

[Copilot]

Pull request overview

PR добавляет поддержку скачивания пользовательских вложений (документы/аудио/изображения/стикеры) по URL в SDK MAX, а также выносит часть логики работы с HTTP-сессией в отдельный метод бота.

Changes:

• Добавлен низкоуровневый BaseConnection.download_file() со стриминговым чтением и retry/backoff.
• Добавлен высокоуровневый Bot.download_file() и Bot.ensure_session() для гарантированного получения aiohttp-сессии.
• Добавлены unit-тесты для download_file и ensure_session; обновлён экспорт исключений.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
maxapi/connection/base.py	Retry-helper _retry_request, рефакторинг request(), добавлен download_file() для потокового скачивания.
maxapi/bot.py	Добавлен ensure_session() и публичный метод download_file().
maxapi/exceptions/download_file.py	Добавлено новое исключение DownloadFileError.
maxapi/exceptions/__init__.py	Экспортирован DownloadFileError через __all__.
tests/test_download_file.py	Новые тесты на скачивание/ретраи/path traversal и ensure_session.
maxapi/utils/updates.py	Добавлен логгер и обработка ошибок при get_chat_member() в enrichment.
pyproject.toml	Ruff-исключение по сложности (C90) для maxapi/utils/updates.py.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

В download_file() ответ aiohttp не закрывается/не освобождается. При успешной загрузке после записи на диск стоит гарантированно освободить соединение (например, через try/finally с response.release()/response.close() или использовать async with session.get(...) as response). Сейчас при исключении в середине чтения (или при раннем выходе) соединение может остаться занятым и со временем привести к утечке соединений в пуле.

Suggested change

	if not response.ok:
	raise DownloadFileError(
	f"Ошибка при скачивании файла: HTTP {response.status}"
	)
	cd = response.content_disposition
	if cd and cd.filename:
	filename = Path(cd.filename).name
	else:
	ext = mimetypes.guess_extension(response.content_type or "") or ""
	filename = f"file{ext}"
	path = Path(destination) / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	return path
	try:
	if not response.ok:
	raise DownloadFileError(
	f"Ошибка при скачивании файла: HTTP {response.status}"
	)
	cd = response.content_disposition
	if cd and cd.filename:
	filename = Path(cd.filename).name
	else:
	ext = mimetypes.guess_extension(response.content_type or "") or ""
	filename = f"file{ext}"
	path = Path(destination) / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	return path
	finally:
	response.release()

[Copilot]

При not response.ok выбрасывается DownloadFileError без чтения/освобождения тела ответа. Чтобы не оставлять соединение в состоянии connection acquired, нужно перед raise вызвать await response.read() или response.release() (и аналогично в других ветках раннего выхода).

Suggested change

	if not response.ok:
	raise DownloadFileError(
	f"Ошибка при скачивании файла: HTTP {response.status}"
	)
	cd = response.content_disposition
	if cd and cd.filename:
	filename = Path(cd.filename).name
	else:
	ext = mimetypes.guess_extension(response.content_type or "") or ""
	filename = f"file{ext}"
	path = Path(destination) / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	return path
	try:
	if not response.ok:
	await response.read()
	raise DownloadFileError(
	f"Ошибка при скачивании файла: HTTP {response.status}"
	)
	cd = response.content_disposition
	if cd and cd.filename:
	filename = Path(cd.filename).name
	else:
	ext = mimetypes.guess_extension(response.content_type or "") or ""
	filename = f"file{ext}"
	path = Path(destination) / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	return path
	finally:
	response.release()

[Copilot]

download_file() пишет в Path(destination) / filename, но не гарантирует, что директория destination существует. Сейчас при передаче несуществующего пути метод упадёт с FileNotFoundError (мимо DownloadFileError). Стоит заранее создать директорию (mkdir(parents=True, exist_ok=True)) и/или обернуть ошибку записи в DownloadFileError, чтобы поведение соответствовало docstring.

Suggested change

	path = Path(destination) / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	destination_path = Path(destination)
	try:
	destination_path.mkdir(parents=True, exist_ok=True)
	path = destination_path / filename
	async with aiofiles.open(path, "wb") as f:
	async for chunk in response.content.iter_chunked(chunk_size):
	await f.write(chunk)
	except OSError as e:
	raise DownloadFileError(
	f"Ошибка при сохранении скачанного файла: {e}"
	) from e

[Copilot]

В request() по-прежнему вручную создаётся ClientSession через if not bot.session, при этом не учитывается кейс bot.session.closed == True и не используется новый Bot.ensure_session() (что заявлено в описании PR). Лучше заменить на session = await bot.ensure_session() и передавать session в _retry_request, чтобы избежать вызовов на закрытой сессии и убрать дублирование логики.

[Copilot]

В Bot.download_file() дефолт chunk_size=65536 дублирует значение константы DOWNLOAD_CHUNK_SIZE из maxapi/connection/base.py. Чтобы не расходиться при будущих изменениях, лучше использовать общую константу (импортировать её или прокинуть дефолт через BaseConnection.download_file).

[codecov]

Codecov Report

❌ Patch coverage is 97.50000% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
maxapi/connection/base.py	97.01%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!