Сделать поля PhotoAttachmentPayload опциональными согласно официальному API

[max92110]

Что изменено

В модели PhotoAttachmentPayload обновлены типы полей: значения, которые в официальной документации MAX API могут отсутствовать, теперь помечены как опциональные.

Это приводит типизацию библиотеки в соответствие с актуальным контрактом API и позволяет корректно обрабатывать payload фото-вложений, где часть данных не возвращается сервером.

Почему это нужно

Согласно официальной документации MAX API, поля в payload фото-вложений не гарантируются как обязательные. Ранее модель ожидала их наличие всегда, из-за чего могли возникать ошибки валидации при обработке корректных ответов API, если некоторые поля отсутствовали.

Что это исправляет

• Устраняет некорректную строгую типизацию PhotoAttachmentPayload.
• Предотвращает ошибки при парсинге сообщений с фото-вложениями.
• Повышает совместимость с официальным API MAX.
• Делает модель данных более устойчивой к неполному payload от сервера.

Совместимость

Изменение обратно совместимо: существующий код, который работает с заполненными полями PhotoAttachmentPayload, продолжит работать как раньше. При этом пользователям теперь нужно учитывать, что эти поля могут быть None.

Ссылка на документацию

Официальная документация API:
https://dev.max.ru/docs-api/objects/NewMessageBody

[K1rL3s]

Не стоит путать PhotoAttachmentPayload и PhotoAttachmentRequestPayload. В первом обязательно всё, во втором - одно

https://dev.max.ru/docs-api/objects/Message

maxapi/maxapi/types/attachments/attachment.py

Lines 28 to 41 in c7569bb

	class PhotoAttachmentPayload(BaseModel):
	"""
	Данные для фото-вложения.
	Attributes:
	photo_id: Идентификатор фотографии.
	token: Токен для доступа к фото.
	url: URL фотографии.
	"""
	photo_id: int
	token: str
	url: str

maxapi/maxapi/types/attachments/image.py

Lines 20 to 33 in c7569bb

	class PhotoAttachmentRequestPayload(BaseModel):
	"""
	Полезная нагрузка для запроса фото-вложения.
	Attributes:
	url: URL изображения.
	token: Токен существующего вложения.
	photos: Токены, полученные после загрузки изображений.
	"""
	url: str | None = None
	token: str | None = None
	photos: dict[str, PhotoToken] | str | None = None

[Copilot]

Pull request overview

PR приводит модель PhotoAttachmentPayload в соответствие с контрактом MAX API, позволяя корректно валидировать payload фото-вложений при отсутствии части полей. Однако в PR также попали изменения поведения Dispatcher.handle() и .python-version, которые не относятся к заявленной цели и меняют контракт/окружение разработки.

Changes:

• Сделаны опциональными поля photo_id/token/url в PhotoAttachmentPayload.
• В Dispatcher.handle() добавлено повторное пробрасывание исключений после логирования (меняет контракт обработки ошибок).
• Обновлён .python-version с 3.10 на 3.12.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
maxapi/types/attachments/attachment.py	Делает поля payload фото-вложений опциональными, чтобы не падать на неполных ответах API.
maxapi/dispatcher.py	Меняет поведение обработки ошибок: исключения начинают всплывать из handle().
.python-version	Меняет локально рекомендуемую версию Python на 3.12 (вне заявленного скоупа PR).

---

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