fastvk 0.0.1__py3-none-any.whl

fastvk/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .app import FastVK
+from .router import Router
+from . import filters
+from . import fsm
+from . import types
+
+__all__ = ["FastVK", "Router", "filters", "fsm", "types"]

fastvk/api/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .client import APIClient
+
+__all__ = ["APIClient"]

fastvk/api/client.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+import aiohttp
+
+from ..exceptions import VKAPIError
+
+if TYPE_CHECKING:
+    pass
+
+VK_API_BASE = "https://api.vk.com/method/"
+
+
+class _APIMethod:
+    """Lazy proxy for a VK API namespace (e.g. ``messages``, ``groups``)."""
+
+    __slots__ = ("_client", "_prefix")
+
+    def __init__(self, client: APIClient, prefix: str) -> None:
+        self._client = client
+        self._prefix = prefix
+
+    def __getattr__(self, name: str) -> _APICallable:
+        return _APICallable(self._client, f"{self._prefix}.{name}")
+
+
+class _APICallable:
+    """Callable proxy for a single VK API method (e.g. ``messages.send``)."""
+
+    __slots__ = ("_client", "_method")
+
+    def __init__(self, client: APIClient, method: str) -> None:
+        self._client = client
+        self._method = method
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        return await self._client._call(self._method, **kwargs)
+
+
+class APIClient:
+    """
+    Async VK API client with dynamic method dispatch.
+
+    Supports any VK API method via attribute access:
+
+    ```python
+    api = APIClient(token="...")
+    await api.messages.send(peer_id=123, message="Hello", random_id=0)
+    await api.users.get(user_ids=1)
+    ```
+    """
+
+    def __init__(self, token: str, version: str = "5.199") -> None:
+        self.token = token
+        self.version = version
+        self._session: aiohttp.ClientSession | None = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def _call(self, method: str, **kwargs: Any) -> Any:
+        session = await self._get_session()
+        params = {"access_token": self.token, "v": self.version, **kwargs}
+        async with session.post(f"{VK_API_BASE}{method}", data=params) as resp:
+            data: dict = await resp.json(content_type=None)
+        if "error" in data:
+            raise VKAPIError(data["error"])
+        return data.get("response")
+
+    def __getattr__(self, name: str) -> _APIMethod:
+        return _APIMethod(self, name)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()

fastvk/app.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Annotated, TYPE_CHECKING
+
+from annotated_doc import Doc
+
+from .api.client import APIClient
+from .fsm.storage import BaseStorage, MemoryStorage
+from .middleware.base import BaseMiddleware, MiddlewareManager
+from .polling.longpoll import LongPoller
+from .router import Router
+from .types.update import Update
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("fastvk")
+
+
+class FastVK(Router):
+    """
+    FastVK application — the root dispatcher and entry point.
+
+    Extends :class:`~fastvk.Router`, so you can register handlers
+    directly on the bot instance or via ``include_router()``.
+
+    ```python
+    from fastvk import FastVK, Router
+    from fastvk.filters import Command
+    from fastvk.types import Message
+
+    bot = FastVK(token="vk1.a...", group_id=123456789)
+
+    @bot.message(Command("start"))
+    async def start(message: Message) -> None:
+        await message.answer("Привет!")
+
+    if __name__ == "__main__":
+        bot.run_polling()
+    ```
+    """
+
+    def __init__(
+        self,
+        token: Annotated[
+            str,
+            Doc(
+                """
+                VK community token with the required permissions.
+
+                Obtain in community settings → Manage → API usage → Access tokens.
+                The token must have at least the ``messages`` permission.
+                """
+            ),
+        ],
+        group_id: Annotated[
+            int,
+            Doc(
+                """
+                Numeric ID of the VK community.
+
+                Shown in the community URL: ``vk.com/public{group_id}``
+                or retrievable via ``groups.getById``.
+                """
+            ),
+        ],
+        *,
+        api_version: Annotated[
+            str,
+            Doc(
+                """
+                VK API version used for all requests.
+
+                FastVK is tested against 5.199. Avoid downgrading below 5.131.
+                """
+            ),
+        ] = "5.199",
+        storage: Annotated[
+            BaseStorage | None,
+            Doc(
+                """
+                FSM storage backend.
+
+                Defaults to :class:`~fastvk.fsm.MemoryStorage` (in-process, lost on restart).
+                Pass a persistent backend (e.g. Redis) for production bots.
+                """
+            ),
+        ] = None,
+        middleware: Annotated[
+            list[BaseMiddleware] | BaseMiddleware | None,
+            Doc(
+                """
+                Middleware applied to every incoming update.
+
+                Can be a single instance or a list.
+                Middleware is executed in the order provided.
+                """
+            ),
+        ] = None,
+    ) -> None:
+        super().__init__()
+        self.api = APIClient(token=token, version=api_version)
+        self.group_id = group_id
+        self.storage: BaseStorage = storage or MemoryStorage()
+
+        if middleware is None:
+            _mw: list[BaseMiddleware] = []
+        elif isinstance(middleware, list):
+            _mw = middleware
+        else:
+            _mw = [middleware]
+        self.middleware_manager = MiddlewareManager(_mw)
+
+    def middleware(self, mw: BaseMiddleware) -> BaseMiddleware:
+        """
+        Register *mw* as global middleware.
+
+        Can be used as a decorator:
+
+        ```python
+        @bot.middleware
+        class Log(BaseMiddleware):
+            async def __call__(self, handler, event, data):
+                print(event)
+                return await handler(event, data)
+        ```
+        """
+        self.middleware_manager.register(mw)
+        return mw
+
+    async def _process_update(self, update: Update) -> None:
+        await self.middleware_manager.trigger(
+            lambda evt, data: self.feed_update(update, self.api, self.storage),
+            update,
+            {},
+        )
+
+    async def _run_polling(self) -> None:
+        logger.info("FastVK started (group_id=%d)", self.group_id)
+        poller = LongPoller(api=self.api, group_id=self.group_id)
+        try:
+            async for update in poller.listen():
+                asyncio.create_task(self._process_update(update))
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            logger.info("Polling stopped")
+        finally:
+            await self.api.close()
+            await self.storage.close()
+
+    def run_polling(self) -> None:
+        """
+        Start Long Poll and block until interrupted.
+
+        ```python
+        if __name__ == "__main__":
+            bot.run_polling()
+        ```
+        """
+        try:
+            asyncio.run(self._run_polling())
+        except KeyboardInterrupt:
+            logger.info("FastVK stopped by user")

fastvk/exceptions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+
+class FastVKError(Exception):
+    """Base exception for all FastVK errors."""
+
+
+class VKAPIError(FastVKError):
+    """Raised when VK API returns an error response."""
+
+    def __init__(self, error_data: dict) -> None:
+        self.code: int = error_data.get("error_code", 0)
+        self.message: str = error_data.get("error_msg", "Unknown error")
+        self.request_params: list = error_data.get("request_params", [])
+        super().__init__(f"[{self.code}] {self.message}")
+
+
+class HandlerNotFoundError(FastVKError):
+    """Raised when no handler matched the incoming update."""
+
+
+class FilterError(FastVKError):
+    """Raised when a filter fails unexpectedly."""
+
+
+class StorageError(FastVKError):
+    """Raised on FSM storage failures."""
+
+
+class PollingError(FastVKError):
+    """Raised on Long Poll failures that cannot be recovered."""

fastvk/filters/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .base import BaseFilter
+from .builtin import Command, FromUser, IsChat, StateFilter, Text
+
+__all__ = ["BaseFilter", "Command", "FromUser", "IsChat", "StateFilter", "Text"]

fastvk/filters/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseFilter(ABC):
+    """
+    Abstract base class for all FastVK filters.
+
+    A filter is a callable that receives an event object and a handler
+    data dict, and returns a bool indicating whether the handler should run.
+
+    Sync and async filters are both supported:
+
+    ```python
+    class MyFilter(BaseFilter):
+        async def __call__(self, message: Message, data: dict) -> bool:
+            return message.from_id == 123456
+    ```
+    """
+
+    @abstractmethod
+    async def __call__(self, event: Any, data: dict) -> bool: ...

fastvk/filters/builtin.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..fsm.context import FSMContext
+    from ..fsm.state import State
+    from ..types.message import Message
+
+
+class Command:
+    """
+    Filter that matches messages starting with a bot command.
+
+    Handles ``/cmd``, ``/cmd@botname``, and ``/cmd argument`` forms.
+
+    ```python
+    @router.message(Command("start", "help"))
+    async def on_start(message: Message) -> None:
+        await message.answer("Привет!")
+    ```
+    """
+
+    def __init__(self, *commands: str) -> None:
+        self.commands = {cmd.lstrip("/") for cmd in commands}
+
+    def __call__(self, message: Message, data: dict) -> bool:
+        if not message.text:
+            return False
+        text = message.text.strip()
+        for cmd in self.commands:
+            if (
+                text == f"/{cmd}"
+                or text.startswith(f"/{cmd} ")
+                or text.startswith(f"/{cmd}@")
+            ):
+                return True
+        return False
+
+    def __repr__(self) -> str:
+        return f"Command({', '.join(self.commands)!r})"
+
+
+class Text:
+    """
+    Filter that matches message text by exact value or substring.
+
+    ```python
+    @router.message(Text("привет"))
+    async def on_hello(message: Message) -> None:
+        await message.answer("И тебе привет!")
+
+    @router.message(Text("help", contains=True, ignore_case=True))
+    async def on_help_mention(message: Message) -> None:
+        await message.answer("Нужна помощь?")
+    ```
+    """
+
+    def __init__(
+        self,
+        *texts: str,
+        contains: bool = False,
+        ignore_case: bool = True,
+    ) -> None:
+        self.texts = texts
+        self.contains = contains
+        self.ignore_case = ignore_case
+
+    def __call__(self, message: Message, data: dict) -> bool:
+        if not message.text:
+            return False
+        msg = message.text.lower() if self.ignore_case else message.text
+        for t in self.texts:
+            cmp = t.lower() if self.ignore_case else t
+            if self.contains and cmp in msg:
+                return True
+            if not self.contains and msg == cmp:
+                return True
+        return False
+
+    def __repr__(self) -> str:
+        return f"Text({self.texts!r}, contains={self.contains})"
+
+
+class StateFilter:
+    """
+    Filter that matches the user's current FSM state.
+
+    ```python
+    @router.message(StateFilter(Form.waiting_name))
+    async def got_name(message: Message, state: FSMContext) -> None:
+        await state.update_data(name=message.text)
+    ```
+
+    Pass ``None`` to match users with no active state:
+
+    ```python
+    @router.message(StateFilter(None))
+    async def no_state(message: Message) -> None: ...
+    ```
+    """
+
+    def __init__(self, *states: State | str | None) -> None:
+        from ..fsm.state import State as _State
+
+        self._states: list[str | None] = []
+        for s in states:
+            if isinstance(s, _State):
+                self._states.append(s.state)
+            else:
+                self._states.append(s)
+
+    async def __call__(self, message: Message, data: dict) -> bool:
+        ctx: FSMContext | None = data.get("state")
+        current = await ctx.get_state() if ctx is not None else None
+        return current in self._states
+
+    def __repr__(self) -> str:
+        return f"StateFilter({self._states!r})"
+
+
+class FromUser:
+    """
+    Filter that only allows messages from specific user IDs.
+
+    ```python
+    ADMIN_ID = 123456789
+
+    @router.message(FromUser(ADMIN_ID), Command("ban"))
+    async def admin_ban(message: Message) -> None: ...
+    ```
+    """
+
+    def __init__(self, *user_ids: int) -> None:
+        self.user_ids = frozenset(user_ids)
+
+    def __call__(self, message: Message, data: dict) -> bool:
+        return message.from_id in self.user_ids
+
+    def __repr__(self) -> str:
+        return f"FromUser({set(self.user_ids)!r})"
+
+
+class IsChat:
+    """
+    Filter that restricts handlers to a specific chat type.
+
+    ```python
+    @router.message(IsChat("private"))
+    async def private_only(message: Message) -> None: ...
+
+    @router.message(IsChat("chat"))
+    async def chat_only(message: Message) -> None: ...
+    ```
+
+    Accepted values: ``"private"``, ``"chat"``.
+    """
+
+    _PRIVATE = "private"
+    _CHAT = "chat"
+
+    def __init__(self, *types: str) -> None:
+        self.types = frozenset(types)
+
+    def __call__(self, message: Message, data: dict) -> bool:
+        if self._PRIVATE in self.types and message.is_private:
+            return True
+        if self._CHAT in self.types and message.is_chat:
+            return True
+        return False
+
+    def __repr__(self) -> str:
+        return f"IsChat({set(self.types)!r})"
+
+
+def _normalize_filter(f: Any) -> Any:
+    """Wrap a bare :class:`~fastvk.fsm.State` in a :class:`StateFilter`."""
+    from ..fsm.state import State as _State
+
+    if isinstance(f, _State):
+        return StateFilter(f)
+    return f

fastvk/fsm/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .context import FSMContext
+from .state import State, StatesGroup
+from .storage import BaseStorage, MemoryStorage
+
+__all__ = ["FSMContext", "State", "StatesGroup", "BaseStorage", "MemoryStorage"]

fastvk/fsm/context.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .state import State
+    from .storage import BaseStorage
+
+
+class FSMContext:
+    """
+    Per-user FSM state accessor injected into every handler.
+
+    ```python
+    @router.message(Command("start"))
+    async def start(message: Message, state: FSMContext) -> None:
+        await state.set_state(Form.waiting_name)
+        await message.answer("Как тебя зовут?")
+
+    @router.message(StateFilter(Form.waiting_name))
+    async def got_name(message: Message, state: FSMContext) -> None:
+        await state.update_data(name=message.text)
+        await state.set_state(Form.waiting_age)
+        await message.answer("Сколько тебе лет?")
+    ```
+    """
+
+    def __init__(
+        self,
+        storage: BaseStorage,
+        peer_id: int,
+        user_id: int,
+    ) -> None:
+        self._storage = storage
+        self._key = (peer_id, user_id)
+
+    async def get_state(self) -> str | None:
+        """Return the current state string, or ``None`` if no state is set."""
+        return await self._storage.get_state(self._key)
+
+    async def set_state(self, state: State | str | None) -> None:
+        """
+        Set the current state.
+
+        Accepts a :class:`~fastvk.fsm.State` instance, a raw string,
+        or ``None`` to clear the state without wiping data.
+        """
+        from .state import State as _State
+
+        if isinstance(state, _State):
+            state = state.state
+        await self._storage.set_state(self._key, state)
+
+    async def clear(self) -> None:
+        """Reset both the state and the stored data for this user."""
+        await self._storage.set_state(self._key, None)
+        await self._storage.set_data(self._key, {})
+
+    async def get_data(self) -> dict:
+        """Return the stored data dict for this user."""
+        return await self._storage.get_data(self._key)
+
+    async def set_data(self, data: dict) -> None:
+        """Replace the stored data dict for this user."""
+        await self._storage.set_data(self._key, data)
+
+    async def update_data(self, **kwargs: object) -> dict:
+        """
+        Merge *kwargs* into the stored data and return the updated dict.
+
+        ```python
+        await state.update_data(name="Alice", age=30)
+        data = await state.get_data()  # {"name": "Alice", "age": 30}
+        ```
+        """
+        data = await self.get_data()
+        data.update(kwargs)
+        await self.set_data(data)
+        return data

fastvk/fsm/state.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+
+class State:
+    """
+    A single FSM state.
+
+    Declare as a class attribute of a :class:`StatesGroup` subclass —
+    the state name is set automatically from the class and attribute names.
+
+    ```python
+    class Form(StatesGroup):
+        waiting_name = State()   # state == "Form:waiting_name"
+        waiting_age  = State()   # state == "Form:waiting_age"
+    ```
+    """
+
+    def __init__(self, state: str | None = None) -> None:
+        self._state = state
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        if self._state is None:
+            self._state = f"{owner.__name__}:{name}"
+
+    @property
+    def state(self) -> str | None:
+        """Fully qualified state name, e.g. ``"Form:waiting_name"``."""
+        return self._state
+
+    def __repr__(self) -> str:
+        return f"<State {self._state!r}>"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, State):
+            return self._state == other._state
+        if isinstance(other, str):
+            return self._state == other
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self._state)
+
+
+class _StatesGroupMeta(type):
+    """Metaclass that auto-assigns state names to all :class:`State` attributes."""
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict,
+    ) -> _StatesGroupMeta:
+        states: dict[str, State] = {}
+        for attr_name, attr_val in namespace.items():
+            if isinstance(attr_val, State) and attr_val._state is None:
+                attr_val._state = f"{name}:{attr_name}"
+                states[attr_name] = attr_val
+        namespace["_states"] = states
+        return super().__new__(mcs, name, bases, namespace)
+
+
+class StatesGroup(metaclass=_StatesGroupMeta):
+    """
+    Base class for grouping related FSM states.
+
+    ```python
+    class RegistrationForm(StatesGroup):
+        waiting_name  = State()
+        waiting_age   = State()
+        waiting_email = State()
+    ```
+    """
+
+    _states: dict[str, State]