vkx 0.1.0__py3-none-any.whl

vkx/__init__.py

@@ -0,0 +1,125 @@
+"""vkx: клиент VK API (vkx.client), типы API/событий (vkx.models) и серверный блок (vkx.server)."""
+
+from .client import (
+    API_HOST,
+    API_VERSION,
+    AUTH_ERROR_CODES,
+    CAPTCHA_ERROR_CODE,
+    CATEGORY_SCOPES,
+    DEFAULT_GROUP_INTERVAL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_PAGINATION_LIMIT,
+    DEFAULT_RETRY_BACKOFF,
+    DEFAULT_USER_INTERVAL,
+    EXECUTE_BATCH_LIMIT,
+    EXECUTE_CODE_BYTES_LIMIT,
+    INVALID_TOKEN_CODE,
+    PAGINATION_LIMITS,
+    RATE_LIMIT_ERROR_CODES,
+    SCOPE_TITLES,
+    TRANSIENT_ERROR_CODES,
+    HttpClient,
+    HttpResponse,
+    JSONStore,
+    MemoryStore,
+    PendingApiCall,
+    SQLiteStore,
+    State,
+    StaticTokenSource,
+    Store,
+    TokenSource,
+    TokenSourceError,
+    VKAuthError,
+    VKCaptchaError,
+    VKClient,
+    VKError,
+    VKErrorCode,
+    VKFloodError,
+    VKInvalidTokenError,
+    VKPermissionError,
+    VKRateLimitError,
+    VKRequestError,
+    VKServerError,
+    VKTimeoutError,
+    VKTransportError,
+    WebCookieSource,
+    build_error,
+    default_store,
+    limit_for,
+    merge_pages,
+    method_scope,
+    open_store,
+    paginate,
+    scope_keys,
+    scope_titles,
+    validate_web_cookies,
+)
+from .server import (
+    BotsLongPoll,
+    CallbackListener,
+    CallbackServer,
+    LongPoll,
+    create_callback_server,
+    parse_callback,
+)
+
+__all__ = [
+    "API_HOST",
+    "API_VERSION",
+    "AUTH_ERROR_CODES",
+    "CAPTCHA_ERROR_CODE",
+    "CATEGORY_SCOPES",
+    "DEFAULT_GROUP_INTERVAL",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_PAGINATION_LIMIT",
+    "DEFAULT_RETRY_BACKOFF",
+    "DEFAULT_USER_INTERVAL",
+    "EXECUTE_BATCH_LIMIT",
+    "EXECUTE_CODE_BYTES_LIMIT",
+    "INVALID_TOKEN_CODE",
+    "PAGINATION_LIMITS",
+    "RATE_LIMIT_ERROR_CODES",
+    "SCOPE_TITLES",
+    "TRANSIENT_ERROR_CODES",
+    "BotsLongPoll",
+    "CallbackListener",
+    "CallbackServer",
+    "HttpClient",
+    "HttpResponse",
+    "JSONStore",
+    "LongPoll",
+    "MemoryStore",
+    "PendingApiCall",
+    "SQLiteStore",
+    "State",
+    "StaticTokenSource",
+    "Store",
+    "TokenSource",
+    "TokenSourceError",
+    "VKAuthError",
+    "VKCaptchaError",
+    "VKClient",
+    "VKError",
+    "VKErrorCode",
+    "VKFloodError",
+    "VKInvalidTokenError",
+    "VKPermissionError",
+    "VKRateLimitError",
+    "VKRequestError",
+    "VKServerError",
+    "VKTimeoutError",
+    "VKTransportError",
+    "WebCookieSource",
+    "build_error",
+    "create_callback_server",
+    "default_store",
+    "limit_for",
+    "merge_pages",
+    "method_scope",
+    "open_store",
+    "paginate",
+    "parse_callback",
+    "scope_keys",
+    "scope_titles",
+    "validate_web_cookies",
+]

vkx/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Веб-адаптеры Callback API для конкретных фреймворков.
+
+Ядро живёт в ``._common`` и не зависит от фреймворков. Каждый модуль
+(``fastapi``, ``starlette``, ``aiohttp``, ``sanic``, ``django``, ``flask``)
+подключает свой фреймворк лениво — при импорте самого модуля, поэтому в
+зависимостях vkx ничего лишнего не появляется: адаптер импортируют только те,
+у кого этот фреймворк уже установлен.
+
+Async-фреймворки используют ``CallbackDispatch`` (задача в текущем loop),
+синхронные — ``SyncCallbackDispatch`` (handler выполняется в том же потоке, что
+и обработка колбека, и обязан быть синхронным). Ни отдельный loop, ни пул
+потоков не нужны.
+"""
+
+from ._common import CallbackDispatch, EventHandler, SyncCallbackDispatch
+
+__all__ = ("CallbackDispatch", "EventHandler", "SyncCallbackDispatch")

vkx/adapters/_common.py

@@ -0,0 +1,173 @@
+"""Общая логика веб-адаптеров Callback API.
+
+VK ждёт от вебхука ответ: если он задерживается, событие приходит повторно, а
+при регулярных задержках сообщество может отключить сервер. Поэтому для
+async-фреймворков уведомление разбирается, ответ ``ok`` отдаётся сразу, а
+обработчик запускается фоновой задачей. Исключение — ``confirmation``: код
+подтверждения адреса нужно вернуть немедленно, откладывать его нельзя.
+
+Диспетчеры:
+
+- ``CallbackDispatch`` — для async-фреймворков (FastAPI, Starlette, aiohttp,
+  Sanic, Django ASGI): задача ставится в текущий loop.
+- ``SyncCallbackDispatch`` — для синхронных (Flask, Django WSGI): синхронный
+  обработчик вызывается прямо в текущем потоке, без пула потоков и loop.
+
+Адаптеры конкретных фреймворков (``vkx.adapters.fastapi``,
+``vkx.adapters.starlette``, ``vkx.adapters.aiohttp``, ``vkx.adapters.sanic``,
+``vkx.adapters.django``, ``vkx.adapters.flask``) — тонкие обёртки над ними.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from ..models.events.callback_events import CallbackEvent
+from ..models.events.enums import CallbackEventType
+from ..server.callback import RawCallback
+from ..server.callback_server import CallbackListener
+
+EventHandler = Callable[[CallbackEvent], Any | Awaitable[Any]]
+
+
+class _DispatchBase:
+    """Общее для диспетчеров: разбор уведомления и ответ VK."""
+
+    def __init__(
+        self,
+        listener: CallbackListener,
+        *,
+        handler: EventHandler | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self._listener = listener
+        self._handler = handler
+        self._logger = logger or logging.getLogger("vkx.adapters")
+
+    @property
+    def listener(self) -> CallbackListener:
+        return self._listener
+
+    @property
+    def handler(self) -> EventHandler | None:
+        return self._handler
+
+    def dispatch(self, raw: RawCallback) -> tuple[str, int]:
+        """Разобрать уведомление и решить, что ответить VK.
+
+        :return: пара ``(тело, статус)`` для HTTP-ответа.
+        """
+        event = self._listener.handle(raw)
+        if event is None:  # чужой group_id / плохой secret / дубликат
+            return "ok", 200
+        if event.type is CallbackEventType.CONFIRMATION:
+            return self._confirmation(event), 200
+        self.schedule(event)
+        return "ok", 200
+
+    def schedule(self, event: CallbackEvent) -> None:
+        """Выполнить обработчик события."""
+        raise NotImplementedError
+
+    def _confirmation(self, event: CallbackEvent) -> str:
+        server = self._listener.get(event.group_id) if event.group_id else None
+        code = server.confirmation_code if server else None
+        return code or ""
+
+
+class CallbackDispatch(_DispatchBase):
+    """Ответ ``ok`` сразу + обработка в фоне задачей текущего loop.
+
+    Для async-фреймворков (FastAPI, Starlette, aiohttp, Sanic, Django ASGI).
+    ``handler`` может быть как async, так и обычной функцией: синхронная уходит
+    в отдельный поток (``asyncio.to_thread``), чтобы не блокировать loop.
+
+    Задачи удерживаются внутри, чтобы их не собрал GC, и логируются при падении;
+    на остановке приложения дождитесь их через ``aclose``.
+    """
+
+    def __init__(
+        self,
+        listener: CallbackListener,
+        *,
+        handler: EventHandler | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        super().__init__(listener, handler=handler, logger=logger)
+        self._tasks: set[asyncio.Task[None]] = set()
+
+    def schedule(self, event: CallbackEvent) -> None:
+        if self._handler is None:
+            self._logger.debug("Событие %s отброшено: обработчик не задан", event.type)
+            return
+        task = asyncio.create_task(self._run(event))
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+
+    async def aclose(self, *, timeout: float | None = None) -> None:
+        """Дождаться завершения фоновых задач."""
+        tasks = set(self._tasks)
+        if tasks:
+            await asyncio.wait(tasks, timeout=timeout)
+
+    async def __aenter__(self) -> CallbackDispatch:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def _run(self, event: CallbackEvent) -> None:
+        handler = self._handler
+        if handler is None:
+            return
+        try:
+            if inspect.iscoroutinefunction(handler):
+                await handler(event)
+            else:
+                result = await asyncio.to_thread(handler, event)
+                if inspect.isawaitable(result):
+                    await result
+        except Exception:  # noqa: BLE001
+            self._logger.exception("Ошибка обработки события %s", event.type)
+
+
+class SyncCallbackDispatch(_DispatchBase):
+    """Синхронный диспетчер для Flask и Django WSGI.
+
+    Синхронный ``handler`` вызывается прямо в том же потоке, что и первичная
+    обработка колбека (WSGI-сервер обычно выделяет отдельный поток на запрос),
+    поэтому ни пул потоков, ни event loop не нужны. ``handler`` обязан быть
+    синхронным: async-функция вызовет ``TypeError`` — для неё нужен
+    ``CallbackDispatch``.
+    """
+
+    def __init__(
+        self,
+        listener: CallbackListener,
+        *,
+        handler: EventHandler | None = None,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        super().__init__(listener, handler=handler, logger=logger)
+        if handler is not None and inspect.iscoroutinefunction(handler):
+            raise TypeError(
+                "SyncCallbackDispatch требует синхронный handler; "
+                "для async-функции используйте CallbackDispatch"
+            )
+
+    def schedule(self, event: CallbackEvent) -> None:
+        handler = self._handler
+        if handler is None:
+            self._logger.debug("Событие %s отброшено: обработчик не задан", event.type)
+            return
+        try:
+            handler(event)
+        except Exception:  # noqa: BLE001
+            self._logger.exception("Ошибка обработки события %s", event.type)
+
+
+__all__ = ("CallbackDispatch", "EventHandler", "SyncCallbackDispatch")

vkx/adapters/aiohttp.py

@@ -0,0 +1,42 @@
+"""aiohttp-адаптер Callback API.
+
+aiohttp в зависимости vkx не тянется: модуль импортируют только те, у кого он
+уже есть.
+
+Пример:
+
+    from vkx.adapters.aiohttp import create_callback_router
+
+    dispatch = CallbackDispatch(listener, handler=handle_vk_event)
+    app = web.Application()
+    app.add_routes(create_callback_router(dispatch))
+"""
+
+from __future__ import annotations
+
+from aiohttp import web
+
+from ._common import CallbackDispatch
+
+__all__ = ("create_callback_router",)
+
+
+def create_callback_router(
+    dispatch: CallbackDispatch,
+    *,
+    path: str = "/vk/callback",
+    name: str = "vk_callback",
+) -> web.RouteTableDef:
+    """Собрать ``RouteTableDef`` с POST-роутом для уведомлений Callback API.
+
+    Роут сам отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает
+    обработчик из ``dispatch`` в фоне. Подключите через ``app.add_routes``.
+    """
+    routes = web.RouteTableDef()
+
+    @routes.post(path, name=name)
+    async def vk_callback(request: web.Request) -> web.Response:
+        body, status = dispatch.dispatch(await request.read())
+        return web.Response(text=body, status=status)
+
+    return routes

vkx/adapters/django.py

@@ -0,0 +1,48 @@
+"""Django-адаптер Callback API.
+
+Django в зависимости vkx не тянется: модуль импортируют только те, у кого он
+уже есть.
+
+Django WSGI синхронный, поэтому используйте ``SyncCallbackDispatch`` с обычным
+(не async) хендлером — он выполнится в том же потоке, что и обработка колбека:
+
+    from vkx.adapters import SyncCallbackDispatch
+    from vkx.adapters.django import create_callback_view
+
+    dispatch = SyncCallbackDispatch(listener, handler=handle_vk_event)
+
+    urlpatterns = [path("vk/callback", create_callback_view(dispatch))]
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import cast
+
+from django.http import HttpRequest, HttpResponse
+from django.views.decorators.csrf import csrf_exempt as csrf_exempt_decorator
+
+from ._common import CallbackDispatch
+
+__all__ = ("create_callback_view",)
+
+
+def create_callback_view(
+    dispatch: CallbackDispatch,
+    *,
+    csrf_exempt: bool = True,
+) -> Callable[[HttpRequest], HttpResponse]:
+    """Вернуть Django-view для уведомлений Callback API.
+
+    View отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает обработчик
+    из ``dispatch`` в фоне. Подключите в ``urls.py`` через ``path``. По умолчанию
+    view освобождён от CSRF-проверки — VK не присылает CSRF-токен.
+    """
+
+    def view(request: HttpRequest) -> HttpResponse:
+        body, status = dispatch.dispatch(request.body)
+        return HttpResponse(body.encode("utf-8"), status=status, content_type="text/plain")
+
+    if csrf_exempt:
+        return cast(Callable[[HttpRequest], HttpResponse], csrf_exempt_decorator(view))
+    return view

vkx/adapters/fastapi.py

@@ -0,0 +1,45 @@
+"""FastAPI-адаптер Callback API.
+
+FastAPI в зависимости vkx не тянется: модуль импортируют только те, у кого он
+уже есть.
+
+Пример:
+
+    from vkx.adapters.fastapi import create_callback_router
+    from vkx.server import CallbackListener
+
+    listener = CallbackListener([server])
+    dispatch = CallbackDispatch(listener, handler=handle_vk_event)
+    app.include_router(create_callback_router(dispatch))
+
+``handle_vk_event`` получит событие уже после того, как VK прочитает ``ok``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request, Response
+
+from ._common import CallbackDispatch
+
+__all__ = ("create_callback_router",)
+
+
+def create_callback_router(
+    dispatch: CallbackDispatch,
+    *,
+    path: str = "/vk/callback",
+    name: str = "vk_callback",
+) -> APIRouter:
+    """Собрать ``APIRouter`` с POST-роутом для уведомлений Callback API.
+
+    Роут сам отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает
+    обработчик из ``dispatch`` в фоне. Подключите через ``app.include_router``.
+    """
+    router = APIRouter()
+
+    @router.post(path, name=name, include_in_schema=False)
+    async def vk_callback(request: Request) -> Response:
+        body, status = dispatch.dispatch(await request.body())
+        return Response(content=body, status_code=status, media_type="text/plain")
+
+    return router

vkx/adapters/flask.py

@@ -0,0 +1,43 @@
+"""Flask-адаптер Callback API.
+
+Flask в зависимости vkx не тянется: модуль импортируют только те, у кого он
+уже есть.
+
+Flask WSGI синхронный, поэтому используйте ``SyncCallbackDispatch`` с обычным
+(не async) хендлером — он выполнится в том же потоке, что и обработка колбека:
+
+    from vkx.adapters import SyncCallbackDispatch
+    from vkx.adapters.flask import create_callback_router
+
+    dispatch = SyncCallbackDispatch(listener, handler=handle_vk_event)
+    app.register_blueprint(create_callback_router(dispatch))
+"""
+
+from __future__ import annotations
+
+from flask import Blueprint, Response, request
+
+from ._common import SyncCallbackDispatch
+
+__all__ = ("create_callback_router",)
+
+
+def create_callback_router(
+    dispatch: SyncCallbackDispatch,
+    *,
+    path: str = "/vk/callback",
+    name: str = "vk_callback",
+) -> Blueprint:
+    """Собрать ``Blueprint`` с POST-роутом для уведомлений Callback API.
+
+    Роут сам отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает
+    обработчик из ``dispatch`` в фоне. Подключите через ``app.register_blueprint``.
+    """
+    bp = Blueprint(name, __name__)
+
+    @bp.post(path)
+    def vk_callback() -> Response:
+        body, status = dispatch.dispatch(request.get_data())
+        return Response(body, status=status, mimetype="text/plain")
+
+    return bp

vkx/adapters/sanic.py

@@ -0,0 +1,42 @@
+"""Sanic-адаптер Callback API.
+
+Sanic в зависимости vkx не тянется: модуль импортируют только те, у кого он
+уже есть.
+
+Пример:
+
+    from vkx.adapters.sanic import create_callback_router
+
+    dispatch = CallbackDispatch(listener, handler=handle_vk_event)
+    app.blueprint(create_callback_router(dispatch))
+"""
+
+from __future__ import annotations
+
+from sanic import Blueprint, Request
+from sanic.response import HTTPResponse, text
+
+from ._common import CallbackDispatch
+
+__all__ = ("create_callback_router",)
+
+
+def create_callback_router(
+    dispatch: CallbackDispatch,
+    *,
+    path: str = "/vk/callback",
+    name: str = "vk_callback",
+) -> Blueprint:
+    """Собрать ``Blueprint`` с POST-роутом для уведомлений Callback API.
+
+    Роут сам отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает
+    обработчик из ``dispatch`` в фоне. Подключите через ``app.blueprint``.
+    """
+    bp = Blueprint(name)
+
+    @bp.post(path, name=name)
+    async def vk_callback(request: Request) -> HTTPResponse:
+        body, status = dispatch.dispatch(request.body)
+        return text(body, status=status)
+
+    return bp

vkx/adapters/starlette.py

@@ -0,0 +1,41 @@
+"""Starlette-адаптер Callback API.
+
+Starlette в зависимости vkx не тянется: модуль импортируют только те, у кого
+он уже есть (сам Starlette, FastAPI и т.п.).
+
+Пример:
+
+    from vkx.adapters.starlette import create_callback_router
+
+    dispatch = CallbackDispatch(listener, handler=handle_vk_event)
+    app = Starlette(routes=[*create_callback_router(dispatch).routes])
+"""
+
+from __future__ import annotations
+
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route, Router
+
+from ._common import CallbackDispatch
+
+__all__ = ("create_callback_router",)
+
+
+def create_callback_router(
+    dispatch: CallbackDispatch,
+    *,
+    path: str = "/vk/callback",
+    name: str = "vk_callback",
+) -> Router:
+    """Собрать ``Router`` с POST-роутом для уведомлений Callback API.
+
+    Роут сам отвечает VK ``ok`` (или ``confirmation``-кодом) и запускает
+    обработчик из ``dispatch`` в фоне.
+    """
+
+    async def vk_callback(request: Request) -> PlainTextResponse:
+        body, status = dispatch.dispatch(await request.body())
+        return PlainTextResponse(body, status_code=status)
+
+    return Router(routes=[Route(path, vk_callback, methods=["POST"], name=name)])