matele 0.1.0__tar.gz

matele-0.1.0/.editorconfig

@@ -0,0 +1,35 @@
+# https://editorconfig.org — отступы табами во всём коде проекта.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = tab
+indent_size = tab
+tab_width = 4
+
+# Фронтенд исторически с шириной отступа 2.
+[*.{js,css,html,json}]
+tab_width = 2
+
+# YAML запрещает табы в отступах (спецификация), поэтому здесь пробелы.
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+# В Markdown таб означает блок кода, а два пробела в конце строки — перенос.
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false
+
+# Бинарные и вендорные файлы не трогаем.
+[*.{pem,db,png,ico}]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset

matele-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

matele-0.1.0/.github/dependabot.yml

@@ -0,0 +1,7 @@
+# Actions are pinned to commit SHAs; this keeps the pins up to date.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

matele-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            python: "3.13"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests tools examples
+      - name: Formatting (tabs, see .editorconfig)
+        run: ruff format --check src tests tools examples
+      - name: Types
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        run: basedpyright --pythonpath "$(which python)"
+      - name: Tests
+        run: python -m pytest -q --cov=matele --cov-report=term-missing:skip-covered --cov-fail-under=90
+      - name: Generated MAX models match the schema
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.12'
+        run: |
+          python tools/gen_max_models.py
+          git diff --exit-code src/matele/max/models.py

matele-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+# Builds the documentation site on every push and publishes it to GitHub
+# Pages from main.
+name: Docs
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ".[docs]"
+      - run: mkdocs build --strict
+        env:
+          NO_MKDOCS_2_WARNING: "1"
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

matele-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+# Publishes to PyPI when a version tag (v0.1.0, ...) is pushed.
+# Uses PyPI Trusted Publishing: no token is stored in the repository.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - name: The tag matches the package version
+        run: |
+          version=$(python -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('src/matele/__init__.py').read()).group(1))")
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $version"; exit 1; }
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

matele-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+site/
+.coverage
+htmlcov/

matele-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Изменения
+
+Версии нумеруются как `MAJOR.MINOR.PATCH`. До 1.0 ломающие изменения возможны в любой версии `0.x`, но каждое такое изменение записывается здесь в разделе «Ломающие изменения» вместе с тем, что нужно поправить в своём коде. Исправления без изменения API выходят как `PATCH`.
+
+## 0.1.0 (2026-11-10)
+
+Первая версия. Что в ней есть:
+
+- общий слой для MAX и Telegram: сообщения, кнопки, файлы, ответы на сообщения, статус «печатает…»
+- роутеры, фильтры, middleware, состояния с хранилищами в памяти, SQLite и Redis
+- типизированные данные кнопок
+- групповые чаты и события входа и выхода участников
+- меню в одном сообщении (`ctx.show()`)
+- меню команд из `@dp.command(..., description=...)`
+- мини-приложения: кнопка открытия и проверка `initData`
+- рассылки во все мессенджеры человека (`Hub`)
+- long polling и вебхуки (ASGI)
+- весь MAX Bot API с моделями из официальной схемы, `TelegramApi.call()` для любого метода Telegram
+- `FakeBot` для тестов без сети
+- `escape()` для текста, который пришёл снаружи: сообщения уходят как HTML
+- подпись данных кнопок (`callback_secret`), чтобы бот принимал только свои кнопки
+- доставка «минимум один раз» для polling и вебхуков (`at_least_once=True`)
+- ограничение числа одновременно обрабатываемых событий (`concurrency`, `max_pending`)
+- остановка по Ctrl+C и SIGTERM с ожиданием начатых хендлеров
+- блокировка разговора между процессами в `RedisStorage`
+- продолжение рассылки после перезапуска (`on_sent`)
+- лимит на размер скачиваемых файлов (`max_download`, по умолчанию 50 МБ)
+- документация на сайте https://cvsqwe.github.io/matele/

matele-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cvsqwe
+
+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.

matele-0.1.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: matele
+Version: 0.1.0
+Summary: One bot, two messengers: an async framework for MAX and Telegram bots
+Project-URL: Homepage, https://github.com/cvsqwe/matele
+Project-URL: Documentation, https://cvsqwe.github.io/matele/
+Project-URL: Source, https://github.com/cvsqwe/matele
+Project-URL: Issues, https://github.com/cvsqwe/matele/issues
+Project-URL: Changelog, https://github.com/cvsqwe/matele/blob/main/CHANGELOG.md
+Author: cvsqwe
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bot,framework,max,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Russian
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: certifi>=2024.2.2
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: basedpyright==1.40.2; extra == 'dev'
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5; extra == 'dev'
+Requires-Dist: ruff>=0.17.4; extra == 'dev'
+Requires-Dist: uvicorn>=0.29; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.6; extra == 'docs'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Provides-Extra: webhook
+Requires-Dist: uvicorn>=0.29; extra == 'webhook'
+Description-Content-Type: text/markdown
+
+# matele
+
+Фреймворк на Python для ботов, которые работают сразу в MAX и Telegram. Хендлеры пишутся один раз, а разницу между мессенджерами matele берёт на себя.
+
+Проект на ранней стадии: до версии 1.0 API ещё может меняться. Все изменения записываются в [CHANGELOG.md](https://github.com/cvsqwe/matele/blob/main/CHANGELOG.md).
+
+Документация с руководством: https://cvsqwe.github.io/matele/
+
+## Установка
+
+```bash
+pip install matele
+```
+
+Нужен Python 3.11 или новее. Для вебхуков добавьте `[webhook]`, для хранения состояния в Redis `[redis]`:
+
+```bash
+pip install "matele[webhook,redis]"
+```
+
+## Пример
+
+Бот, который здоровается, спрашивает имя и запоминает его. Один и тот же код работает в обоих мессенджерах:
+
+```python
+from matele import Button, CallbackData, Context, Dispatcher, Keyboard, State, callback, escape
+from matele.max import MaxBot
+from matele.telegram import TelegramBot
+
+dp = Dispatcher()
+ASK_NAME = State("ask_name")
+
+
+@callback("hello")
+class Hello(CallbackData):
+    lang: str
+
+
+@dp.command("start")
+async def start(ctx: Context):
+    keyboard = Keyboard([[Button("Русский", Hello("ru").pack()), Button("English", Hello("en").pack())]])
+    await ctx.reply("Привет! На каком языке говорим?", keyboard)
+
+
+@dp.callback(Hello)
+async def chose_language(ctx: Context, payload: Hello):
+    ctx.state.set(ASK_NAME)
+    ctx.state.update(lang=payload.lang)
+    await ctx.edit("Как тебя зовут?" if payload.lang == "ru" else "What's your name?")
+
+
+@dp.message(state=ASK_NAME)
+async def got_name(ctx: Context):
+    lang = ctx.state.get("lang")
+    ctx.state.clear()
+    await ctx.reply(f"Приятно познакомиться, {escape(ctx.text)}!" if lang == "ru" else f"Nice to meet you, {escape(ctx.text)}!")
+
+
+dp.run_polling(MaxBot(MAX_TOKEN), TelegramBot(TG_TOKEN))
+```
+
+Можно запустить только один из ботов, если второй мессенджер не нужен. Пример побольше лежит в [examples/two_messengers.py](https://github.com/cvsqwe/matele/blob/main/examples/two_messengers.py).
+
+## Кнопки
+
+Данные кнопки описываются классом, а не строкой, которую потом приходится резать вручную. В хендлер приходит уже готовый объект с нужными типами:
+
+```python
+@callback("order:set")
+class SetStatus(CallbackData):
+    order_id: int
+    status: Literal["paid", "shipped"]
+
+
+@dp.callback(SetStatus)
+async def set_status(ctx: Context, payload: SetStatus):
+    await ctx.edit(f"Заказ {payload.order_id}: {payload.status}")
+```
+
+Telegram ограничивает данные кнопки 64 байтами. Если payload длиннее, matele подменяет его коротким ключом, а при нажатии возвращает исходное значение. Нажатия на кнопки из старых версий бота, которые уже не разбираются, приходят в `@dp.raw_callback()`, и бот не падает.
+
+## Меню в одном сообщении
+
+`ctx.show()` рисует экран в одном и том же сообщении: при нажатии кнопки оно редактируется, а не появляется новое. Если человек что-то напечатал, его сообщение удаляется, а меню обновляется прямо под ним, так что чат не засоряется.
+
+```python
+@dp.command("menu")
+async def menu(ctx: Context):
+    await ctx.show("Главное меню", main_keyboard)
+
+
+@dp.callback(OpenOrders)
+async def orders(ctx: Context, payload: OpenOrders):
+    await ctx.show("Ваши заказы", orders_keyboard, toast="Загружено")
+```
+
+Уведомления, которые не являются экранами меню, лучше отправлять обычным `ctx.reply()`.
+
+## Фильтры и порядок хендлеров
+
+Фильтр это любая функция от контекста, обычная или async. Фильтры комбинируются через `&`, `|` и `~`:
+
+```python
+is_admin = as_filter(lambda ctx: ctx.user.id in ADMINS)
+
+@dp.command("ban", is_admin)
+async def ban(ctx: Context): ...
+```
+
+Встроенные фильтры: `Text`, `Regex`, `HasAttachment`, `OnPlatform`, `ChatType`.
+
+Если у команды есть описание, при запуске она попадёт в меню команд в обоих мессенджерах. Команды без описания работают, но в меню не видны:
+
+```python
+@dp.command("start", description="Начать заново")
+async def start(ctx: Context): ...
+```
+
+Хендлер выбирается в предсказуемом порядке: сначала команды, потом хендлеры текущего состояния, потом все остальные. Поэтому `/cancel` срабатывает посреди любого сценария, и не нужно следить, в каком порядке что зарегистрировано.
+
+## Состояния
+
+`ctx.state` хранит, на каком шаге сценария находится человек, и данные, которые он успел ввести. По умолчанию всё лежит в памяти и теряется при перезапуске. Чтобы переживало перезапуск, подключите хранилище:
+
+```python
+from matele.fsm import SQLiteStorage, RedisStorage
+
+dp = Dispatcher(storage=SQLiteStorage("bot.db"))
+# или, если процессов несколько:
+dp = Dispatcher(storage=RedisStorage.from_url("redis://localhost:6379/0"))
+```
+
+SQLite работает на стандартной библиотеке, ничего ставить не нужно.
+
+## Группы
+
+Бот работает и в личке, и в групповых чатах. `ctx.reply()` отвечает туда, откуда пришло сообщение, а `ctx.send_private()` пишет человеку в личку. Состояние хранится отдельно для каждого человека в каждом чате, так что форма, начатая в одной группе, не мешает в другой.
+
+```python
+@dp.member_update()
+async def welcome(ctx: Context):
+    update = ctx.member_update
+    if update.joined and not update.is_me:
+        await ctx.reply(f"Добро пожаловать, {escape(update.member.name)}!")
+```
+
+Команды вроде `/help@other_bot` бот пропускает: они адресованы не ему.
+
+Чтобы бот видел в группе все сообщения, а не только команды: в Telegram выключите privacy mode у бота в BotFather, в MAX сделайте бота администратором с правом читать все сообщения.
+
+## Файлы и ответы
+
+```python
+await ctx.reply_file(Path("cat.jpg"), kind="image", caption="Кот")
+await ctx.reply("Принято", quote=True)  # ответом на сообщение человека
+
+async with ctx.typing():  # «печатает…», пока идёт долгая работа
+    report = await build_report()
+```
+
+Файл можно передать байтами, путём или открытым файлом. Большие файлы уходят потоком, целиком в память не читаются.
+
+## Мини-приложения
+
+Кнопка с `app=` открывает мини-приложение бота. Значение кнопки приложение получает как параметр запуска, по нему удобно сразу открыть нужную страницу:
+
+```python
+keyboard = Keyboard([[Button("Открыть магазин", app=""), Button("Сразу к кофе", app="coffee")]])
+```
+
+В MAX адрес мини-приложения задаётся в настройках бота на business.max.ru. В Telegram его передают в `TelegramBot(token, app_url="https://...")`, и там такие кнопки работают только в личных чатах.
+
+Мини-приложение присылает на ваш сервер `initData`, подписанные мессенджером данные о человеке. Перед тем как чему-то верить, подпись нужно проверить:
+
+```python
+data = bot.verify_init_data(request.headers["X-Init-Data"])  # иначе InitDataError
+await bot.send_message("Заказ принят", user_id=data.user.id)
+```
+
+Проверка одна на оба мессенджера: подпись и срок (по умолчанию час, как советует MAX). Готовый пример со страницей и сервером на FastAPI лежит в [examples/mini_app](https://github.com/cvsqwe/matele/tree/main/examples/mini_app).
+
+## Рассылки
+
+Если человек есть в обоих мессенджерах, `Hub` напишет ему в каждый. Отказ одного мессенджера не мешает второму:
+
+```python
+from matele.hub import Hub
+
+hub = Hub(max_bot, telegram_bot)
+await hub.send({"max": 123, "telegram": 456}, "Заказ готов")
+
+report = await hub.broadcast(subscribers(), "Мы открылись!")
+print(report.reached, report.unreachable)
+```
+
+Скорость отправки ограничена под лимиты мессенджеров (по умолчанию 25 сообщений в секунду на каждый). Если мессенджер ненадолго пропал, отправка подождёт и повторит, а при долгом сбое сразу вернёт ошибку и не застопорит рассылку. Тех, кто заблокировал бота, видно в `report.unreachable`, а `on_unreachable` позволяет сразу отметить их у себя. Получателей можно отдавать генератором, например постранично из базы.
+
+## Вебхуки
+
+Вместо постоянного опроса мессенджеры могут сами присылать события на ваш сервер:
+
+```python
+from matele.webhook import Webhook
+
+webhook = Webhook(dp, base_url="https://bot.example.com")
+webhook.add(MaxBot(MAX_TOKEN), "/max")
+webhook.add(TelegramBot(TG_TOKEN), "/telegram")
+webhook.run(port=8080)
+```
+
+`Webhook` это обычное ASGI-приложение, его можно запустить и через `uvicorn app:webhook`. При старте он сам регистрирует адреса в мессенджерах со случайным секретом и проверяет этот секрет в каждом запросе. Нужен публичный HTTPS-адрес: MAX принимает только порт 443, Telegram ещё 80, 88 и 8443.
+
+## Весь MAX Bot API
+
+Помимо общего слоя есть типизированный клиент ко всем 33 методам MAX Bot API: чаты, участники, закрепы, загрузка файлов, вебхуки, комментарии.
+
+```python
+from matele.max import MaxApi
+
+async with MaxApi(token) as api:
+    photo = await api.upload(Path("cat.jpg"), type="image")
+    sent = await api.send_message(chat_id=chat_id, text="<b>Кот</b>", format="html", attachments=[photo])
+    await api.pin_message(chat_id, sent.body.mid)
+```
+
+Модели генерируются из [официальной схемы](https://github.com/max-messenger/api-schema), поэтому совпадают с документацией MAX. Если MAX добавит новое поле или новый тип события, бот не упадёт: неизвестное просто приходит как базовый объект с исходными данными в `.raw`. Сертификат Минцифры, которым подписан MAX API, уже встроен и используется только для запросов к MAX.
+
+Из хендлера клиент доступен как `ctx.bot.api`. Для Telegram есть `TelegramApi.call()`, через него можно вызвать любой метод Bot API.
+
+## Тесты
+
+Ботов можно тестировать без сети и токенов:
+
+```python
+from matele.testing import FakeBot
+
+bot = FakeBot()
+await dp.feed(bot.message("/start"))
+assert bot.sent[-1].text == "Привет! На каком языке говорим?"
+```
+
+## Что дальше
+
+Ближайшее: проверка на живых ботах в обоих мессенджерах. Подробнее в [ROADMAP.md](https://github.com/cvsqwe/matele/blob/main/ROADMAP.md).
+
+## Разработка
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest
+.venv/bin/ruff check src tests tools examples
+.venv/bin/basedpyright
+```
+
+Документация лежит в `docs/` и собирается MkDocs:
+
+```bash
+.venv/bin/python -m pip install -e ".[docs]"
+.venv/bin/mkdocs serve
+```
+
+В коде отступы табами, настройки в `.editorconfig`.
+
+## Лицензия
+
+MIT