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

python_vk_bot/transport.py

@@ -0,0 +1,154 @@
+"""Reusable HTTP transport; request credentials never become client defaults."""
+
+import logging
+import re
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Self, cast
+
+import httpx
+from pydantic import JsonValue, SecretStr, ValidationError
+
+from ._config import TransportConfig
+from .errors import (
+    APIError,
+    HTTPError,
+    InvalidResponseError,
+    LifecycleError,
+    NetworkError,
+    RateLimitError,
+)
+from .models.api import APIEnvelope
+
+type Parameter = str | int | float | bool | None
+
+
+class _RedactQuery(logging.Filter):
+    """HTTPX INFO logs otherwise expose the Long Poll key in request URLs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.args, tuple):
+            record.args = tuple(
+                value.copy_with(query=None)
+                if isinstance(value, httpx.URL) and value.query
+                else value
+                for value in record.args
+            )
+        return True
+
+
+class HTTPTransport:
+    """Own a client or borrow an injected client without closing it."""
+
+    def __init__(self, config: TransportConfig, *, client: httpx.AsyncClient | None = None) -> None:
+        self.config = config
+        self._client = client
+        self._owns_client = client is None
+        self._started = False
+        httpx_logger = logging.getLogger("httpx")
+        if not any(isinstance(item, _RedactQuery) for item in httpx_logger.filters):
+            httpx_logger.addFilter(_RedactQuery())
+
+    async def initialize(self) -> None:
+        if self._started:
+            return
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self.config.timeout)
+        if self._client.is_closed:
+            raise LifecycleError("The injected HTTP client is closed")
+        if "authorization" in self._client.headers:
+            raise ValueError("Injected clients must not define a default Authorization header")
+        if {"access_token", "key", "secret"}.intersection(self._client.params):
+            raise ValueError("Injected clients must not define credential query parameters")
+        self._started = True
+
+    async def shutdown(self) -> None:
+        self._started = False
+        if self._owns_client and self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> Self:
+        await self.initialize()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.shutdown()
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        data: Mapping[str, str] | None = None,
+        params: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> JsonValue:
+        if not self._started or self._client is None:
+            raise LifecycleError("Initialize the bot or use its async context manager")
+        try:
+            response = await self._client.request(
+                method,
+                url,
+                data=data,
+                params=params,
+                headers=headers,
+                timeout=self.config.timeout if timeout is None else timeout,
+                follow_redirects=False,
+                auth=None,
+            )
+        except httpx.RequestError:
+            raise NetworkError("VK HTTP request could not complete") from None
+        if not response.is_success:
+            raise HTTPError(response.status_code)
+        try:
+            return cast(JsonValue, response.json())
+        except ValueError:
+            raise InvalidResponseError("VK returned invalid JSON") from None
+
+    async def call(self, method: str, parameters: Mapping[str, Parameter]) -> JsonValue:
+        if re.fullmatch(r"[A-Za-z]+\.[A-Za-z]+", method) is None:
+            raise ValueError("Expected a VK method name such as messages.send")
+        if {"v", "access_token"}.intersection(parameters):
+            raise ValueError("Version and credentials belong to the transport configuration")
+        data = {
+            key: str(int(value)) if isinstance(value, bool) else str(value)
+            for key, value in parameters.items()
+            if value is not None
+        }
+        data["v"] = self.config.api_version
+        payload = await self._request(
+            "POST",
+            f"https://api.vk.ru/method/{method}",
+            data=data,
+            headers={"Authorization": f"Bearer {self.config.token.get_secret_value()}"},
+        )
+        try:
+            envelope = APIEnvelope.model_validate(payload)
+        except ValidationError:
+            raise InvalidResponseError("Invalid VK API envelope") from None
+        if envelope.error is not None:
+            code = envelope.error.error_code
+            error_type = RateLimitError if code == 6 else APIError
+            raise error_type(code, method)
+        if "response" not in envelope.model_fields_set:
+            raise InvalidResponseError("VK API envelope has no response")
+        return envelope.response
+
+    async def poll(self, server: str, *, key: SecretStr, ts: str, wait: int) -> JsonValue:
+        url = httpx.URL(server)
+        if url.scheme != "https" or not url.host or url.userinfo or url.query or url.fragment:
+            raise InvalidResponseError("Unexpected Long Poll server URL")
+        # The community token is only sent to api.vk.ru, never to the polling server.
+        return await self._request(
+            "GET",
+            server,
+            params={"act": "a_check", "key": key.get_secret_value(), "ts": ts, "wait": str(wait)},
+            timeout=max(self.config.timeout, wait + 10.0),
+        )

python_vk_bot-0.1.0.dist-info/METADATA

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: python-vk-bot
+Version: 0.1.0
+Summary: An asynchronous framework for VK community bots.
+Author-email: Aleksei Fomenko <fomenko_ai@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bot,vk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic-settings<3,>=2.12
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: callback
+Requires-Dist: starlette<1,>=0.49; extra == 'callback'
+Requires-Dist: uvicorn<1,>=0.38; extra == 'callback'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="logo.png" alt="python-vk-bot logo" width="720">
+</p>
+
+# python-vk-bot
+
+An asynchronous framework for VK community bots, inspired by python-telegram-bot.
+Development targets **Python 3.14** and VK API **5.199**. The regression suite runs without
+network access; see [verification results](docs/development/verification.md).
+
+## Installation
+
+```bash
+uv add python-vk-bot
+```
+
+### Install from this checkout
+
+```bash
+uv sync --locked
+```
+
+For the optional Callback HTTP receiver:
+
+```bash
+uv sync --locked --extra callback
+```
+
+## Long Poll bot
+
+Enable Bots Long Poll and the `message_new` event in the community settings. Configure
+its event version to match the supported API schema. Supply a community token with the
+required permissions through the environment; messaging is subject to VK's conversation
+and permission rules.
+
+```python
+import asyncio
+
+from python_vk_bot import Application, Bot, BotSettings, Context, MessageHandler, Update, filters
+
+
+async def echo(update: Update, context: Context) -> None:
+    message = update.message
+    if message is not None:
+        await context.bot.send_message(message.peer_id, message.text)
+
+
+async def main() -> None:
+    settings = BotSettings()
+    bot = Bot(settings.token, api_version=settings.api_version, timeout=settings.timeout)
+    app = Application(bot, settings.group_id)
+    app.add_handler(MessageHandler(echo, predicate=filters.TEXT))
+    await app.run_polling(wait=settings.polling_wait)
+
+
+asyncio.run(main())
+```
+
+With `VK_TOKEN` and `VK_GROUP_ID` already set, run the included example:
+
+```bash
+uv run python examples/echo.py
+```
+
+`run_polling()` is awaitable. Cancellation closes owned resources. Handlers run
+sequentially, with the first match in each numeric group. `Context` exposes `bot`,
+`user_data`, `peer_data` and `bot_data`. Use `MessageEventHandler` for button events,
+`filters.LOCATION` for messages containing geo, and `CommandHandler` for `/command` tokens.
+
+## Settings
+
+Import `BotSettings` from `python_vk_bot` or `python_vk_bot.settings`. It uses
+`pydantic-settings` to load and validate configuration when you create an instance.
+Importing the module does not read configuration or require credentials.
+
+| Field | Environment variable | Default |
+| --- | --- | --- |
+| `token` | `VK_TOKEN` | Required, nonempty `SecretStr` |
+| `group_id` | `VK_GROUP_ID` | Required, positive integer |
+| `api_version` | `VK_API_VERSION` | `"5.199"` |
+| `timeout` | `VK_TIMEOUT` | `40.0` seconds, positive and finite |
+| `polling_wait` | `VK_POLLING_WAIT` | `25` seconds, between 1 and 90 |
+
+Use environment variables directly:
+
+```python
+from python_vk_bot import BotSettings
+
+settings = BotSettings()  # Read VK_* variables; no automatic .env loading.
+```
+
+Alternatively, opt into a dotenv file and override a value for this instance:
+
+```python
+from pathlib import Path
+
+from python_vk_bot import BotSettings
+
+settings = BotSettings(_env_file=Path(".env"), timeout=15.0)
+```
+
+Explicit constructor values take precedence over environment variables, which take
+precedence over dotenv values and field defaults. Unrelated dotenv entries are ignored,
+so a project may share its `.env` with other components. Unknown constructor fields are
+also ignored; use `extra="forbid"` in a subclass if you prefer strict configuration.
+Settings only contain configuration: pass their values to `Bot`, `Application` and
+`run_polling` explicitly as shown above. Keep real tokens and `.env` out of Git.
+
+Extend the class with your project's fields:
+
+```python
+from pathlib import Path
+
+from pydantic import Field
+
+from python_vk_bot import BotSettings
+
+
+class ProjectSettings(BotSettings):
+    admin_ids: list[int] = Field(default_factory=list)
+    debug: bool = False
+
+
+settings = ProjectSettings(_env_file=Path(".env"))
+```
+
+These fields read `VK_ADMIN_IDS` (a JSON array such as `[123, 456]`) and `VK_DEBUG`
+(for example, `true`). Override `model_config` with `SettingsConfigDict(env_prefix="MYBOT_")`
+to use another prefix. A field with `Field(validation_alias="DATABASE_URL")` instead reads
+that exact variable name, without the prefix. Token values remain `SecretStr` and can be
+passed directly to `Bot`.
+
+## Bot without polling
+
+```python
+async with Bot(token) as bot:
+    user = await bot.get_user_info(user_id)
+```
+
+An injected `httpx.AsyncClient` remains caller-owned. Methods cover sending, editing,
+forwarding, fetching a message/user, answering message events, and obtaining Long Poll
+connection data. `Bot.request(method, parameters)` exposes raw JSON results for additional
+VK methods; nested request parameters must be JSON encoded explicitly.
+
+Messages use `peer_id`; `Message` exposes both `id` and `conversation_message_id`.
+`send_message` returns an integer message ID and accepts an optional nonzero int32
+`random_id`. Sends are never retried automatically. `edit_message` accepts exactly one
+message identifier and maps `conversation_message_id` to VK's `cmid` parameter.
+
+## Callback API
+
+The [Callback example](examples/callback.py) extends the same base settings with its
+required secrets. For example, to construct a receiver from the environment:
+
+```python
+from pydantic import Field, SecretStr
+
+from python_vk_bot import Application, Bot, BotSettings, Callback
+
+
+class CallbackSettings(BotSettings):
+    callback_secret: SecretStr = Field(min_length=1, repr=False)
+    callback_confirmation: SecretStr = Field(min_length=1, repr=False)
+
+
+settings = CallbackSettings()
+bot = Bot(settings.token, api_version=settings.api_version, timeout=settings.timeout)
+application = Application(bot, settings.group_id)
+# Register your handlers before starting the ASGI application.
+callback = Callback(
+    application,
+    secret=settings.callback_secret,
+    confirmation_code=settings.callback_confirmation,
+)
+asgi_app = callback.create_app()
+```
+
+Set `VK_TOKEN`, `VK_GROUP_ID`, `VK_CALLBACK_SECRET`, and `VK_CALLBACK_CONFIRMATION`, then:
+
+```bash
+uv run --extra callback uvicorn examples.callback:create_app --factory
+```
+
+Expose `/callback` through your HTTPS deployment and configure the same secret in VK.
+ASGI lifespan manages startup/shutdown. `Callback.handle()` is also available for other
+HTTP frameworks, provided the caller manages Application's async lifecycle.
+
+Confirmation returns the configured confirmation code. Ordinary events return `ok` only
+after successful processing. A bounded in-memory cache skips successful duplicates.
+Partial handler failures, restarts and multiple workers can repeat side effects; this
+is not a durable queue or an exactly-once processing guarantee. See the architecture
+for delivery limitations and resource limits.
+
+## Agent Skills
+
+The bundled **telegram-to-vk** Agent Skill helps AI coding agents migrate
+`python-telegram-bot` applications to VK using `python-vk-bot`.
+
+After installing a package version containing the skill, run from your bot project's root:
+
+```bash
+uvx library-skills
+```
+
+Select `telegram-to-vk` and the `.agents/skills` target for a compatible AI coding agent.
+The skill adds no runtime dependencies and does not change the framework's behavior.
+See [Agent Skills](docs/agent-skills.md) for package installation, installing from a local
+checkout, and usage examples.
+
+## Documentation
+
+- [Architecture and lifecycle](docs/architecture/project-architecture.md)
+- [python-telegram-bot design mapping](docs/architecture/python-telegram-bot-compatibility.md)
+- [VK API support](docs/development/api-compatibility.md)
+- [Contributing and verification](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)

python_vk_bot-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+python_vk_bot/__init__.py,sha256=4Qy_CyBUsznCQJ5h3I2VVLMQNWUoTlQc5mOCjYVUMIM,693
+python_vk_bot/_config.py,sha256=Rju-sjCKAfk70ajQbpPMzOuefBIjtgF8tKjOuSYo0AE,744
+python_vk_bot/application.py,sha256=rHjKVJRUTGwqgpp7DRJrZOV1eP-_LZ9_ei90EYsTQcs,8741
+python_vk_bot/bot.py,sha256=rZgunz4lG-P2EFxLMuTl3Smory8soeIbe00YOVkyJ78,6386
+python_vk_bot/callback.py,sha256=9j11jtl4rpTnfUThvOf2g6kb7wYQXAQerHbuk3IYw3o,4726
+python_vk_bot/context.py,sha256=pzsnUSdJsVLCAsCeItf0L804HclyDtzG2laZrLlHDpk,445
+python_vk_bot/errors.py,sha256=36sWLepB5JoZh2-n89wA2CiaEzbKES86Qc818dLkfCw,1148
+python_vk_bot/filters.py,sha256=5fpOdxTZvFmrgokWUvYj1nowCWvPlLt9EUhRmB-0HVg,1285
+python_vk_bot/handlers.py,sha256=iG91bzA40evZFY6Qp78nvoz_O4pjG0lE6p1IwLuCQSY,1974
+python_vk_bot/long_poll.py,sha256=rmAxflq0E3H-tMDybQ7fBf1cKsJQFnaU4VbyQS3BSw4,3777
+python_vk_bot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_vk_bot/settings.py,sha256=JcbDihGRJGRGvBBSeB3j_LPaoX7dkPHfh-WviKQCrwk,915
+python_vk_bot/transport.py,sha256=sfNIEtiKGvaUgU2wm4IrWjrIU1CXMwtR9TnaoBXUzfM,5833
+python_vk_bot/.agents/skills/telegram-to-vk/SKILL.md,sha256=WMrNoxLkhhlu8wnS9rFpZi3OlwBlVNHCYFSNtKmkJzM,2828
+python_vk_bot/.agents/skills/telegram-to-vk/references/migration-mapping.md,sha256=KFxmCQyKbUK7Z0JuS39FocyoFdtnslLLp9j2pNeJAds,9019
+python_vk_bot/models/__init__.py,sha256=L9huCyAM2WWt5JKXyaC8dS0OfTydubdtrGUmvvTnyak,196
+python_vk_bot/models/api.py,sha256=WrPGsBOIO1yFD376b0nlVY75rZWhJPXEJ4VzZeUW6uI,931
+python_vk_bot/models/base.py,sha256=LYcbevtU8jq5QVLo8b1mOv70RzgEYjPtTmhMMe-JN3A,249
+python_vk_bot/models/events.py,sha256=bS8XC0TJrj_AG0u6H9fs35kMkg47EeVoxtaUH7ya1gM,2222
+python_vk_bot/models/messages.py,sha256=CmchlimGmKfj_i-ogHPDZbAk0vPwHKUymfMr_bsWlPc,1223
+python_vk_bot-0.1.0.dist-info/METADATA,sha256=61pB87s_jpj9l0CI6CvvMe-r_av1dGnwonXWexwQJ9Y,8275
+python_vk_bot-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+python_vk_bot-0.1.0.dist-info/licenses/LICENSE,sha256=F-35ycqPcYW243OjxMHCggr_AHQgZLX2zvtZgobVEvo,1072
+python_vk_bot-0.1.0.dist-info/RECORD,,

python_vk_bot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_vk_bot-0.1.0.dist-info/licenses/LICENSE

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