maxpyin 0.1.0__tar.gz

maxpyin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxpyin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maxpyin-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: maxpyin
+Version: 0.1.0
+Summary: Синхронный и асинхронный клиент Bot API мессенджера MAX
+Author: evsikov-a
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/evsikov-a/maxpyin
+Project-URL: Repository, https://github.com/evsikov-a/maxpyin
+Project-URL: Issues, https://github.com/evsikov-a/maxpyin/issues
+Project-URL: Changelog, https://github.com/evsikov-a/maxpyin/releases
+Project-URL: MAX API, https://dev.max.ru/docs-api
+Keywords: max,maxpyin,bot,messenger,chat,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Dynamic: license-file
+
+# maxpyin
+
+Синхронный и асинхронный клиент [Bot API мессенджера MAX](https://dev.max.ru/docs-api).
+Один и тот же набор методов доступен через `MaxBot` и `AsyncMaxBot`.
+
+Запросы идут на `https://platform-api2.max.ru`. Токен передаётся только
+в заголовке `Authorization`.
+
+## Установка
+
+Нужен Python 3.10 или новее.
+
+```bash
+pip install maxpyin
+```
+
+Для разработки из этого репозитория:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Токен бота лежит в кабинете MAX: Чат-боты → нужный бот → Настройки.
+Положите его в переменную окружения и не записывайте в код.
+
+```bash
+export MAX_BOT_TOKEN="сюда-токен"
+```
+
+### Синхронный echo
+
+Бот отвечает тем же текстом и добавляет две кнопки. В личном диалоге
+сообщение уходит по `user_id`, в чате и канале — по `chat_id`.
+
+```python
+import os
+
+from maxpyin import CallbackButton, InlineKeyboard, MaxBot
+
+
+def main() -> None:
+    token = os.environ["MAX_BOT_TOKEN"]
+    with MaxBot(token) as bot:
+        print(bot.get_me().first_name)
+        for update in bot.poll(
+            types=["message_created", "message_callback"],
+        ):
+            callback = update.callback
+            if (
+                update.update_type == "message_callback"
+                and callback is not None
+                and callback.callback_id
+            ):
+                bot.answer_callback(
+                    callback.callback_id,
+                    notification="Принято",
+                )
+                continue
+            message = update.message
+            if (
+                message is None
+                or message.body is None
+                or message.sender is None
+                or message.sender.is_bot
+                or message.recipient is None
+            ):
+                continue
+            if message.recipient.chat_type == "dialog":
+                user_id, chat_id = message.sender.user_id, None
+            else:
+                user_id, chat_id = None, message.recipient.chat_id
+            keyboard = InlineKeyboard().add(
+                CallbackButton("Да", "yes"),
+                CallbackButton("Нет", "no"),
+            )
+            bot.send_message(
+                message.body.text or "",
+                user_id=user_id,
+                chat_id=chat_id,
+                attachments=[keyboard],
+            )
+
+
+if __name__ == "__main__":
+    main()
+```
+
+`poll` подходит для разработки. В рабочем боте используйте Webhook:
+пока подписка активна, long polling события не получает.
+
+### Асинхронный echo
+
+```python
+import asyncio
+import os
+
+from maxpyin import AsyncMaxBot
+
+
+async def main() -> None:
+    token = os.environ["MAX_BOT_TOKEN"]
+    async with AsyncMaxBot(token) as bot:
+        me = await bot.get_me()
+        print(me.username)
+        async for update in bot.poll(types=["message_created"]):
+            message = update.message
+            if (
+                message is None
+                or message.body is None
+                or message.sender is None
+                or message.sender.is_bot
+                or message.recipient is None
+            ):
+                continue
+            if message.recipient.chat_type == "dialog":
+                user_id, chat_id = message.sender.user_id, None
+            else:
+                user_id, chat_id = None, message.recipient.chat_id
+            await bot.send_message(
+                message.body.text or "",
+                user_id=user_id,
+                chat_id=chat_id,
+            )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Клавиатура и callback
+
+`CallbackButton` возвращает `payload` в событии `message_callback`.
+`LinkButton` просто открывает адрес. Ответ на нажатие:
+
+```python
+from maxpyin import LinkButton
+
+keyboard = InlineKeyboard().add(
+    CallbackButton("Да", "yes"),
+    LinkButton("Сайт", "https://example.com"),
+)
+bot.answer_callback(
+    callback_id,
+    text="Вы выбрали ответ",
+    attachments=[keyboard],
+    notification="Готово",
+)
+```
+
+### Webhook
+
+Подписка принимает только `https://` на порту 443. Секрет бот присылает
+в заголовке `X-Max-Bot-Api-Secret`.
+
+```python
+from maxpyin import parse_update
+
+bot.subscribe(
+    "https://example.com/max/webhook",
+    update_types=["message_created", "message_callback"],
+    secret="replace-me",
+)
+
+update = parse_update(request_json)
+bot.unsubscribe("https://example.com/max/webhook")
+```
+
+Свой HTTP-сервер библиотека не поднимает: разберите тело запроса
+через `parse_update` в том фреймворке, который уже обслуживает сайт.
+
+### Файл
+
+Сначала библиотека получает URL загрузки, затем отправляет байты.
+Токен из ответа кладётся во вложение.
+
+```python
+uploaded = bot.upload_media("file", "notes.txt")
+bot.send_message(
+    "Файл",
+    chat_id=chat_id,
+    attachments=[uploaded.as_attachment("file")],
+)
+```
+
+Если сервер ответит, что вложение ещё не обработано, подождите
+и отправьте сообщение с тем же токеном ещё раз.
+
+### Сертификат Минцифры
+
+Если проверка TLS не проходит, передайте корпоративный или
+государственный корневой сертификат:
+
+```python
+bot = MaxBot(
+    token,
+    verify="/path/to/russian_trusted_root_ca.cer",
+)
+```
+
+Другой адрес API задаётся параметром `base_url`.
+
+## Что умеет клиент
+
+Оба класса покрывают текущие методы бота:
+
+- профиль и команды: `get_me`, `edit_me`, `set_commands`;
+- чат: карточка, правка, удаление, действие «печатает», закреп,
+  участники, администраторы, выход бота;
+- сообщения: отправка, правка, удаление, одно сообщение и история;
+- ответ на кнопку: `answer_callback`;
+- загрузка `image`, `video`, `audio` и `file`;
+- комментарии к посту канала;
+- подписки Webhook и long polling.
+
+`GET /chats` с июня 2026 не поддерживается, поэтому метода списка чатов
+нет: `chat_id` приходит в событиях `bot_added` и `bot_started`.
+Добавление участников методом `POST /chats/{chatId}/members` платформа
+снимает, и библиотека его не вызывает.
+
+Ответы 429 и 503 повторяются несколько раз. Число попыток задаёт
+`max_retries` (по умолчанию 2 повтора после первого запроса).
+
+## Ошибки
+
+- `MaxAuthError` — HTTP 401, токен недействителен;
+- `MaxRateLimitError` — HTTP 429, повторы закончились;
+- `MaxApiError` — другая ошибка API, в том числе `success: false`;
+- `MaxNetworkError` — таймаут или обрыв сети;
+- `ValueError` — аргументы не проходят проверку до запроса.
+
+У `MaxApiError` есть `status_code`, `code` и `payload`.
+
+## Лицензия
+
+MIT. Текст лежит в файле `LICENSE`.

maxpyin-0.1.0/README.md

@@ -0,0 +1,237 @@
+# maxpyin
+
+Синхронный и асинхронный клиент [Bot API мессенджера MAX](https://dev.max.ru/docs-api).
+Один и тот же набор методов доступен через `MaxBot` и `AsyncMaxBot`.
+
+Запросы идут на `https://platform-api2.max.ru`. Токен передаётся только
+в заголовке `Authorization`.
+
+## Установка
+
+Нужен Python 3.10 или новее.
+
+```bash
+pip install maxpyin
+```
+
+Для разработки из этого репозитория:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+Токен бота лежит в кабинете MAX: Чат-боты → нужный бот → Настройки.
+Положите его в переменную окружения и не записывайте в код.
+
+```bash
+export MAX_BOT_TOKEN="сюда-токен"
+```
+
+### Синхронный echo
+
+Бот отвечает тем же текстом и добавляет две кнопки. В личном диалоге
+сообщение уходит по `user_id`, в чате и канале — по `chat_id`.
+
+```python
+import os
+
+from maxpyin import CallbackButton, InlineKeyboard, MaxBot
+
+
+def main() -> None:
+    token = os.environ["MAX_BOT_TOKEN"]
+    with MaxBot(token) as bot:
+        print(bot.get_me().first_name)
+        for update in bot.poll(
+            types=["message_created", "message_callback"],
+        ):
+            callback = update.callback
+            if (
+                update.update_type == "message_callback"
+                and callback is not None
+                and callback.callback_id
+            ):
+                bot.answer_callback(
+                    callback.callback_id,
+                    notification="Принято",
+                )
+                continue
+            message = update.message
+            if (
+                message is None
+                or message.body is None
+                or message.sender is None
+                or message.sender.is_bot
+                or message.recipient is None
+            ):
+                continue
+            if message.recipient.chat_type == "dialog":
+                user_id, chat_id = message.sender.user_id, None
+            else:
+                user_id, chat_id = None, message.recipient.chat_id
+            keyboard = InlineKeyboard().add(
+                CallbackButton("Да", "yes"),
+                CallbackButton("Нет", "no"),
+            )
+            bot.send_message(
+                message.body.text or "",
+                user_id=user_id,
+                chat_id=chat_id,
+                attachments=[keyboard],
+            )
+
+
+if __name__ == "__main__":
+    main()
+```
+
+`poll` подходит для разработки. В рабочем боте используйте Webhook:
+пока подписка активна, long polling события не получает.
+
+### Асинхронный echo
+
+```python
+import asyncio
+import os
+
+from maxpyin import AsyncMaxBot
+
+
+async def main() -> None:
+    token = os.environ["MAX_BOT_TOKEN"]
+    async with AsyncMaxBot(token) as bot:
+        me = await bot.get_me()
+        print(me.username)
+        async for update in bot.poll(types=["message_created"]):
+            message = update.message
+            if (
+                message is None
+                or message.body is None
+                or message.sender is None
+                or message.sender.is_bot
+                or message.recipient is None
+            ):
+                continue
+            if message.recipient.chat_type == "dialog":
+                user_id, chat_id = message.sender.user_id, None
+            else:
+                user_id, chat_id = None, message.recipient.chat_id
+            await bot.send_message(
+                message.body.text or "",
+                user_id=user_id,
+                chat_id=chat_id,
+            )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Клавиатура и callback
+
+`CallbackButton` возвращает `payload` в событии `message_callback`.
+`LinkButton` просто открывает адрес. Ответ на нажатие:
+
+```python
+from maxpyin import LinkButton
+
+keyboard = InlineKeyboard().add(
+    CallbackButton("Да", "yes"),
+    LinkButton("Сайт", "https://example.com"),
+)
+bot.answer_callback(
+    callback_id,
+    text="Вы выбрали ответ",
+    attachments=[keyboard],
+    notification="Готово",
+)
+```
+
+### Webhook
+
+Подписка принимает только `https://` на порту 443. Секрет бот присылает
+в заголовке `X-Max-Bot-Api-Secret`.
+
+```python
+from maxpyin import parse_update
+
+bot.subscribe(
+    "https://example.com/max/webhook",
+    update_types=["message_created", "message_callback"],
+    secret="replace-me",
+)
+
+update = parse_update(request_json)
+bot.unsubscribe("https://example.com/max/webhook")
+```
+
+Свой HTTP-сервер библиотека не поднимает: разберите тело запроса
+через `parse_update` в том фреймворке, который уже обслуживает сайт.
+
+### Файл
+
+Сначала библиотека получает URL загрузки, затем отправляет байты.
+Токен из ответа кладётся во вложение.
+
+```python
+uploaded = bot.upload_media("file", "notes.txt")
+bot.send_message(
+    "Файл",
+    chat_id=chat_id,
+    attachments=[uploaded.as_attachment("file")],
+)
+```
+
+Если сервер ответит, что вложение ещё не обработано, подождите
+и отправьте сообщение с тем же токеном ещё раз.
+
+### Сертификат Минцифры
+
+Если проверка TLS не проходит, передайте корпоративный или
+государственный корневой сертификат:
+
+```python
+bot = MaxBot(
+    token,
+    verify="/path/to/russian_trusted_root_ca.cer",
+)
+```
+
+Другой адрес API задаётся параметром `base_url`.
+
+## Что умеет клиент
+
+Оба класса покрывают текущие методы бота:
+
+- профиль и команды: `get_me`, `edit_me`, `set_commands`;
+- чат: карточка, правка, удаление, действие «печатает», закреп,
+  участники, администраторы, выход бота;
+- сообщения: отправка, правка, удаление, одно сообщение и история;
+- ответ на кнопку: `answer_callback`;
+- загрузка `image`, `video`, `audio` и `file`;
+- комментарии к посту канала;
+- подписки Webhook и long polling.
+
+`GET /chats` с июня 2026 не поддерживается, поэтому метода списка чатов
+нет: `chat_id` приходит в событиях `bot_added` и `bot_started`.
+Добавление участников методом `POST /chats/{chatId}/members` платформа
+снимает, и библиотека его не вызывает.
+
+Ответы 429 и 503 повторяются несколько раз. Число попыток задаёт
+`max_retries` (по умолчанию 2 повтора после первого запроса).
+
+## Ошибки
+
+- `MaxAuthError` — HTTP 401, токен недействителен;
+- `MaxRateLimitError` — HTTP 429, повторы закончились;
+- `MaxApiError` — другая ошибка API, в том числе `success: false`;
+- `MaxNetworkError` — таймаут или обрыв сети;
+- `ValueError` — аргументы не проходят проверку до запроса.
+
+У `MaxApiError` есть `status_code`, `code` и `payload`.
+
+## Лицензия
+
+MIT. Текст лежит в файле `LICENSE`.

maxpyin-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maxpyin"
+dynamic = ["version"]
+description = "Синхронный и асинхронный клиент Bot API мессенджера MAX"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "evsikov-a" }]
+keywords = ["max", "maxpyin", "bot", "messenger", "chat", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/evsikov-a/maxpyin"
+Repository = "https://github.com/evsikov-a/maxpyin"
+Issues = "https://github.com/evsikov-a/maxpyin/issues"
+Changelog = "https://github.com/evsikov-a/maxpyin/releases"
+"MAX API" = "https://dev.max.ru/docs-api"
+
+[tool.setuptools.dynamic]
+version = { attr = "maxpyin._version.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+maxpyin = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 79
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "N", "D", "I"]
+ignore = ["D401"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]

maxpyin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maxpyin-0.1.0/src/maxpyin/__init__.py

@@ -0,0 +1,87 @@
+"""Клиент Bot API мессенджера MAX.
+
+Библиотека даёт два равноправных класса: синхронный ``MaxBot``
+и асинхронный ``AsyncMaxBot``.
+"""
+
+from ._version import __version__
+from .async_bot import AsyncMaxBot
+from .bot import MaxBot
+from .exceptions import (
+    MaxApiError,
+    MaxAuthError,
+    MaxError,
+    MaxNetworkError,
+    MaxRateLimitError,
+)
+from .keyboards import (
+    CallbackButton,
+    ChatButton,
+    InlineKeyboard,
+    LinkButton,
+    MessageButton,
+    OpenAppButton,
+    RequestContactButton,
+    RequestGeoLocationButton,
+)
+from .models import (
+    BotCommand,
+    Callback,
+    Chat,
+    ChatAdmin,
+    ChatMember,
+    ChatPermission,
+    CommentPage,
+    Message,
+    MessageLink,
+    SenderAction,
+    Subscription,
+    SuccessResult,
+    Update,
+    UpdatePage,
+    UpdateType,
+    UploadResult,
+    UploadSlot,
+    User,
+    parse_update,
+)
+from .transport import DEFAULT_BASE_URL
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncMaxBot",
+    "BotCommand",
+    "Callback",
+    "CallbackButton",
+    "Chat",
+    "ChatAdmin",
+    "ChatButton",
+    "ChatMember",
+    "ChatPermission",
+    "CommentPage",
+    "InlineKeyboard",
+    "LinkButton",
+    "MaxApiError",
+    "MaxAuthError",
+    "MaxBot",
+    "MaxError",
+    "MaxNetworkError",
+    "MaxRateLimitError",
+    "Message",
+    "MessageButton",
+    "MessageLink",
+    "OpenAppButton",
+    "RequestContactButton",
+    "RequestGeoLocationButton",
+    "SenderAction",
+    "Subscription",
+    "SuccessResult",
+    "Update",
+    "UpdatePage",
+    "UpdateType",
+    "UploadResult",
+    "UploadSlot",
+    "User",
+    "__version__",
+    "parse_update",
+]

maxpyin-0.1.0/src/maxpyin/_version.py

@@ -0,0 +1,3 @@
+"""Версия пакета maxpyin."""
+
+__version__ = "0.1.0"