python-vk-bot 0.1.0__py3-none-any.whl

python_vk_bot/callback.py

@@ -0,0 +1,115 @@
+"""Framework-neutral Callback authentication and an optional Starlette HTTP adapter."""
+
+import asyncio
+import hmac
+import json
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING
+
+from pydantic import JsonValue, SecretStr
+
+from .application import Application
+from .errors import CallbackAuthenticationError, InvalidUpdateError, LifecycleError
+from .models import Update
+
+if TYPE_CHECKING:
+    from starlette.applications import Starlette
+    from starlette.requests import Request
+    from starlette.responses import Response
+
+
+class Callback:
+    def __init__(
+        self,
+        application: Application,
+        *,
+        secret: str | SecretStr,
+        confirmation_code: str | SecretStr,
+    ) -> None:
+        self.application = application
+        self._secret = secret if isinstance(secret, SecretStr) else SecretStr(secret)
+        self._confirmation_code = (
+            confirmation_code
+            if isinstance(confirmation_code, SecretStr)
+            else SecretStr(confirmation_code)
+        )
+        if not self._secret.get_secret_value() or not self._confirmation_code.get_secret_value():
+            raise ValueError("Callback secret and confirmation code must be nonempty")
+
+    async def handle(self, payload: dict[str, JsonValue]) -> str:
+        secret = payload.get("secret")
+        group_id = payload.get("group_id")
+        if (
+            type(group_id) is not int
+            or group_id != self.application.group_id
+            or not isinstance(secret, str)
+            or not hmac.compare_digest(secret.encode(), self._secret.get_secret_value().encode())
+        ):
+            raise CallbackAuthenticationError("Callback authentication failed")
+        if payload.get("type") == "confirmation":
+            return self._confirmation_code.get_secret_value()
+        update = Update.from_dict(payload)
+        await self.application.process_update(update)
+        return "ok"
+
+    def create_app(
+        self,
+        *,
+        path: str = "/callback",
+        max_body_bytes: int = 1_048_576,
+        max_pending: int = 32,
+        request_timeout: float = 10.0,
+    ) -> Starlette:
+        """Create an ASGI app. Limits are local policy, not VK API limits.
+
+        The host must run ASGI lifespan; it owns the listener and TLS configuration.
+        """
+        from starlette.applications import Starlette
+        from starlette.requests import ClientDisconnect
+        from starlette.responses import PlainTextResponse
+        from starlette.routing import Route
+
+        if max_body_bytes <= 0 or max_pending <= 0 or request_timeout <= 0:
+            raise ValueError("Callback resource limits must be positive")
+        pending = 0
+
+        @asynccontextmanager
+        async def lifespan(app: Starlette) -> AsyncGenerator[None]:
+            async with self.application:
+                yield
+
+        async def endpoint(request: Request) -> Response:
+            nonlocal pending
+            if pending >= max_pending:
+                return PlainTextResponse("busy", status_code=503)
+            pending += 1
+            try:
+                async with asyncio.timeout(request_timeout):
+                    body = bytearray()
+                    async for chunk in request.stream():
+                        if len(body) + len(chunk) > max_body_bytes:
+                            return PlainTextResponse("too large", status_code=413)
+                        body.extend(chunk)
+                    try:
+                        payload = json.loads(body)
+                    except ValueError, UnicodeDecodeError:
+                        return PlainTextResponse("invalid JSON", status_code=400)
+                    if not isinstance(payload, dict):
+                        return PlainTextResponse("invalid event", status_code=400)
+                    return PlainTextResponse(await self.handle(payload))
+            except CallbackAuthenticationError:
+                return PlainTextResponse("forbidden", status_code=403)
+            except InvalidUpdateError:
+                return PlainTextResponse("invalid event", status_code=400)
+            except TimeoutError, LifecycleError:
+                return PlainTextResponse("unavailable", status_code=503)
+            except ClientDisconnect:
+                return PlainTextResponse("disconnected", status_code=400)
+            except Exception:
+                # Do not expose user code exceptions or echo private request data.
+                return PlainTextResponse("processing failed", status_code=500)
+            finally:
+                pending -= 1
+
+        return Starlette(routes=[Route(path, endpoint, methods=["POST"])], lifespan=lifespan)

python_vk_bot/context.py

@@ -0,0 +1,19 @@
+"""State scopes for one dispatched update."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .bot import Bot
+
+if TYPE_CHECKING:
+    from .application import Application
+
+
+@dataclass(slots=True)
+class Context:
+    application: Application
+    bot: Bot
+    user_data: dict[str, object]
+    peer_data: dict[str, object]
+    bot_data: dict[str, object]
+    error: Exception | None = field(default=None, repr=False)

python_vk_bot/errors.py

@@ -0,0 +1,42 @@
+"""Safe exceptions: messages never include credentials or server payloads."""
+
+
+class VKError(Exception):
+    """Base class for library errors."""
+
+
+class NetworkError(VKError):
+    """A request could not complete; a mutation may already have reached VK."""
+
+
+class HTTPError(VKError):
+    def __init__(self, status_code: int) -> None:
+        self.status_code = status_code
+        super().__init__(f"VK HTTP request failed with status {status_code}")
+
+
+class APIError(VKError):
+    def __init__(self, code: int, method: str) -> None:
+        self.code = code
+        self.method = method
+        super().__init__(f"VK API error {code} in {method}")
+
+
+class RateLimitError(APIError):
+    """VK error 6; no retry or numeric rate assumption is made."""
+
+
+class InvalidResponseError(VKError):
+    """Malformed JSON or an unexpected response shape."""
+
+
+class InvalidUpdateError(VKError):
+    """An event does not match the supported data boundary."""
+
+
+class CallbackAuthenticationError(VKError):
+    """The Callback group or secret did not match."""
+
+
+class LifecycleError(VKError):
+    """An operation is invalid in the current lifecycle state."""

python_vk_bot/filters.py

@@ -0,0 +1,40 @@
+"""Small synchronous predicates; filter execution must not perform blocking I/O."""
+
+import re
+from collections.abc import Callable
+
+from .models import Update
+
+
+class Filter:
+    def __init__(self, predicate: Callable[[Update], bool]) -> None:
+        self.predicate = predicate
+
+    def __call__(self, update: Update) -> bool:
+        return self.predicate(update)
+
+    def __and__(self, other: Filter) -> Filter:
+        return Filter(lambda update: self(update) and other(update))
+
+    def __or__(self, other: Filter) -> Filter:
+        return Filter(lambda update: self(update) or other(update))
+
+    def __invert__(self) -> Filter:
+        return Filter(lambda update: not self(update))
+
+
+class Regex(Filter):
+    """Search the message text using a compiled regular expression."""
+
+    def __init__(self, pattern: str | re.Pattern[str]) -> None:
+        compiled = re.compile(pattern)
+        super().__init__(
+            lambda update: (
+                update.message is not None and compiled.search(update.message.text) is not None
+            )
+        )
+
+
+ALL = Filter(lambda update: True)
+TEXT = Filter(lambda update: update.message is not None and bool(update.message.text))
+LOCATION = Filter(lambda update: update.message is not None and update.message.geo is not None)

python_vk_bot/handlers.py

@@ -0,0 +1,60 @@
+"""Typed handler registration without a conversation-state framework."""
+
+from collections.abc import Awaitable, Callable
+
+from . import filters
+from .context import Context
+from .models import Update
+
+type HandlerCallback = Callable[[Update, Context], Awaitable[None]]
+
+
+class Handler:
+    def __init__(
+        self, callback: HandlerCallback, *, predicate: filters.Filter = filters.ALL
+    ) -> None:
+        self.callback = callback
+        self.predicate = predicate
+
+    def check_update(self, update: Update) -> bool:
+        return self.predicate(update)
+
+    async def handle_update(self, update: Update, context: Context) -> None:
+        await self.callback(update, context)
+
+
+class MessageHandler(Handler):
+    def __init__(
+        self, callback: HandlerCallback, *, predicate: filters.Filter = filters.ALL
+    ) -> None:
+        super().__init__(
+            callback,
+            predicate=filters.Filter(lambda update: update.message is not None) & predicate,
+        )
+
+
+class MessageEventHandler(Handler):
+    def __init__(
+        self, callback: HandlerCallback, *, predicate: filters.Filter = filters.ALL
+    ) -> None:
+        super().__init__(
+            callback,
+            predicate=filters.Filter(lambda update: update.message_event is not None) & predicate,
+        )
+
+
+class CommandHandler(MessageHandler):
+    """Match an explicit /command token; no Telegram mention syntax is inferred."""
+
+    def __init__(self, command: str, callback: HandlerCallback) -> None:
+        if not command or command.startswith("/") or any(char.isspace() for char in command):
+            raise ValueError("command must be a nonempty token without a leading slash")
+        super().__init__(
+            callback,
+            predicate=filters.Filter(
+                lambda update: (
+                    update.message is not None
+                    and update.message.text.split(maxsplit=1)[:1] == [f"/{command}"]
+                )
+            ),
+        )

python_vk_bot/long_poll.py

@@ -0,0 +1,91 @@
+"""VK Bots Long Poll recovery without recursion or detached tasks."""
+
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+
+from pydantic import ValidationError
+
+from .bot import Bot
+from .errors import HTTPError, InvalidResponseError, NetworkError, RateLimitError
+from .models.api import LongPollResponse, LongPollServer
+from .models.events import Update
+
+logger = logging.getLogger(__name__)
+
+
+class LongPoll:
+    def __init__(self, bot: Bot, group_id: int, *, wait: int = 25) -> None:
+        if group_id <= 0:
+            raise ValueError("group_id must be positive")
+        if not 1 <= wait <= 90:
+            raise ValueError("wait must be between 1 and 90 seconds")
+        self.bot = bot
+        self.group_id = group_id
+        self.wait = wait
+        self._server: LongPollServer | None = None
+
+    async def _connect(self, *, preserve_ts: bool = False) -> None:
+        old_ts = self._server.ts if self._server is not None else None
+        server = await self.bot.get_long_poll_server(self.group_id)
+        if preserve_ts and old_ts is not None:
+            server.ts = old_ts
+        self._server = server
+
+    async def get_updates(self) -> list[Update]:
+        """Fetch a batch; the caller owns dispatch and its failure policy."""
+        if self._server is None:
+            await self._connect()
+        server = self._server
+        if server is None:
+            raise InvalidResponseError("Long Poll connection is unavailable")
+        payload = await self.bot.transport.poll(
+            server.server, key=server.key, ts=server.ts, wait=self.wait
+        )
+        try:
+            response = LongPollResponse.model_validate(payload)
+        except ValidationError:
+            raise InvalidResponseError("Invalid Long Poll response") from None
+        if response.failed == 1:
+            if response.ts is None:
+                raise InvalidResponseError("Long Poll recovery has no cursor")
+            server.ts = response.ts
+            logger.warning("Long Poll event history was partially lost")
+            return []
+        if response.failed in (2, 3):
+            await self._connect(preserve_ts=response.failed == 2)
+            return []
+        if response.failed is not None:
+            raise InvalidResponseError("Unknown Long Poll failure code")
+        if response.ts is None or response.updates is None:
+            raise InvalidResponseError("Long Poll response has no cursor or updates")
+        # Validate the whole batch before advancing the cursor; malformed data is fatal.
+        updates = [Update.from_dict(item) for item in response.updates]
+        if any(update.group_id != self.group_id for update in updates):
+            raise InvalidResponseError("Long Poll event belongs to another community")
+        server.ts = response.ts
+        return updates
+
+    async def listen(self) -> AsyncGenerator[Update]:
+        """Retry only polling/network acquisition; authentication errors propagate."""
+        delay = 1.0
+        while True:
+            try:
+                updates = await self.get_updates()
+            except HTTPError as error:
+                if error.status_code != 429 and error.status_code < 500:
+                    raise
+                updates = None
+            except NetworkError, RateLimitError:
+                updates = None
+            if updates is None:
+                logger.warning("Long Poll temporarily unavailable; reconnecting")
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, 30.0)
+                continue
+            delay = 1.0
+            for update in updates:
+                yield update
+            if not updates:
+                # Local anti-spin policy, not a VK rate limit.
+                await asyncio.sleep(0.1)

python_vk_bot/models/__init__.py

@@ -0,0 +1,4 @@
+from .events import Update
+from .messages import Coordinates, Geo, Keyboard, Message, MessageEvent, User
+
+__all__ = ["Coordinates", "Geo", "Keyboard", "Message", "MessageEvent", "Update", "User"]

python_vk_bot/models/api.py

@@ -0,0 +1,37 @@
+"""API envelope and Long Poll response boundaries."""
+
+from pydantic import Field, JsonValue, SecretStr, field_validator
+
+from .base import VKModel
+
+
+class APIErrorData(VKModel):
+    error_code: int
+    error_msg: str = Field(repr=False)
+
+
+class APIEnvelope(VKModel):
+    response: JsonValue = None
+    error: APIErrorData | None = Field(default=None, repr=False)
+
+
+class LongPollServer(VKModel):
+    key: SecretStr
+    server: str
+    ts: str
+
+    @field_validator("ts", mode="before")
+    @classmethod
+    def normalize_ts(cls, value: object) -> object:
+        return str(value) if type(value) is int else value
+
+
+class LongPollResponse(VKModel):
+    failed: int | None = None
+    ts: str | None = None
+    updates: list[dict[str, JsonValue]] | None = None
+
+    @field_validator("ts", mode="before")
+    @classmethod
+    def normalize_ts(cls, value: object) -> object:
+        return str(value) if type(value) is int else value

python_vk_bot/models/base.py

@@ -0,0 +1,9 @@
+"""Shared inbound-model policy."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class VKModel(BaseModel):
+    """Retain unmodeled VK fields without logging their contents."""
+
+    model_config = ConfigDict(extra="allow", hide_input_in_errors=True)

python_vk_bot/models/events.py

@@ -0,0 +1,67 @@
+"""Validate known event objects once and retain unknown event types."""
+
+from typing import Self
+
+from pydantic import JsonValue, PrivateAttr, ValidationError, field_validator, model_validator
+
+from python_vk_bot.errors import InvalidUpdateError
+
+from .base import VKModel
+from .messages import Message, MessageEvent, MessageObject
+
+
+class Update(VKModel):
+    type: str
+    group_id: int
+    event_id: str
+    v: str
+    object: JsonValue
+    _message: Message | None = PrivateAttr(default=None)
+    _message_event: MessageEvent | None = PrivateAttr(default=None)
+
+    @field_validator("event_id", mode="before")
+    @classmethod
+    def normalize_event_id(cls, value: object) -> object:
+        # Callback documentation also contains a numeric event_id example.
+        return str(value) if type(value) is int else value
+
+    @model_validator(mode="after")
+    def parse_object(self) -> Self:
+        if self.type == "message_new":
+            self._message = MessageObject.model_validate(self.object).message
+        elif self.type == "message_event":
+            self._message_event = MessageEvent.model_validate(self.object)
+        return self
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, JsonValue]) -> Self:
+        # Authentication belongs to the Callback boundary, never to an Update.
+        clean = {key: value for key, value in payload.items() if key != "secret"}
+        try:
+            return cls.model_validate(clean)
+        except ValidationError:
+            raise InvalidUpdateError("Invalid VK event structure") from None
+
+    @property
+    def message(self) -> Message | None:
+        return self._message
+
+    @property
+    def message_event(self) -> MessageEvent | None:
+        return self._message_event
+
+    @property
+    def user_id(self) -> int | None:
+        if self.message is not None:
+            return self.message.from_id
+        if self.message_event is not None:
+            return self.message_event.user_id
+        return None
+
+    @property
+    def peer_id(self) -> int | None:
+        if self.message is not None:
+            return self.message.peer_id
+        if self.message_event is not None:
+            return self.message_event.peer_id
+        return None

python_vk_bot/models/messages.py

@@ -0,0 +1,57 @@
+"""The message fields used by this framework, not the entire VK schema."""
+
+from pydantic import Field, JsonValue
+
+from .base import VKModel
+
+
+class Coordinates(VKModel):
+    latitude: float
+    longitude: float
+
+
+class Geo(VKModel):
+    coordinates: Coordinates
+
+
+class Message(VKModel):
+    id: int
+    from_id: int
+    peer_id: int
+    conversation_message_id: int
+    text: str
+    geo: Geo | None = None
+    payload: str | None = None
+    attachments: list[dict[str, JsonValue]] = Field(default_factory=list)
+
+
+class MessageObject(VKModel):
+    message: Message
+
+
+class MessageEvent(VKModel):
+    user_id: int
+    peer_id: int
+    event_id: str
+    conversation_message_id: int | None = None
+    # Official schema says string; deployed button events may contain JSON objects.
+    # Preserve both without silently decoding or discarding the original value.
+    payload: JsonValue = None
+
+
+class User(VKModel):
+    id: int
+    first_name: str | None = None
+    last_name: str | None = None
+    screen_name: str | None = None
+
+
+class Keyboard(VKModel):
+    buttons: list[list[dict[str, JsonValue]]]
+    one_time: bool = False
+    inline: bool = False
+
+
+class MessagePage(VKModel):
+    count: int
+    items: list[Message]

python_vk_bot/settings.py

@@ -0,0 +1,26 @@
+"""Reusable settings loaded only when the caller creates an instance."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from ._config import DEFAULT_API_VERSION, DEFAULT_TIMEOUT, APIVersion, RequestTimeout, Token
+
+
+class BotSettings(BaseSettings):
+    """Read VK_* variables, with optional explicit dotenv loading and subclass fields.
+
+    No instance is created at import time. Pass ``_env_file=Path(".env")`` to opt into
+    dotenv loading. Pass values explicitly to override their environment counterparts.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="VK_",
+        extra="ignore",
+        hide_input_in_errors=True,
+    )
+
+    token: Token = Field(repr=False)
+    group_id: int = Field(gt=0)
+    api_version: APIVersion = DEFAULT_API_VERSION
+    timeout: RequestTimeout = DEFAULT_TIMEOUT
+    polling_wait: int = Field(default=25, ge=1, le=90)