maxapi-python 1.2.4__tar.gz → 2.0.0__tar.gz

{maxapi_python-1.2.4 → maxapi_python-2.0.0}/.github/workflows/publish.yml

@@ -21,8 +21,10 @@ jobs:
           python-version: "3.10"
 
       - name: Build release distributions
-        run: |
-          uv build
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check dist/*
 
       - name: Upload distributions
         uses: actions/upload-artifact@v4
@@ -32,8 +34,14 @@ jobs:
 
   pypi-publish:
     runs-on: ubuntu-latest
-    needs:
-      - release-build
+    needs: release-build
+    environment:
+      name: pypi
+      url: https://pypi.org/project/maxapi-python/
+
+    permissions:
+      contents: read
+      id-token: write
 
     steps:
       - name: Retrieve release distributions
@@ -42,13 +50,5 @@ jobs:
           name: release-dists
           path: dist/
 
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          python-version: "3.10"
-
       - name: Publish release distributions to PyPI
-        env:
-          TOKEN: ${{ secrets.PYPI_API_TOKEN }}
-        run: |
-          uv publish -t $TOKEN
+        uses: pypa/gh-action-pypi-publish@release/v1

maxapi_python-2.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Build artifacts
+build/
+dist/
+wheels/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tool caches
+.mypy_cache/
+.pyright/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Sphinx
+docs/_build/
+
+# Local/runtime artifacts
+.codex/
+.agents/
+cache/
+cache*/
+*.db
+*.sqlite
+*.sqlite3
+
+# Local experiments
+tests2/
+
+# OS/editor
+.DS_Store
+.idea/
+.vscode/

maxapi_python-2.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: maxapi-python
+Version: 2.0.0
+Summary: Python wrapper для API мессенджера Max
+Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
+Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
+Project-URL: Issues, https://github.com/MaxApiTeam/PyMax/issues
+Project-URL: Documentation, https://maxapiteam.github.io/PyMax/
+Author-email: ink <inkdev@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,asyncio,max,messenger,tcp,websocket,wrapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: aiohttp>=3.13.5
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: python-socks[asyncio]>=2.8.1
+Requires-Dist: qrcode>=8.2
+Requires-Dist: websockets>=16.0
+Provides-Extra: docs
+Requires-Dist: furo>=2025.12.19; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
+Requires-Dist: sphinx>=8.1.3; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# PyMax
+
+Python-библиотека для Max API.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+
+> [!WARNING]
+> PyMax использует неофициальный внутренний API Max. API может измениться без
+> предупреждения, а использование библиотеки может нарушать условия сервиса.
+> Вы используете PyMax на свой риск; авторы и контрибьюторы не несут
+> ответственности за блокировки аккаунтов, потерю данных или другие последствия.
+
+## Что это
+
+**PyMax** - асинхронная Python-библиотека для внутреннего API Max. Она умеет
+авторизоваться в аккаунте, слушать события, отправлять сообщения, работать с
+чатами, пользователями, файлами, сессиями и доменными типами Max через TCP или
+WebSocket.
+
+## Возможности
+
+- Авторизация по телефону и SMS-коду через `Client`.
+- QR-авторизация web-клиента через `WebClient`.
+- Роутеры, фильтры, `on_start`, raw-события и typed events.
+- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Чаты, группы, участники, invite-ссылки и настройки групп.
+- Пользователи, контакты, профиль, папки, активные сессии и 2FA.
+- Вложения: `Photo`, `File`, `Video`.
+- SQLite-сессии, sync-state, reconnect и debug-логи.
+- Pydantic-модели и удобные domain-объекты.
+
+## Установка
+
+Требуется Python 3.10 или новее.
+
+```bash
+pip install -U maxapi-python
+```
+
+Через `uv`:
+
+```bash
+uv add -U maxapi-python
+```
+
+Напрямую из репозитория:
+
+```bash
+pip install git+https://github.com/MaxApiTeam/PyMax.git
+```
+
+## Быстрый старт
+
+`Client` использует TCP-соединение. При первом запуске PyMax попросит SMS-код
+и сохранит сессию в SQLite-файл; дальше этот файл используется автоматически.
+
+```python
+import asyncio
+
+from pymax import Client, Message
+
+client = Client(
+    phone="+79990000000",
+    work_dir="cache",
+    session_name="main.db",
+)
+
+
+@client.on_start()
+async def on_start(client: Client) -> None:
+    print("Клиент запущен")
+    print("Ваш ID:", client.me.contact.id if client.me else "unknown")
+
+
+@client.on_message()
+async def on_message(message: Message, client: Client) -> None:
+    print(message.chat_id, message.sender, message.text)
+
+    if message.chat_id is not None and message.text:
+        await message.answer("Привет от PyMax")
+
+
+async def main() -> None:
+    await client.start()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## WebClient
+
+`WebClient` использует WebSocket и QR-авторизацию:
+
+```python
+import asyncio
+
+from pymax import WebClient
+
+client = WebClient(work_dir="cache", session_name="web.db")
+
+
+@client.on_start()
+async def on_start(client: WebClient) -> None:
+    print("Web-клиент запущен")
+
+
+asyncio.run(client.start())
+```
+
+## Роутеры
+
+Обработчики можно регистрировать на клиенте или вынести в отдельный роутер.
+Handler всегда принимает событие и клиента: `(event, client)`.
+
+```python
+from pymax import Client, ClientRouter, Message
+
+router = ClientRouter()
+
+
+def is_start(message: Message) -> bool:
+    return message.text == "/start"
+
+
+@router.on_message(is_start)
+async def start(message: Message, client: Client) -> None:
+    await message.answer("Готово")
+
+
+client = Client(phone="+79990000000", work_dir="cache")
+client.include_router(router)
+```
+
+## Куда дальше
+
+- [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
+- [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
+- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Files](docs/files.rst) - отправка и скачивание файлов.
+- [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
+  проблемы.
+
+Опубликованная документация:
+
+- [docs.pymax.org](https://docs.pymax.org/)
+- [DeepWiki](https://deepwiki.com/MaxApiTeam/PyMax)
+
+## Разработка
+
+```bash
+uv sync --all-groups
+uv run python -c "import pymax; print(pymax.__all__)"
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+## Ссылки
+
+- [GitHub](https://github.com/MaxApiTeam/PyMax)
+- [PyPI](https://pypi.org/project/maxapi-python/)
+- [Telegram](https://t.me/pymax_news)
+
+## Лицензия
+
+Проект распространяется под лицензией MIT. Подробности см. в [LICENSE](LICENSE).
+
+## Авторы
+
+- [ink](https://github.com/ink-developer) - основной разработчик, исследование
+  API и документация.
+- [noxzion](https://github.com/noxzion) - оригинальный автор проекта.

maxapi_python-2.0.0/README.md

@@ -0,0 +1,174 @@
+# PyMax
+
+Python-библиотека для Max API.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+
+> [!WARNING]
+> PyMax использует неофициальный внутренний API Max. API может измениться без
+> предупреждения, а использование библиотеки может нарушать условия сервиса.
+> Вы используете PyMax на свой риск; авторы и контрибьюторы не несут
+> ответственности за блокировки аккаунтов, потерю данных или другие последствия.
+
+## Что это
+
+**PyMax** - асинхронная Python-библиотека для внутреннего API Max. Она умеет
+авторизоваться в аккаунте, слушать события, отправлять сообщения, работать с
+чатами, пользователями, файлами, сессиями и доменными типами Max через TCP или
+WebSocket.
+
+## Возможности
+
+- Авторизация по телефону и SMS-коду через `Client`.
+- QR-авторизация web-клиента через `WebClient`.
+- Роутеры, фильтры, `on_start`, raw-события и typed events.
+- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Чаты, группы, участники, invite-ссылки и настройки групп.
+- Пользователи, контакты, профиль, папки, активные сессии и 2FA.
+- Вложения: `Photo`, `File`, `Video`.
+- SQLite-сессии, sync-state, reconnect и debug-логи.
+- Pydantic-модели и удобные domain-объекты.
+
+## Установка
+
+Требуется Python 3.10 или новее.
+
+```bash
+pip install -U maxapi-python
+```
+
+Через `uv`:
+
+```bash
+uv add -U maxapi-python
+```
+
+Напрямую из репозитория:
+
+```bash
+pip install git+https://github.com/MaxApiTeam/PyMax.git
+```
+
+## Быстрый старт
+
+`Client` использует TCP-соединение. При первом запуске PyMax попросит SMS-код
+и сохранит сессию в SQLite-файл; дальше этот файл используется автоматически.
+
+```python
+import asyncio
+
+from pymax import Client, Message
+
+client = Client(
+    phone="+79990000000",
+    work_dir="cache",
+    session_name="main.db",
+)
+
+
+@client.on_start()
+async def on_start(client: Client) -> None:
+    print("Клиент запущен")
+    print("Ваш ID:", client.me.contact.id if client.me else "unknown")
+
+
+@client.on_message()
+async def on_message(message: Message, client: Client) -> None:
+    print(message.chat_id, message.sender, message.text)
+
+    if message.chat_id is not None and message.text:
+        await message.answer("Привет от PyMax")
+
+
+async def main() -> None:
+    await client.start()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## WebClient
+
+`WebClient` использует WebSocket и QR-авторизацию:
+
+```python
+import asyncio
+
+from pymax import WebClient
+
+client = WebClient(work_dir="cache", session_name="web.db")
+
+
+@client.on_start()
+async def on_start(client: WebClient) -> None:
+    print("Web-клиент запущен")
+
+
+asyncio.run(client.start())
+```
+
+## Роутеры
+
+Обработчики можно регистрировать на клиенте или вынести в отдельный роутер.
+Handler всегда принимает событие и клиента: `(event, client)`.
+
+```python
+from pymax import Client, ClientRouter, Message
+
+router = ClientRouter()
+
+
+def is_start(message: Message) -> bool:
+    return message.text == "/start"
+
+
+@router.on_message(is_start)
+async def start(message: Message, client: Client) -> None:
+    await message.answer("Готово")
+
+
+client = Client(phone="+79990000000", work_dir="cache")
+client.include_router(router)
+```
+
+## Куда дальше
+
+- [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
+- [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
+- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Files](docs/files.rst) - отправка и скачивание файлов.
+- [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
+  проблемы.
+
+Опубликованная документация:
+
+- [docs.pymax.org](https://docs.pymax.org/)
+- [DeepWiki](https://deepwiki.com/MaxApiTeam/PyMax)
+
+## Разработка
+
+```bash
+uv sync --all-groups
+uv run python -c "import pymax; print(pymax.__all__)"
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+## Ссылки
+
+- [GitHub](https://github.com/MaxApiTeam/PyMax)
+- [PyPI](https://pypi.org/project/maxapi-python/)
+- [Telegram](https://t.me/pymax_news)
+
+## Лицензия
+
+Проект распространяется под лицензией MIT. Подробности см. в [LICENSE](LICENSE).
+
+## Авторы
+
+- [ink](https://github.com/ink-developer) - основной разработчик, исследование
+  API и документация.
+- [noxzion](https://github.com/noxzion) - оригинальный автор проекта.

maxapi_python-2.0.0/docs/_static/.gitkeep

@@ -0,0 +1 @@
+

maxapi_python-2.0.0/docs/account.rst

@@ -0,0 +1,127 @@
+Account
+=======
+
+Что это
+-------
+
+Методы аккаунта работают с профилем текущего пользователя, папками чатов,
+активными сессиями и выходом из аккаунта. Они доступны напрямую на клиенте.
+
+Профиль
+-------
+
+После успешного login профиль текущего аккаунта лежит в ``client.me``:
+
+.. code-block:: python
+
+   @client.on_start()
+   async def on_start(client: Client) -> None:
+       if client.me is not None:
+           print(client.me.contact.id)
+
+Обновить имя, фамилию и описание:
+
+.. code-block:: python
+
+   await client.change_profile(
+       first_name="Alex",
+       last_name="PyMax",
+       description="Testing Max API",
+   )
+
+Фотография профиля
+------------------
+
+Сейчас ``change_profile(photo=...)`` не загружает файл напрямую. Для фото
+нужен ``photo_token`` от API Max:
+
+.. code-block:: python
+
+   upload_url = await client.request_profile_photo_upload_url()
+   print(upload_url)
+
+   await client.change_profile(
+       first_name="Alex",
+       photo_token="PHOTO_TOKEN",
+   )
+
+Если передать ``photo`` вместо ``photo_token``, PyMax выбросит
+``NotImplementedError``.
+
+Папки чатов
+-----------
+
+Создать папку:
+
+.. code-block:: python
+
+   update = await client.create_folder(
+       title="Работа",
+       chat_include=[123456, 234567],
+   )
+
+Получить список папок:
+
+.. code-block:: python
+
+   folders = await client.get_folders()
+   for folder in folders:
+       print(folder.id, folder.title)
+
+Обновить и удалить папку:
+
+.. code-block:: python
+
+   await client.update_folder(
+       folder_id="folder-id",
+       title="Новый заголовок",
+       chat_include=[123456],
+   )
+
+   await client.delete_folder("folder-id")
+
+``FolderList`` можно итерировать напрямую: он перебирает ``folders`` внутри
+ответа.
+
+Сессии и выход
+--------------
+
+Получить активные сессии:
+
+.. code-block:: python
+
+   sessions = await client.get_sessions()
+   for session in sessions:
+       print(session.id, session.device_name, session.current)
+
+Закрыть остальные сессии аккаунта:
+
+.. code-block:: python
+
+   await client.close_all_sessions()
+
+Выйти из текущей сессии Max:
+
+.. code-block:: python
+
+   await client.logout()
+   await client.close()
+
+``logout()`` завершает серверную сессию. ``close()`` закрывает локальное
+соединение, фоновые задачи и файл сессии.
+
+Частые ошибки
+-------------
+
+``client.me`` равен ``None``
+   Login еще не завершился или клиент не запущен. Читайте профиль внутри
+   ``on_start`` или после успешного ``await client.start()`` в собственном
+   lifecycle.
+
+``NotImplementedError`` при ``change_profile(photo=...)``
+   Прямая загрузка фото через параметр ``photo`` пока не реализована.
+   Используйте ``photo_token``.
+
+Папка создалась, но список старый
+   Используйте ``get_folders()`` после изменения и сохраняйте новый
+   ``folder_sync``, если строите собственную синхронизацию папок.

maxapi_python-2.0.0/docs/api/auth.rst

@@ -0,0 +1,35 @@
+Auth API
+========
+
+.. autoclass:: pymax.AuthFlow
+   :members:
+
+.. autoclass:: pymax.SmsAuthFlow
+   :members:
+
+.. autoclass:: pymax.QrAuthFlow
+   :members:
+
+.. autoclass:: pymax.SmsCodeProvider
+   :members:
+
+.. autoclass:: pymax.PasswordProvider
+   :members:
+
+.. autoclass:: pymax.auth.EmailCodeProvider
+   :members:
+
+.. autoclass:: pymax.QrHandler
+   :members:
+
+.. autoclass:: pymax.ConsoleSmsCodeProvider
+   :members:
+
+.. autoclass:: pymax.ConsolePasswordProvider
+   :members:
+
+.. autoclass:: pymax.auth.providers.ConsoleEmailCodeProvider
+   :members:
+
+.. autoclass:: pymax.ConsoleQrHandler
+   :members:

maxapi_python-2.0.0/docs/api/client.rst

@@ -0,0 +1,17 @@
+Client API
+==========
+
+.. currentmodule:: pymax
+
+.. autoclass:: Client
+   :members:
+   :inherited-members:
+
+.. autoclass:: WebClient
+   :members:
+   :inherited-members:
+
+.. autoclass:: ExtraConfig
+   :members:
+
+.. autofunction:: configure_logging

maxapi_python-2.0.0/docs/api/files.rst

@@ -0,0 +1,14 @@
+Files API
+=========
+
+.. autoclass:: pymax.File
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.Photo
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.Video
+   :members:
+   :show-inheritance:

maxapi_python-2.0.0/docs/api/router.rst

@@ -0,0 +1,10 @@
+Router API
+==========
+
+.. autoclass:: pymax.Router
+   :members:
+   :show-inheritance:
+
+.. autodata:: pymax.ClientRouter
+
+.. autodata:: pymax.WebRouter