python-vk-bot 0.1.0__tar.gz

python_vk_bot-0.1.0/.gitignore

@@ -0,0 +1,222 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.agent-work/

python_vk_bot-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes will be documented here, following Keep a Changelog.
+
+## 0.1.0 - 2026-10-31
+
+### Added
+
+- Internal vk-api-upgrade Agent Skill for maintainers to audit VK API compatibility and
+  implement approved upgrades.
+- Bundled telegram-to-vk Agent Skill and migration reference in Python distributions,
+  discoverable with `uvx library-skills` after package installation.
+- Agent Skills documentation covering installation, AI agent setup, usage and approval rules.
+- Public BotSettings based on pydantic-settings, with VK_* environment variables, explicit
+  dotenv loading and subclass extensions; Long Poll and Callback examples use settings.
+- Async Bot and Application with explicit lifecycle, ordered handlers, composable filters,
+  scoped context data and error callbacks.
+- Pydantic v2 message/event models preserving unmodeled VK fields and raw event objects.
+- Callback authentication, confirmation and an optional ASGI receiver with resource limits.
+- Bounded in-memory suppression of successfully processed duplicate events.
+- Python 3.14 package baseline and VK API 5.199 support, verified against official
+  documentation on 2026-10-31.
+- Reusable HTTPX AsyncClient sessions with explicit ownership and timeouts.
+- Asynchronous Long Poll with iterative session recovery.
+- Messaging methods with nonzero int32 random_id generation, editing by message ID or cmid,
+  and forwarding from the source conversation.
+
+### Security
+
+- Callback group/secret checks occur before event dispatch.
+- Credentials and payloads are excluded from library error logs; HTTPX request log query
+  strings are redacted to protect Long Poll keys.

python_vk_bot-0.1.0/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.

python_vk_bot-0.1.0/PKG-INFO

@@ -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)