ubits-bot 0.1.0b2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ubits contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,4 @@
1
+ include LICENSE README.md
2
+ recursive-include docs *.md *.json
3
+ recursive-include examples *.py *.md *.txt
4
+ recursive-include tests *.py
@@ -0,0 +1,76 @@
1
+ Metadata-Version: 2.4
2
+ Name: ubits-bot
3
+ Version: 0.1.0b2
4
+ Summary: Async Python client for the Ubits Bot API beta
5
+ License-Expression: MIT
6
+ Project-URL: Documentation, https://ubits.org/assets/bots/bot-api-v1-beta-2.md
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: httpx<1,>=0.27
11
+ Dynamic: license-file
12
+
13
+ # ubits-bot
14
+
15
+ Асинхронная Python-библиотека для Ubits Bot API. Python 3.10+.
16
+
17
+ **Bot API пока не включён на ubits.org.** SDK и пример готовы; запросы начнут
18
+ работать после активации API на сервере.
19
+
20
+ ## Установка
21
+
22
+ ```sh
23
+ python -m pip install --pre ubits-bot
24
+ ```
25
+
26
+ Для установки бета-версии нужен флаг `--pre`.
27
+
28
+ ## Пример
29
+
30
+ Создайте бота через @CreateBot: `/newbot`. Сохраните выданный токен в переменную
31
+ окружения `UBITS_BOT_TOKEN`.
32
+
33
+ ```python
34
+ import asyncio
35
+ import os
36
+ from ubits_bot import Bot
37
+
38
+ async def main():
39
+ async with Bot(os.environ["UBITS_BOT_TOKEN"]) as bot:
40
+ async def handle(update):
41
+ message = update.get("message")
42
+ if update["type"] == "message" and message and message["kind"] == "text":
43
+ await bot.send_message(message["chatId"], "Привет!")
44
+ await bot.run_polling(handle)
45
+
46
+ asyncio.run(main())
47
+ ```
48
+
49
+ Программа должна оставаться запущенной. Один процесс polling на токен.
50
+ Пользователь сначала сам открывает диалог с ботом в Ubits.
51
+
52
+ ## Методы
53
+
54
+ - `get_me`, `get_user`, `get_chat`, `get_message`
55
+ - `send_message`, `edit_message`, `delete_message`
56
+ - `send_media`, `edit_media`
57
+ - `download_file`, `download_user_photo`
58
+ - `get_updates`, `run_polling`
59
+
60
+ [Документация API](docs/API.md) · [OpenAPI](docs/openapi.json) ·
61
+ [Игровой бот](examples/game_bot/README.md)
62
+
63
+ run_polling сохраняет offset после обработки всей пачки событий.
64
+ Повторная обработка события возможна: учитывайте updateId в своём коде.
65
+ SDK автоматически повторяет чтение при транспортных ошибках, 429 и 5xx.
66
+ Отправка и загрузка файлов автоматически не повторяются. Для повторной отправки
67
+ текста используйте заранее сохранённый message_id.
68
+
69
+ ## Разработка
70
+
71
+ ```sh
72
+ python -m pip install -e .
73
+ python -m unittest discover -s tests -v
74
+ ```
75
+
76
+ Лицензия MIT.
@@ -0,0 +1,64 @@
1
+ # ubits-bot
2
+
3
+ Асинхронная Python-библиотека для Ubits Bot API. Python 3.10+.
4
+
5
+ **Bot API пока не включён на ubits.org.** SDK и пример готовы; запросы начнут
6
+ работать после активации API на сервере.
7
+
8
+ ## Установка
9
+
10
+ ```sh
11
+ python -m pip install --pre ubits-bot
12
+ ```
13
+
14
+ Для установки бета-версии нужен флаг `--pre`.
15
+
16
+ ## Пример
17
+
18
+ Создайте бота через @CreateBot: `/newbot`. Сохраните выданный токен в переменную
19
+ окружения `UBITS_BOT_TOKEN`.
20
+
21
+ ```python
22
+ import asyncio
23
+ import os
24
+ from ubits_bot import Bot
25
+
26
+ async def main():
27
+ async with Bot(os.environ["UBITS_BOT_TOKEN"]) as bot:
28
+ async def handle(update):
29
+ message = update.get("message")
30
+ if update["type"] == "message" and message and message["kind"] == "text":
31
+ await bot.send_message(message["chatId"], "Привет!")
32
+ await bot.run_polling(handle)
33
+
34
+ asyncio.run(main())
35
+ ```
36
+
37
+ Программа должна оставаться запущенной. Один процесс polling на токен.
38
+ Пользователь сначала сам открывает диалог с ботом в Ubits.
39
+
40
+ ## Методы
41
+
42
+ - `get_me`, `get_user`, `get_chat`, `get_message`
43
+ - `send_message`, `edit_message`, `delete_message`
44
+ - `send_media`, `edit_media`
45
+ - `download_file`, `download_user_photo`
46
+ - `get_updates`, `run_polling`
47
+
48
+ [Документация API](docs/API.md) · [OpenAPI](docs/openapi.json) ·
49
+ [Игровой бот](examples/game_bot/README.md)
50
+
51
+ run_polling сохраняет offset после обработки всей пачки событий.
52
+ Повторная обработка события возможна: учитывайте updateId в своём коде.
53
+ SDK автоматически повторяет чтение при транспортных ошибках, 429 и 5xx.
54
+ Отправка и загрузка файлов автоматически не повторяются. Для повторной отправки
55
+ текста используйте заранее сохранённый message_id.
56
+
57
+ ## Разработка
58
+
59
+ ```sh
60
+ python -m pip install -e .
61
+ python -m unittest discover -s tests -v
62
+ ```
63
+
64
+ Лицензия MIT.
@@ -0,0 +1,111 @@
1
+ # Bot API v1
2
+
3
+ Статус: серверная активация ожидается.
4
+ Базовый адрес: `https://ubits.org/bot/v1`.
5
+
6
+ Токен создаётся через @CreateBot → `/newbot`.
7
+ Передавайте его в заголовке `Authorization: Bot <token>`. В URL токен не нужен.
8
+ Удаление бота через `/deletebot` отзывает токен.
9
+
10
+ ## Запросы и ответы
11
+
12
+ Для JSON-методов: POST, `Content-Type: application/json`.
13
+
14
+ ```json
15
+ {"ok": true, "result": {}}
16
+ ```
17
+
18
+ Ошибки имеют HTTP-статус и тело:
19
+
20
+ ```json
21
+ {"ok": false, "error": {"code": 403, "message": "Only own messages can be changed"}}
22
+ ```
23
+
24
+ 400 — параметры, 401 — авторизация, 403 — права, 404 — объект недоступен,
25
+ 409 — конфликт ID или одновременный polling, 413 — размер, 429 — лимит.
26
+ При 5xx повторите чтение с задержкой. Прокси может вернуть другой формат ошибки.
27
+
28
+ ID пользователя, чата и сообщения — строки UUID. numericId — отдельный публичный
29
+ цифровой идентификатор, он не заменяет UUID в запросах. updateId и offset —
30
+ десятичные строки; не преобразуйте их в JavaScript Number.
31
+
32
+ ## Методы
33
+
34
+ | Метод | Параметры | Результат |
35
+ |---|---|---|
36
+ | POST getMe | `{}` | Профиль бота |
37
+ | POST getUser | userId | Профиль участника общего чата |
38
+ | POST getChat | chatId | id, type, title |
39
+ | POST getMessage | chatId, messageId | Сообщение |
40
+ | POST sendMessage | chatId, content; необязательно messageId, replyToId | Сообщение |
41
+ | POST editMessage | chatId, messageId, content | Сообщение |
42
+ | POST deleteMessage | chatId, messageId | true |
43
+ | POST sendMedia | multipart file; query chatId, caption?, kind? | Сообщение |
44
+ | POST editMedia | multipart file; query chatId, messageId, caption?, kind? | Сообщение |
45
+ | POST getUpdates | offset?, limit?, timeout? | updates, nextOffset |
46
+ | GET getFile | query chatId, messageId, index? | Файл |
47
+ | GET getUserPhoto | query userId | Фото профиля |
48
+
49
+ content: 1–4096 символов после trim. Файл: до 25 MiB, один на запрос.
50
+ kind: voice, sticker, gif; для остальных типов сервер определяет формат файла.
51
+ caption: до 4096 символов; если не указана, используется имя файла.
52
+ editMedia сохраняет ID сообщения. Альбом можно заменить одним файлом.
53
+ getFile принимает index 0–4 для файла из альбома.
54
+
55
+ Бот работает в чатах, где он участник. Публикация в канале требует права
56
+ публикации. Изменять и удалять можно только собственные сообщения.
57
+ API не позволяет боту начать диалог с произвольным пользователем.
58
+ Для повторной отправки текста передавайте прежний messageId и те же данные.
59
+ Медиа-загрузки не идемпотентны: не повторяйте их автоматически при потере ответа.
60
+
61
+ ## Данные
62
+
63
+ Профиль: id, numericId, displayName, username, bio, avatarUrl, isBot.
64
+ Скрытые поля остаются null согласно приватности пользователя.
65
+ Почта, телефон, IP, сессии, токены и настройки не выдаются.
66
+ avatarUrl указывает на getUserPhoto; запрос требует тот же Bot-заголовок.
67
+
68
+ Сообщение: id, chatId, sender, senderChat, content, kind, createdAt, editedAt,
69
+ replyToId, postId, fileName, mimeType, fileSize, durationSeconds, files, hasFile.
70
+ Время — ISO 8601, размер — байты, длительность — секунды.
71
+ У поста канала sender=null, senderChat содержит id и title канала.
72
+ Аккаунт администратора канала не раскрывается.
73
+
74
+ Для скачивания сервер может вернуть подписанную HTTPS-ссылку на CDN.
75
+ При переходе не пересылайте Authorization/cookie. SDK делает это сам.
76
+
77
+ ## Polling
78
+
79
+ getUpdates: offset="0", limit=50 (1–100), timeout=25 секунд (0–25).
80
+ Одновременно разрешён один запрос на бота.
81
+
82
+ ```json
83
+ {"ok":true,"result":{"updates":[{"updateId":"123","type":"message","chatId":"UUID","messageId":"UUID","message":{}}],"nextOffset":"124"}}
84
+ ```
85
+
86
+ События: message, message_edited, message_deleted. У удаления message=null.
87
+ Собственные исходящие сообщения боту не возвращаются. События хранятся 7 дней.
88
+ Текст выдаётся в текущем состоянии: это не архив промежуточных редакций.
89
+ Удалённое или скрытое содержимое не выдаётся. Если доступ к чату потерян,
90
+ его события пропускаются, nextOffset продолжает двигаться.
91
+
92
+ После успешной обработки всей пачки сохраните nextOffset. Повторный запрос
93
+ прежнего offset может вернуть те же события. Обработчик должен учитывать updateId,
94
+ если повторное выполнение действия недопустимо.
95
+
96
+ Лимит: 90 запросов в минуту на бота на процесс, плюс общие IP-лимиты сервера и
97
+ лимиты отправки сообщений/медиа. Для пустого polling используйте timeout=25.
98
+ При 429/5xx увеличивайте задержку. Webhook в этой версии нет.
99
+
100
+ ## Python
101
+
102
+ ```python
103
+ await bot.send_message(chat_id, "Привет!", message_id=saved_uuid)
104
+ await bot.edit_message(chat_id, message_id, "Новый текст")
105
+ await bot.delete_message(chat_id, message_id)
106
+ await bot.send_media(chat_id, "photo.jpg", caption="Фото")
107
+ await bot.edit_media(chat_id, message_id, "new_photo.jpg")
108
+ await bot.download_file(chat_id, message_id, "download.jpg")
109
+ ```
110
+
111
+ [Полная схема запросов](openapi.json).