yuchatlib 0.1.0__tar.gz

yuchatlib-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.env
+.pypirc

yuchatlib-0.1.0/LICENSE

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

yuchatlib-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: yuchatlib
+Version: 0.1.0
+Summary: Библиотека для Public API YuChat
+Project-URL: Documentation, https://docs.yuchat.ru/api-docs/category/api-documentation
+Project-URL: Source, https://github.com/codegenIrlX/yuchatlib
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiohttp==3.14.3
+Requires-Dist: pydantic==2.13.4
+Provides-Extra: dev
+Requires-Dist: mypy==1.20.2; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.16.3; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build==1.5.0; extra == 'release'
+Requires-Dist: twine==7.0.0; extra == 'release'
+Description-Content-Type: text/markdown
+
+# yuchatlib
+
+Асинхронная Python-библиотека для создания ботов YuChat.
+
+Поддерживает long polling, команды, декораторы обработчиков, FSM, отправку и
+редактирование сообщений. Данные API валидируются через Pydantic.
+
+## Установка
+
+```powershell
+pip install yuchatlib==0.1.0
+```
+
+Требуется Python 3.12 или новее.
+
+## Быстрый старт
+
+```python
+import asyncio
+
+from yuchatlib import HandlerContext, UpdateListItemResponseDto, YuChatBot
+
+bot = YuChatBot(
+    token="your-token",
+    workspace_id="your-workspace-id",
+    base_url="https://your-yuchat-api.example",
+    polling_interval=2,
+    storage=None,
+)
+
+
+@bot.command(name="start", description="Начать работу")
+async def start_command(
+    update: UpdateListItemResponseDto,
+    context: HandlerContext,
+) -> None:
+    del update
+    await context.answer("👋 Привет!")
+
+
+if __name__ == "__main__":
+    asyncio.run(bot.run_polling())
+```
+
+## Отправка в указанный чат
+
+```python
+await bot.send_message(
+    chat_id="target-chat-id",
+    text="Сообщение в выбранный чат",
+)
+```
+
+## Возможности
+
+- long polling через `getUpdates`;
+- команды вида `/start`;
+- FSM и state-handler;
+- отправка и редактирование сообщений;
+- явная отправка по `chat_id`;
+- асинхронная обработка разных чатов;
+- Pydantic-валидация API.
+
+При `storage=None` FSM и polling offset хранятся в памяти процесса и
+сбрасываются после перезапуска.
+
+[Документация Public API YuChat](https://docs.yuchat.ru/api-docs/category/api-documentation)

yuchatlib-0.1.0/README.md

@@ -0,0 +1,67 @@
+# yuchatlib
+
+Асинхронная Python-библиотека для создания ботов YuChat.
+
+Поддерживает long polling, команды, декораторы обработчиков, FSM, отправку и
+редактирование сообщений. Данные API валидируются через Pydantic.
+
+## Установка
+
+```powershell
+pip install yuchatlib==0.1.0
+```
+
+Требуется Python 3.12 или новее.
+
+## Быстрый старт
+
+```python
+import asyncio
+
+from yuchatlib import HandlerContext, UpdateListItemResponseDto, YuChatBot
+
+bot = YuChatBot(
+    token="your-token",
+    workspace_id="your-workspace-id",
+    base_url="https://your-yuchat-api.example",
+    polling_interval=2,
+    storage=None,
+)
+
+
+@bot.command(name="start", description="Начать работу")
+async def start_command(
+    update: UpdateListItemResponseDto,
+    context: HandlerContext,
+) -> None:
+    del update
+    await context.answer("👋 Привет!")
+
+
+if __name__ == "__main__":
+    asyncio.run(bot.run_polling())
+```
+
+## Отправка в указанный чат
+
+```python
+await bot.send_message(
+    chat_id="target-chat-id",
+    text="Сообщение в выбранный чат",
+)
+```
+
+## Возможности
+
+- long polling через `getUpdates`;
+- команды вида `/start`;
+- FSM и state-handler;
+- отправка и редактирование сообщений;
+- явная отправка по `chat_id`;
+- асинхронная обработка разных чатов;
+- Pydantic-валидация API.
+
+При `storage=None` FSM и polling offset хранятся в памяти процесса и
+сбрасываются после перезапуска.
+
+[Документация Public API YuChat](https://docs.yuchat.ru/api-docs/category/api-documentation)

yuchatlib-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yuchatlib"
+version = "0.1.0"
+description = "Библиотека для Public API YuChat"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "aiohttp==3.14.3",
+    "pydantic==2.13.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy==1.20.2",
+    "pytest==9.1.1",
+    "ruff==0.16.3",
+]
+release = [
+    "build==1.5.0",
+    "twine==7.0.0",
+]
+
+[project.urls]
+Documentation = "https://docs.yuchat.ru/api-docs/category/api-documentation"
+Source = "https://github.com/codegenIrlX/yuchatlib"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yuchatlib"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "SIM", "UP"]
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

yuchatlib-0.1.0/src/yuchatlib/__init__.py

@@ -0,0 +1,109 @@
+from yuchatlib.api.errors import (
+    YuChatAuthorizationError,
+    YuChatClientError,
+    YuChatRateLimitError,
+    YuChatTransientError,
+    YuChatUnexpectedResponseError,
+)
+from yuchatlib.api.models import (
+    ButtonBarRequestDto,
+    ButtonGroupRequestDto,
+    ButtonRequestDto,
+    CommandButtonRequestDto,
+    GetMeResponseDto,
+    GetUpdatesResponseDto,
+    LinkButtonRequestDto,
+    MessageActionResponseDto,
+    MessageType,
+    MessageUpdateResponseDto,
+    PressedButtonCommandResponseDto,
+    SendMessageResponseDto,
+    UpdateListItemResponseDto,
+    UpdateSetting,
+)
+from yuchatlib.bot import Bot
+from yuchatlib.dispatch import (
+    Command,
+    CommandFilter,
+    Dispatcher,
+    HandlerContext,
+    HandlerContextError,
+    HandlerDecorator,
+    MessageActionFilter,
+    MessageFilter,
+    Router,
+    StateFilter,
+    UpdateFilter,
+    UpdateHandler,
+    parse_command,
+)
+from yuchatlib.facade import YuChatBot
+from yuchatlib.fsm import (
+    DEFAULT_MAX_FSM_RECORDS,
+    FSMContext,
+    FSMData,
+    FSMKey,
+    FSMStorage,
+    FSMStorageError,
+    MemoryFSMStorage,
+    State,
+    StatesGroup,
+)
+from yuchatlib.polling import (
+    MemoryOffsetStorage,
+    OffsetStorage,
+    PollingConfig,
+    PollingWorker,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_MAX_FSM_RECORDS",
+    "Bot",
+    "ButtonBarRequestDto",
+    "ButtonGroupRequestDto",
+    "ButtonRequestDto",
+    "Command",
+    "CommandButtonRequestDto",
+    "CommandFilter",
+    "Dispatcher",
+    "FSMContext",
+    "FSMData",
+    "FSMKey",
+    "FSMStorage",
+    "FSMStorageError",
+    "GetMeResponseDto",
+    "GetUpdatesResponseDto",
+    "HandlerContext",
+    "HandlerContextError",
+    "HandlerDecorator",
+    "LinkButtonRequestDto",
+    "MemoryFSMStorage",
+    "MemoryOffsetStorage",
+    "MessageActionFilter",
+    "MessageActionResponseDto",
+    "MessageFilter",
+    "MessageType",
+    "MessageUpdateResponseDto",
+    "OffsetStorage",
+    "PollingConfig",
+    "PollingWorker",
+    "PressedButtonCommandResponseDto",
+    "Router",
+    "SendMessageResponseDto",
+    "State",
+    "StateFilter",
+    "StatesGroup",
+    "UpdateFilter",
+    "UpdateHandler",
+    "UpdateListItemResponseDto",
+    "UpdateSetting",
+    "YuChatAuthorizationError",
+    "YuChatBot",
+    "YuChatClientError",
+    "YuChatRateLimitError",
+    "YuChatTransientError",
+    "YuChatUnexpectedResponseError",
+    "parse_command",
+]

yuchatlib-0.1.0/src/yuchatlib/api/__init__.py

@@ -0,0 +1 @@
+"""Модели и ошибки Public API YuChat."""

yuchatlib-0.1.0/src/yuchatlib/api/client.py

@@ -0,0 +1,172 @@
+"""Асинхронный клиент Public API YuChat."""
+
+import json
+from collections.abc import Mapping
+from types import TracebackType
+from typing import TypeVar
+
+import aiohttp
+from pydantic import BaseModel, ValidationError
+
+from yuchatlib.api.errors import (
+    YuChatAuthorizationError,
+    YuChatClientError,
+    YuChatRateLimitError,
+    YuChatTransientError,
+    YuChatUnexpectedResponseError,
+)
+from yuchatlib.api.models import (
+    EditMessageRequestDto,
+    GetMeResponseDto,
+    GetUpdatesRequestDto,
+    GetUpdatesResponseDto,
+    SendMessageRequestDto,
+    SendMessageResponseDto,
+    SetUpdateSettingsRequestDto,
+)
+
+ModelType = TypeVar("ModelType", bound=BaseModel)
+AUTHORIZATION_ERROR_STATUSES = frozenset({401, 403})
+RATE_LIMIT_STATUS = 429
+SERVER_ERROR_STATUS = 500
+
+
+class YuChatApiClient:
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        timeout_seconds: float,
+        connection_limit: int,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._timeout_seconds = timeout_seconds
+        self._connection_limit = connection_limit
+        self._session: aiohttp.ClientSession | None = None
+
+    async def __aenter__(self) -> "YuChatApiClient":
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def start(self) -> None:
+        if self._session is not None:
+            return
+        timeout = aiohttp.ClientTimeout(total=self._timeout_seconds)
+        connector = aiohttp.TCPConnector(limit=self._connection_limit)
+        self._session = aiohttp.ClientSession(
+            timeout=timeout,
+            connector=connector,
+            headers={
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self._token}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def close(self) -> None:
+        if self._session is None:
+            return
+        await self._session.close()
+        self._session = None
+
+    async def set_update_settings(self, request: SetUpdateSettingsRequestDto) -> None:
+        """Сохраняет на стороне YuChat настройки получаемых событий."""
+        await self._post("/public/v2/setUpdateSettings", request=request, parse_json=False)
+
+    async def get_me(self) -> GetMeResponseDto:
+        """Получает сведения о текущем боте."""
+        payload = await self._post("/public/v2/getMe")
+        return self._parse_response(payload, GetMeResponseDto)
+
+    async def get_updates(self, request: GetUpdatesRequestDto) -> GetUpdatesResponseDto:
+        """Получает следующую пачку событий после указанного offset."""
+        payload = await self._post("/public/v2/getUpdates", request=request)
+        return self._parse_response(payload, GetUpdatesResponseDto)
+
+    async def send_message(self, request: SendMessageRequestDto) -> SendMessageResponseDto:
+        """Отправляет сообщение в явно указанный чат."""
+        payload = await self._post("/public/v2/sendMessage", request=request)
+        return self._parse_response(payload, SendMessageResponseDto)
+
+    async def edit_message(self, request: EditMessageRequestDto) -> None:
+        """Заменяет текст и кнопки существующего сообщения."""
+        await self._post("/public/v2/editMessage", request=request, parse_json=False)
+
+    async def _post(
+        self,
+        path: str,
+        request: BaseModel | None = None,
+        *,
+        parse_json: bool = True,
+    ) -> object | None:
+        session = self._require_session()
+        url = f"{self._base_url}{path}"
+        payload = (
+            request.model_dump(mode="json", by_alias=True, exclude_none=True)
+            if request is not None
+            else None
+        )
+        try:
+            async with session.post(url, json=payload) as response:
+                self._raise_for_status(response.status, response.headers, path)
+                if not parse_json:
+                    return None
+                try:
+                    response_payload: object = await response.json(content_type=None)
+                    return response_payload
+                except (aiohttp.ContentTypeError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+                    raise YuChatUnexpectedResponseError("YuChat вернул некорректный JSON") from exc
+        except (TimeoutError, aiohttp.ClientConnectionError) as exc:
+            raise YuChatTransientError("YuChat временно недоступен") from exc
+        except aiohttp.ClientError as exc:
+            raise YuChatClientError("Ошибка выполнения запроса к YuChat") from exc
+
+    def _require_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            raise YuChatClientError("HTTP-клиент YuChat не запущен")
+        return self._session
+
+    @staticmethod
+    def _parse_response(payload: object | None, model_type: type[ModelType]) -> ModelType:
+        try:
+            return model_type.model_validate(payload)
+        except ValidationError as exc:
+            raise YuChatUnexpectedResponseError("Формат ответа YuChat не поддерживается") from exc
+
+    @staticmethod
+    def _raise_for_status(
+        status: int,
+        headers: Mapping[str, str],
+        path: str,
+    ) -> None:
+        if 200 <= status < 300:
+            return
+        if status in AUTHORIZATION_ERROR_STATUSES:
+            raise YuChatAuthorizationError("YuChat отклонил токен или права бота")
+        if status == RATE_LIMIT_STATUS:
+            retry_after = headers.get("Retry-After")
+            raise YuChatRateLimitError(YuChatApiClient._parse_retry_after(retry_after))
+        if status >= SERVER_ERROR_STATUS:
+            raise YuChatTransientError(f"YuChat временно недоступен: status={status}, path={path}")
+        raise YuChatUnexpectedResponseError(
+            f"YuChat вернул неожиданный статус: status={status}, path={path}"
+        )
+
+    @staticmethod
+    def _parse_retry_after(raw_value: str | None) -> float | None:
+        if raw_value is None:
+            return None
+        try:
+            return max(0.0, float(raw_value))
+        except ValueError:
+            return None

yuchatlib-0.1.0/src/yuchatlib/api/errors.py

@@ -0,0 +1,25 @@
+"""Исключения Public API YuChat."""
+
+
+class YuChatClientError(RuntimeError):
+    """Представляет базовую ошибку вызова YuChat без чувствительных данных."""
+
+
+class YuChatAuthorizationError(YuChatClientError):
+    """Сообщает об отклонении токена или недостаточных правах бота."""
+
+
+class YuChatTransientError(YuChatClientError):
+    """Сообщает о временной сетевой или серверной ошибке."""
+
+
+class YuChatUnexpectedResponseError(YuChatClientError):
+    """Сообщает о неподдерживаемом статусе или формате ответа YuChat."""
+
+
+class YuChatRateLimitError(YuChatClientError):
+    """Передаёт рекомендуемую задержку после ответа 429."""
+
+    def __init__(self, retry_after_seconds: float | None) -> None:
+        super().__init__("YuChat временно ограничил частоту запросов")
+        self.retry_after_seconds = retry_after_seconds