pybotx 0.77.0__tar.gz → 0.77.2__tar.gz

pybotx-0.77.2/.gitlab-ci.yml

@@ -0,0 +1,56 @@
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
+      when: never
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH'
+
+stages:
+  - check
+  - package
+
+variables:
+  PYTHON_VERSION: "3.13"
+
+default:
+  image: "python:${PYTHON_VERSION}-bookworm"
+  tags:
+    - docker
+  before_script:
+    - python -m pip install uv
+    - uv sync --locked --dev
+
+test:
+  stage: check
+  parallel:
+    matrix:
+      - PYTHON_VERSION: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+  script:
+    - >-
+      uv run --no-sync ./scripts/test -n 4 --cov-report=xml
+      --junitxml=junit.xml --junit-prefix="py${PYTHON_VERSION}"
+  coverage: '/^TOTAL\s+.*\s+([0-9]+(?:\.[0-9]+)?%)\s*$/'
+  artifacts:
+    reports:
+      junit: junit.xml
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+
+lint:
+  stage: check
+  script:
+    - uv run --no-sync ./scripts/lint
+
+docs-lint:
+  stage: check
+  script:
+    - uv run --no-sync bash ./scripts/docs-lint
+
+package:
+  stage: package
+  script:
+    - uv build
+  artifacts:
+    paths:
+      - dist/

pybotx-0.77.0/README.md → pybotx-0.77.2/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.5
+Name: pybotx
+Version: 0.77.2
+Summary: A python library for interacting with eXpress BotX API
+Project-URL: Repository, https://github.com/ExpressApp/pybotx
+Author: Sidnev Nikolay, Maxim Gorbachev, Alexander Samoylenko, Arseniy Zhiltsov, Aleksandr Osovskii
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: aiocsv<2,>=1.4.0
+Requires-Dist: aiofiles<26,>=25.1.0
+Requires-Dist: httpcore<2,>=1.0.9
+Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: loguru<0.8,>=0.7.3
+Requires-Dist: mypy-extensions<2,>=1.1.0
+Requires-Dist: pydantic<3,>=2.12.5
+Requires-Dist: pyjwt<3,>=2.11.0
+Requires-Dist: tenacity<10,>=9.1.2
+Description-Content-Type: text/markdown
+
 # pybotx
 
 *Библиотека для создания чат-ботов и SmartApps для мессенджера eXpress*
@@ -122,20 +141,6 @@ uv run pybotx create widget-flow deployment-approval --project-dir my-bot --kind
 - `src/<package>/domain/` - доменные модели и контракты, включая `domain/ports/`
 - `src/<package>/infrastructure/` - config, repository/adapters, внешние интеграции
 
-**Предупреждение:** Данный проект находится в активной разработке (`0.y.z`) и
-его API может быть изменён при повышении минорной версии.
-
-## Документация по виджетам
-
-Подробное и исчерпывающее руководство по всем виджетам и API раннера:
-
-- `/Users/aleksandrosovskii/PycharmProjects/pybotx_stable/WIDGETS.md`
-
-Демо-бот с примерами всех виджетов:
-
-- `/Users/aleksandrosovskii/PycharmProjects/pybotx_stable/example/README.md`
-
-
 ## Информация о мессенджере eXpress и платформе BotX
 
 Документацию по мессенджеру (включая руководство пользователя и администратора)
@@ -217,6 +222,44 @@ app: FastAPI = create_fastapi_bot_app(
 - опционально `GET /metrics`
 - healthcheck routes через `setup_healthcheck(...)`
 
+### Динамические account-ы и несколько CTS
+
+Если credentials появляются во время работы процесса, передайте
+`account_provider` вместо `bot_accounts`. Provider является синхронным
+read-side контрактом: он не должен выполнять сетевой или database I/O в
+обработчике команды. Для динамического хранилища используйте локальный
+snapshot, обновляемый приложением после регистрации или через invalidation.
+
+```python
+from uuid import UUID
+
+from pybotx import Bot, BotAccountKey, BotAccountProvider, HandlerCollector
+
+collector = HandlerCollector()
+
+
+def create_bot(registration_account_provider: BotAccountProvider) -> Bot:
+    return Bot(
+        collectors=[collector],
+        account_provider=registration_account_provider,
+    )
+
+# В background-задаче CTS выбирается явно.
+async def send_registration_confirmation(
+    bot: Bot, *, bot_id: UUID, chat_id: UUID
+) -> None:
+    with bot.account_scope(BotAccountKey(server_id="cts-001", bot_id=bot_id)):
+        await bot.send_message(bot_id=bot_id, chat_id=chat_id, body="Готово")
+```
+
+Входящие команды связываются с `BotAccountKey` provider-ом до вызова handler;
+JWT v1 cache изолирован ключом account-а и его `revision`. Если вызов производится
+вне handler и один `bot_id` зарегистрирован на нескольких CTS, provider обязан
+поднять `AmbiguousBotAccountError`, а не выбрать произвольный credential.
+
+Полный контракт и требования к adapter-у описаны в
+[`docs/dynamic_accounts.md`](docs/dynamic_accounts.md).
+
 Если у вас уже есть свой `FastAPI()` объект, можно не создавать новый app, а
 подключить `pybotx` в существующий:
 

pybotx-0.77.0/PKG-INFO → pybotx-0.77.2/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.5
-Name: pybotx
-Version: 0.77.0
-Summary: A python library for interacting with eXpress BotX API
-Project-URL: Repository, https://github.com/ExpressApp/pybotx
-Author-email: Sidnev Nikolay <nsidnev@ccsteam.ru>, Maxim Gorbachev <mgorbachev@ccsteam.ru>, Alexander Samoylenko <alexandr.samojlenko@ccsteam.ru>, Arseniy Zhiltsov <arseniy.zhiltsov@ccsteam.ru>
-License-File: LICENSE
-Requires-Python: <4.0,>=3.10
-Requires-Dist: aiocsv<2,>=1.4.0
-Requires-Dist: aiofiles<26,>=25.1.0
-Requires-Dist: httpcore<2,>=1.0.9
-Requires-Dist: httpx<0.29,>=0.28.1
-Requires-Dist: loguru<0.8,>=0.7.3
-Requires-Dist: mypy-extensions<2,>=1.1.0
-Requires-Dist: pydantic<3,>=2.12.5
-Requires-Dist: pyjwt<3,>=2.11.0
-Requires-Dist: tenacity<10,>=9.1.2
-Description-Content-Type: text/markdown
-
 # pybotx
 
 *Библиотека для создания чат-ботов и SmartApps для мессенджера eXpress*
@@ -141,20 +122,6 @@ uv run pybotx create widget-flow deployment-approval --project-dir my-bot --kind
 - `src/<package>/domain/` - доменные модели и контракты, включая `domain/ports/`
 - `src/<package>/infrastructure/` - config, repository/adapters, внешние интеграции
 
-**Предупреждение:** Данный проект находится в активной разработке (`0.y.z`) и
-его API может быть изменён при повышении минорной версии.
-
-## Документация по виджетам
-
-Подробное и исчерпывающее руководство по всем виджетам и API раннера:
-
-- `/Users/aleksandrosovskii/PycharmProjects/pybotx_stable/WIDGETS.md`
-
-Демо-бот с примерами всех виджетов:
-
-- `/Users/aleksandrosovskii/PycharmProjects/pybotx_stable/example/README.md`
-
-
 ## Информация о мессенджере eXpress и платформе BotX
 
 Документацию по мессенджеру (включая руководство пользователя и администратора)
@@ -236,6 +203,44 @@ app: FastAPI = create_fastapi_bot_app(
 - опционально `GET /metrics`
 - healthcheck routes через `setup_healthcheck(...)`
 
+### Динамические account-ы и несколько CTS
+
+Если credentials появляются во время работы процесса, передайте
+`account_provider` вместо `bot_accounts`. Provider является синхронным
+read-side контрактом: он не должен выполнять сетевой или database I/O в
+обработчике команды. Для динамического хранилища используйте локальный
+snapshot, обновляемый приложением после регистрации или через invalidation.
+
+```python
+from uuid import UUID
+
+from pybotx import Bot, BotAccountKey, BotAccountProvider, HandlerCollector
+
+collector = HandlerCollector()
+
+
+def create_bot(registration_account_provider: BotAccountProvider) -> Bot:
+    return Bot(
+        collectors=[collector],
+        account_provider=registration_account_provider,
+    )
+
+# В background-задаче CTS выбирается явно.
+async def send_registration_confirmation(
+    bot: Bot, *, bot_id: UUID, chat_id: UUID
+) -> None:
+    with bot.account_scope(BotAccountKey(server_id="cts-001", bot_id=bot_id)):
+        await bot.send_message(bot_id=bot_id, chat_id=chat_id, body="Готово")
+```
+
+Входящие команды связываются с `BotAccountKey` provider-ом до вызова handler;
+JWT v1 cache изолирован ключом account-а и его `revision`. Если вызов производится
+вне handler и один `bot_id` зарегистрирован на нескольких CTS, provider обязан
+поднять `AmbiguousBotAccountError`, а не выбрать произвольный credential.
+
+Полный контракт и требования к adapter-у описаны в
+[`docs/dynamic_accounts.md`](docs/dynamic_accounts.md).
+
 Если у вас уже есть свой `FastAPI()` объект, можно не создавать новый app, а
 подключить `pybotx` в существующий:
 

{pybotx-0.77.0 → pybotx-0.77.2}/pybotx/__init__.py

@@ -15,6 +15,10 @@ from pybotx.bot.api.responses.unverified_request import (
 )
 from pybotx.auth import BotXAuthVersion
 from pybotx.bot.bot import Bot
+from pybotx.bot.bot_account_provider import (
+    BotAccountProvider,
+    StaticBotAccountProvider,
+)
 from pybotx.bot.command_processing import (
     BotCommandOverloadAction,
     BotCommandOverloadStrategy,
@@ -152,7 +156,11 @@ from pybotx.models.attachments import (
     AttachmentVoice,
     OutgoingAttachment,
 )
-from pybotx.models.bot_account import BotAccount, BotAccountWithSecret
+from pybotx.models.bot_account import (
+    BotAccount,
+    BotAccountKey,
+    BotAccountWithSecret,
+)
 from pybotx.models.bot_catalog import BotsListItem
 from pybotx.models.bot_sender import BotSender
 from pybotx.models.chats import (
@@ -242,6 +250,8 @@ __all__ = (
     "AttachmentVideo",
     "AttachmentVoice",
     "Bot",
+    "BotAccountKey",
+    "BotAccountProvider",
     "BotAPIBotDisabledErrorData",
     "BotAPIBotDisabledResponse",
     "BotAPIMethodFailedCallback",
@@ -385,6 +395,7 @@ __all__ = (
     "SmartappManifestWebLayoutChoices",
     "SmartappManifestWebParams",
     "StatusRecipient",
+    "StaticBotAccountProvider",
     "StealthModeDisabledError",
     "Sticker",
     "StickerPack",