vkx 0.2.0__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. vkx-0.2.2/PKG-INFO +263 -0
  2. vkx-0.2.2/README.md +235 -0
  3. {vkx-0.2.0 → vkx-0.2.2}/pyproject.toml +1 -1
  4. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/__init__.py +12 -0
  5. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/__init__.py +14 -0
  6. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/client.py +171 -6
  7. vkx-0.2.2/src/vkx/client/resolve.py +590 -0
  8. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/upload.py +23 -3
  9. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/docs.py +4 -0
  10. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/groups.py +11 -0
  11. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/messages.py +4 -1
  12. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/photos.py +4 -0
  13. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/objects.py +19 -0
  14. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/groups.py +14 -0
  15. vkx-0.2.0/PKG-INFO +0 -1030
  16. vkx-0.2.0/README.md +0 -1002
  17. {vkx-0.2.0 → vkx-0.2.2}/.gitignore +0 -0
  18. {vkx-0.2.0 → vkx-0.2.2}/LICENSE +0 -0
  19. {vkx-0.2.0 → vkx-0.2.2}/examples/README.md +0 -0
  20. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/__init__.py +0 -0
  21. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/_common.py +0 -0
  22. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/aiohttp.py +0 -0
  23. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/django.py +0 -0
  24. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/fastapi.py +0 -0
  25. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/flask.py +0 -0
  26. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/sanic.py +0 -0
  27. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/adapters/starlette.py +0 -0
  28. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/errors.py +0 -0
  29. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/http.py +0 -0
  30. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/pagination.py +0 -0
  31. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/storage.py +0 -0
  32. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/client/tokens.py +0 -0
  33. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/__init__.py +0 -0
  34. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/base_model.py +0 -0
  35. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/categories.py +0 -0
  36. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/__init__.py +0 -0
  37. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/bot_events.py +0 -0
  38. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/callback_events.py +0 -0
  39. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/enums/__init__.py +0 -0
  40. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/enums/callback_events.py +0 -0
  41. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/enums/group_events.py +0 -0
  42. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/enums/user_events.py +0 -0
  43. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/objects/__init__.py +0 -0
  44. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/objects/group_event_objects.py +0 -0
  45. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/objects/user_event_objects.py +0 -0
  46. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/events/user_events.py +0 -0
  47. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/formatting.py +0 -0
  48. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/__init__.py +0 -0
  49. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/account.py +0 -0
  50. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/ads.py +0 -0
  51. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/app_widgets.py +0 -0
  52. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/apps.py +0 -0
  53. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/auth.py +0 -0
  54. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/base_category.py +0 -0
  55. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/board.py +0 -0
  56. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/bugtracker.py +0 -0
  57. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/calls.py +0 -0
  58. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/database.py +0 -0
  59. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/donut.py +0 -0
  60. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/downloaded_games.py +0 -0
  61. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/fave.py +0 -0
  62. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/friends.py +0 -0
  63. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/gifts.py +0 -0
  64. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/lead_forms.py +0 -0
  65. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/likes.py +0 -0
  66. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/market.py +0 -0
  67. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/newsfeed.py +0 -0
  68. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/notes.py +0 -0
  69. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/notifications.py +0 -0
  70. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/orders.py +0 -0
  71. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/pages.py +0 -0
  72. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/podcasts.py +0 -0
  73. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/polls.py +0 -0
  74. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/pretty_cards.py +0 -0
  75. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/search.py +0 -0
  76. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/secure.py +0 -0
  77. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/stats.py +0 -0
  78. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/status.py +0 -0
  79. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/storage.py +0 -0
  80. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/store.py +0 -0
  81. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/stories.py +0 -0
  82. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/streaming.py +0 -0
  83. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/translations.py +0 -0
  84. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/users.py +0 -0
  85. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/utils.py +0 -0
  86. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/video.py +0 -0
  87. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/wall.py +0 -0
  88. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/methods/widgets.py +0 -0
  89. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/__init__.py +0 -0
  90. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/account.py +0 -0
  91. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/ads.py +0 -0
  92. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/app_widgets.py +0 -0
  93. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/apps.py +0 -0
  94. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/auth.py +0 -0
  95. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/base.py +0 -0
  96. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/board.py +0 -0
  97. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/bugtracker.py +0 -0
  98. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/calls.py +0 -0
  99. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/database.py +0 -0
  100. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/docs.py +0 -0
  101. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/donut.py +0 -0
  102. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/downloaded_games.py +0 -0
  103. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/fave.py +0 -0
  104. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/friends.py +0 -0
  105. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/gifts.py +0 -0
  106. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/lead_forms.py +0 -0
  107. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/likes.py +0 -0
  108. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/market.py +0 -0
  109. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/messages.py +0 -0
  110. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/newsfeed.py +0 -0
  111. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/notes.py +0 -0
  112. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/notifications.py +0 -0
  113. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/orders.py +0 -0
  114. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/pages.py +0 -0
  115. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/photos.py +0 -0
  116. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/podcasts.py +0 -0
  117. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/pretty_cards.py +0 -0
  118. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/search.py +0 -0
  119. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/store.py +0 -0
  120. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/stories.py +0 -0
  121. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/streaming.py +0 -0
  122. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/translations.py +0 -0
  123. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/users.py +0 -0
  124. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/utils.py +0 -0
  125. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/video.py +0 -0
  126. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/wall.py +0 -0
  127. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/models/responses/widgets.py +0 -0
  128. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/py.typed +0 -0
  129. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/__init__.py +0 -0
  130. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/_polling.py +0 -0
  131. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/bots_longpoll.py +0 -0
  132. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/callback.py +0 -0
  133. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/callback_server.py +0 -0
  134. {vkx-0.2.0 → vkx-0.2.2}/src/vkx/server/longpoll.py +0 -0
vkx-0.2.2/PKG-INFO ADDED
@@ -0,0 +1,263 @@
1
+ Metadata-Version: 2.5
2
+ Name: vkx
3
+ Version: 0.2.2
4
+ Summary: Асинхронный клиент VK API: выбор токена по scope, батчинг через execute, типы API/событий и разбор Callback/Long Poll.
5
+ Project-URL: Homepage, https://github.com/matrixd0t/vkx
6
+ Project-URL: Repository, https://github.com/matrixd0t/vkx
7
+ Project-URL: Issues, https://github.com/matrixd0t/vkx/issues
8
+ Author: to4e4ka
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: api-client,asyncio,callback-api,longpoll,vk,vk-api
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Typing :: Typed
21
+ Requires-Python: >=3.12
22
+ Requires-Dist: pydantic>=2.13.5
23
+ Provides-Extra: all
24
+ Requires-Dist: httpx>=0.28.1; extra == 'all'
25
+ Provides-Extra: http
26
+ Requires-Dist: httpx>=0.28.1; extra == 'http'
27
+ Description-Content-Type: text/markdown
28
+
29
+ # vkx
30
+
31
+ [![PyPI](https://img.shields.io/pypi/v/vkx)](https://pypi.org/project/vkx/)
32
+ [![Python](https://img.shields.io/pypi/pyversions/vkx)](https://pypi.org/project/vkx/)
33
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
34
+ [![CI](https://github.com/matrixd0t/vkx/actions/workflows/ci.yml/badge.svg)](https://github.com/matrixd0t/vkx/actions/workflows/ci.yml)
35
+
36
+ Библиотека для работы с VK API. Асинхронный клиент с выбором токена по правам,
37
+ батчингом через `execute`, автопагинацией, типизированными методами и
38
+ Python-моделями ответов. Плюс серверный блок (Callback API / Long Poll) и
39
+ адаптеры для популярных веб-фреймворков.
40
+
41
+ ## Киллер-фичи
42
+
43
+ - **Python-модели ответов** — каждый метод возвращает pydantic-модель
44
+ (`UserFull`, `Message`, `GroupFull`, `Keyboard`…). Всё типизировано, IDE
45
+ подсказывает поля, валидация на границе API. Модели поддерживаются вручную.
46
+ - **Батчинг `execute`** — десятки вызовов сворачиваются в один HTTP-запрос к VK
47
+ API (лимит 25 вызовов / 260 КБ кода на батч). Снаружи `await vk.call(...)` —
48
+ как обычный одиночный вызов.
49
+ - **Автопагинация** — методы с `offset`/`count` сами добирают страницы и
50
+ склеивают тело (`count`, `items`, `profiles`, `groups`). `vk.database.get_countries(count=1500)`
51
+ вернёт 1500 стран одним вызовом.
52
+ - **Cookie-авторизация** — `VKClient(cookies={"p": ..., "remixsid": ...})`
53
+ получает веб-токен и обновляет его сам; токен и владелец сохраняются в Store.
54
+ - **`resolve()`** — по тексту находит упоминания пользователей и сообществ
55
+ (`vk.com/durov`, `vk.com/id123`, `@durov`, `[id123|@Имя]`, приглашения
56
+ `vk.com/invite/CODE`) и возвращает их данные одним запросом. Общий кеш на
57
+ приложение с TTL и лимитом размера.
58
+ - **Выбор токена по scope** — несколько источников (статичные токены, cookies,
59
+ готовые `TokenSource`), клиент сам выбирает подходящий по правам метода и
60
+ отбрасывает источники чужого владельца при `probe`.
61
+ - **Клавиатуры** — `Keyboard`/`KeyboardButton`/`Button`: immutable, разбор и
62
+ сборка, `keyboard.to_json()` для `messages.send`.
63
+ - **Разметка сообщений** — HTML/markdown в `message` разбирается в `format_data`
64
+ VK (смещения в UTF-16 code units).
65
+ - **Серверный блок** — `parse_callback`, `CallbackServer`/`CallbackListener`,
66
+ `LongPoll`, `BotsLongPoll` + адаптеры для FastAPI, Starlette, aiohttp, Sanic,
67
+ Flask, Django.
68
+ - **Загрузка файлов** — `vk.upload.*`: фото, документы, голосовые (multipart
69
+ напрямую HTTP-клиентом, save через очередь).
70
+
71
+ ## Установка
72
+
73
+ ```bash
74
+ pip install "vkx[http]"
75
+ ```
76
+
77
+ Требуется Python ≥ 3.12. `httpx` подключается лениво: если передать свой
78
+ HTTP-клиент, `httpx` не нужен. Фреймворки для адаптеров в `vkx` не входят.
79
+
80
+ ## Быстрый старт
81
+
82
+ ```python
83
+ import asyncio
84
+ from vkx import VKClient
85
+
86
+ async def main() -> None:
87
+ vk = VKClient(tokens="vk1.a....")
88
+ owner = (await vk.users.get())[0]
89
+ print(vk.user_id, owner.first_name)
90
+ await vk.aclose()
91
+
92
+ asyncio.run(main())
93
+ ```
94
+
95
+ Клиент жёстко привязан к одному владельцу: при первом запросе он «прощупывает»
96
+ токены (`probe`) и определяет, кому они принадлежат — пользователю или
97
+ сообществу.
98
+
99
+ ## Клиент
100
+
101
+ ### Создание
102
+
103
+ Передать можно статичный токен, веб-cookies, готовые источники или всё вместе:
104
+
105
+ ```python
106
+ from vkx import VKClient
107
+
108
+ vk = VKClient(tokens="vk1.a....")
109
+ vk = VKClient(cookies={"p": "...", "remixsid": "..."})
110
+ vk = VKClient(tokens=["tok_a", "tok_b"], cookies=[{"p": ..., "remixsid": ...}])
111
+ ```
112
+
113
+ Конструктор не ходит в сеть; сеть трогается при первом `call()` или явном
114
+ `await vk.probe()`.
115
+
116
+ ### Владелец и права
117
+
118
+ ```python
119
+ await vk.probe()
120
+ print(vk.user_id, vk.is_group, vk.group_id) # user_id < 0 — сообщество
121
+ print(vk.permissions) # ['Сообщения', 'Друзья', ...]
122
+ ```
123
+
124
+ ### Батчинг (по умолчанию включён)
125
+
126
+ ```python
127
+ # эти три вызова уйдут одним execute-запросом
128
+ a = await vk.call("users.get", user_ids=1)
129
+ b = await vk.call("users.get", user_ids=2)
130
+ c = await vk.call("users.get", user_ids=3)
131
+ # отключить на один запрос:
132
+ await vk.call("users.get", user_ids=1, batching=False)
133
+ ```
134
+
135
+ ### Автопагинация (по умолчанию включена)
136
+
137
+ ```python
138
+ # доберёт страницы сам, вернёт 1500 стран
139
+ countries = await vk.database.get_countries(count=1500)
140
+ # выключить: async with vk.overrides(pagination=False): ...
141
+ ```
142
+
143
+ ### Cookie-авторизация
144
+
145
+ ```python
146
+ vk = VKClient(cookies={"p": "...", "remixsid": "..."})
147
+ ```
148
+
149
+ Веб-токен получается и обновляется автоматически; токен и владелец сохраняются
150
+ в Store (по умолчанию SQLite в `.vkx/vkx.sqlite`).
151
+
152
+ ### `resolve()`
153
+
154
+ ```python
155
+ result = await vk.resolve("Привет @durov, см. vk.com/club123 и vk.com/invite/abc")
156
+ print(result.users) # [UserFull(...)]
157
+ print(result.groups) # [GroupFull(...)]
158
+ print(result.mentions) # [ResolvedMention(...), ...]
159
+ ```
160
+
161
+ Принимает строку, список строк или словарь `{ключ: текст}` — возвращает тот же
162
+ вид. Все запросы идут одним `execute`. Кеш общий на приложение:
163
+
164
+ ```python
165
+ vk.resolve_cache_ttl = 1800 # секунды (0 — выключить)
166
+ vk.resolve_cache_size = 500 # записей в общем кеше
167
+ ```
168
+
169
+ ### Ошибки, повторы, таймауты
170
+
171
+ - `max_retries` / `retry_backoff` — повторы транзиентных сбоев (сеть, HTTP 5xx/429,
172
+ коды 1/6/9/10/29) с экспоненциальной паузой.
173
+ - `timeout` — ограничение ожидания ответа для `call()` (переопределяется на запрос).
174
+ - `captcha_handler` — обработчик капчи (код 14).
175
+ - `interval` — пауза между HTTP-запросами (по умолчанию 0.5 с для пользователя,
176
+ 0.1 с для сообщества).
177
+ - `await vk.drain()` — отправить очередь немедленно; `await vk.aclose(drain=True)` —
178
+ сначала отправить очередь, потом закрыть.
179
+
180
+ ### Загрузка файлов
181
+
182
+ ```python
183
+ photo = await vk.upload.photo_to_wall(data, peer_id=123)
184
+ await vk.messages.send(peer_id=123, attachment=photo.as_att)
185
+ ```
186
+
187
+ ## Типы и модели
188
+
189
+ `vkx.models` — VK-объекты, модели ответов и события. Типизированные методы
190
+ (`vk.users.get`, `vk.messages.send`, …) возвращают pydantic-модели из
191
+ `vkx.models.responses` / `vkx.models.objects`. Клавиатуры:
192
+
193
+ ```python
194
+ from vkx.models.objects import Keyboard, KeyboardButton
195
+
196
+ kb = Keyboard(
197
+ [KeyboardButton.callback("ОК", payload={"a": 1})],
198
+ inline=True,
199
+ )
200
+ await vk.messages.send(peer_id=123, message="выбор", keyboard=kb.to_json())
201
+ ```
202
+
203
+ Разметка сообщений (HTML/markdown → `format_data` VK):
204
+
205
+ ```python
206
+ from vkx.models.formatting import parse_format
207
+
208
+ text, items = parse_format("**жирный** и _курсив_")
209
+ ```
210
+
211
+ ## Серверный блок
212
+
213
+ ### Callback API
214
+
215
+ ```python
216
+ from vkx.server import parse_callback, CallbackServer, CallbackListener, create_callback_server
217
+
218
+ event = parse_callback(raw_bytes) # bytes/str/dict -> CallbackEvent
219
+ ```
220
+
221
+ `CallbackServer` — состояние одного колбек-сервера (secret, confirmation-код,
222
+ group_id, дедупликация `event_id` и контентная дедупликация комментариев).
223
+ `CallbackListener` — набор серверов, маршрутизация по `group_id`.
224
+ `create_callback_server(client, group_id, url, ...)` — регистрирует сервер через
225
+ `groups.addCallbackServer` и забирает confirmation-код.
226
+
227
+ ### Адаптеры
228
+
229
+ Готовые роуты для FastAPI, Starlette, aiohttp, Sanic, Flask, Django (фреймворки
230
+ опциональны, импортируются лениво):
231
+
232
+ ```python
233
+ from vkx.adapters.fastapi import create_callback_router
234
+ from vkx.server import CallbackDispatch
235
+
236
+ dispatch = CallbackDispatch(server)
237
+ router = create_callback_router(dispatch, path="/vk/callback")
238
+ ```
239
+
240
+ ### Long Poll
241
+
242
+ ```python
243
+ from vkx.server import LongPoll, BotsLongPoll
244
+
245
+ async with LongPoll(vk) as lp:
246
+ async for event in lp:
247
+ ...
248
+ ```
249
+
250
+ `BotsLongPoll(client, group_id=...)` — для сообществ (требует group_id при
251
+ пользовательском токене).
252
+
253
+ ## Примеры и тесты
254
+
255
+ Ручные/живые скрипты: `_example_client.py`, `_test_batch.py`, `_test_pagination.py`,
256
+ `_probe_format.py`. Тесты: `tests/test_*.py` (unittest, Python ≥ 3.12).
257
+
258
+ ```bash
259
+ .venv\Scripts\python.exe tests\test_message_format.py
260
+ .venv\Scripts\python.exe tests\test_resolve.py
261
+ ```
262
+
263
+ Линтер: `uvx ruff check src`. Типы: `uvx pyright`.
vkx-0.2.2/README.md ADDED
@@ -0,0 +1,235 @@
1
+ # vkx
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/vkx)](https://pypi.org/project/vkx/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/vkx)](https://pypi.org/project/vkx/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
6
+ [![CI](https://github.com/matrixd0t/vkx/actions/workflows/ci.yml/badge.svg)](https://github.com/matrixd0t/vkx/actions/workflows/ci.yml)
7
+
8
+ Библиотека для работы с VK API. Асинхронный клиент с выбором токена по правам,
9
+ батчингом через `execute`, автопагинацией, типизированными методами и
10
+ Python-моделями ответов. Плюс серверный блок (Callback API / Long Poll) и
11
+ адаптеры для популярных веб-фреймворков.
12
+
13
+ ## Киллер-фичи
14
+
15
+ - **Python-модели ответов** — каждый метод возвращает pydantic-модель
16
+ (`UserFull`, `Message`, `GroupFull`, `Keyboard`…). Всё типизировано, IDE
17
+ подсказывает поля, валидация на границе API. Модели поддерживаются вручную.
18
+ - **Батчинг `execute`** — десятки вызовов сворачиваются в один HTTP-запрос к VK
19
+ API (лимит 25 вызовов / 260 КБ кода на батч). Снаружи `await vk.call(...)` —
20
+ как обычный одиночный вызов.
21
+ - **Автопагинация** — методы с `offset`/`count` сами добирают страницы и
22
+ склеивают тело (`count`, `items`, `profiles`, `groups`). `vk.database.get_countries(count=1500)`
23
+ вернёт 1500 стран одним вызовом.
24
+ - **Cookie-авторизация** — `VKClient(cookies={"p": ..., "remixsid": ...})`
25
+ получает веб-токен и обновляет его сам; токен и владелец сохраняются в Store.
26
+ - **`resolve()`** — по тексту находит упоминания пользователей и сообществ
27
+ (`vk.com/durov`, `vk.com/id123`, `@durov`, `[id123|@Имя]`, приглашения
28
+ `vk.com/invite/CODE`) и возвращает их данные одним запросом. Общий кеш на
29
+ приложение с TTL и лимитом размера.
30
+ - **Выбор токена по scope** — несколько источников (статичные токены, cookies,
31
+ готовые `TokenSource`), клиент сам выбирает подходящий по правам метода и
32
+ отбрасывает источники чужого владельца при `probe`.
33
+ - **Клавиатуры** — `Keyboard`/`KeyboardButton`/`Button`: immutable, разбор и
34
+ сборка, `keyboard.to_json()` для `messages.send`.
35
+ - **Разметка сообщений** — HTML/markdown в `message` разбирается в `format_data`
36
+ VK (смещения в UTF-16 code units).
37
+ - **Серверный блок** — `parse_callback`, `CallbackServer`/`CallbackListener`,
38
+ `LongPoll`, `BotsLongPoll` + адаптеры для FastAPI, Starlette, aiohttp, Sanic,
39
+ Flask, Django.
40
+ - **Загрузка файлов** — `vk.upload.*`: фото, документы, голосовые (multipart
41
+ напрямую HTTP-клиентом, save через очередь).
42
+
43
+ ## Установка
44
+
45
+ ```bash
46
+ pip install "vkx[http]"
47
+ ```
48
+
49
+ Требуется Python ≥ 3.12. `httpx` подключается лениво: если передать свой
50
+ HTTP-клиент, `httpx` не нужен. Фреймворки для адаптеров в `vkx` не входят.
51
+
52
+ ## Быстрый старт
53
+
54
+ ```python
55
+ import asyncio
56
+ from vkx import VKClient
57
+
58
+ async def main() -> None:
59
+ vk = VKClient(tokens="vk1.a....")
60
+ owner = (await vk.users.get())[0]
61
+ print(vk.user_id, owner.first_name)
62
+ await vk.aclose()
63
+
64
+ asyncio.run(main())
65
+ ```
66
+
67
+ Клиент жёстко привязан к одному владельцу: при первом запросе он «прощупывает»
68
+ токены (`probe`) и определяет, кому они принадлежат — пользователю или
69
+ сообществу.
70
+
71
+ ## Клиент
72
+
73
+ ### Создание
74
+
75
+ Передать можно статичный токен, веб-cookies, готовые источники или всё вместе:
76
+
77
+ ```python
78
+ from vkx import VKClient
79
+
80
+ vk = VKClient(tokens="vk1.a....")
81
+ vk = VKClient(cookies={"p": "...", "remixsid": "..."})
82
+ vk = VKClient(tokens=["tok_a", "tok_b"], cookies=[{"p": ..., "remixsid": ...}])
83
+ ```
84
+
85
+ Конструктор не ходит в сеть; сеть трогается при первом `call()` или явном
86
+ `await vk.probe()`.
87
+
88
+ ### Владелец и права
89
+
90
+ ```python
91
+ await vk.probe()
92
+ print(vk.user_id, vk.is_group, vk.group_id) # user_id < 0 — сообщество
93
+ print(vk.permissions) # ['Сообщения', 'Друзья', ...]
94
+ ```
95
+
96
+ ### Батчинг (по умолчанию включён)
97
+
98
+ ```python
99
+ # эти три вызова уйдут одним execute-запросом
100
+ a = await vk.call("users.get", user_ids=1)
101
+ b = await vk.call("users.get", user_ids=2)
102
+ c = await vk.call("users.get", user_ids=3)
103
+ # отключить на один запрос:
104
+ await vk.call("users.get", user_ids=1, batching=False)
105
+ ```
106
+
107
+ ### Автопагинация (по умолчанию включена)
108
+
109
+ ```python
110
+ # доберёт страницы сам, вернёт 1500 стран
111
+ countries = await vk.database.get_countries(count=1500)
112
+ # выключить: async with vk.overrides(pagination=False): ...
113
+ ```
114
+
115
+ ### Cookie-авторизация
116
+
117
+ ```python
118
+ vk = VKClient(cookies={"p": "...", "remixsid": "..."})
119
+ ```
120
+
121
+ Веб-токен получается и обновляется автоматически; токен и владелец сохраняются
122
+ в Store (по умолчанию SQLite в `.vkx/vkx.sqlite`).
123
+
124
+ ### `resolve()`
125
+
126
+ ```python
127
+ result = await vk.resolve("Привет @durov, см. vk.com/club123 и vk.com/invite/abc")
128
+ print(result.users) # [UserFull(...)]
129
+ print(result.groups) # [GroupFull(...)]
130
+ print(result.mentions) # [ResolvedMention(...), ...]
131
+ ```
132
+
133
+ Принимает строку, список строк или словарь `{ключ: текст}` — возвращает тот же
134
+ вид. Все запросы идут одним `execute`. Кеш общий на приложение:
135
+
136
+ ```python
137
+ vk.resolve_cache_ttl = 1800 # секунды (0 — выключить)
138
+ vk.resolve_cache_size = 500 # записей в общем кеше
139
+ ```
140
+
141
+ ### Ошибки, повторы, таймауты
142
+
143
+ - `max_retries` / `retry_backoff` — повторы транзиентных сбоев (сеть, HTTP 5xx/429,
144
+ коды 1/6/9/10/29) с экспоненциальной паузой.
145
+ - `timeout` — ограничение ожидания ответа для `call()` (переопределяется на запрос).
146
+ - `captcha_handler` — обработчик капчи (код 14).
147
+ - `interval` — пауза между HTTP-запросами (по умолчанию 0.5 с для пользователя,
148
+ 0.1 с для сообщества).
149
+ - `await vk.drain()` — отправить очередь немедленно; `await vk.aclose(drain=True)` —
150
+ сначала отправить очередь, потом закрыть.
151
+
152
+ ### Загрузка файлов
153
+
154
+ ```python
155
+ photo = await vk.upload.photo_to_wall(data, peer_id=123)
156
+ await vk.messages.send(peer_id=123, attachment=photo.as_att)
157
+ ```
158
+
159
+ ## Типы и модели
160
+
161
+ `vkx.models` — VK-объекты, модели ответов и события. Типизированные методы
162
+ (`vk.users.get`, `vk.messages.send`, …) возвращают pydantic-модели из
163
+ `vkx.models.responses` / `vkx.models.objects`. Клавиатуры:
164
+
165
+ ```python
166
+ from vkx.models.objects import Keyboard, KeyboardButton
167
+
168
+ kb = Keyboard(
169
+ [KeyboardButton.callback("ОК", payload={"a": 1})],
170
+ inline=True,
171
+ )
172
+ await vk.messages.send(peer_id=123, message="выбор", keyboard=kb.to_json())
173
+ ```
174
+
175
+ Разметка сообщений (HTML/markdown → `format_data` VK):
176
+
177
+ ```python
178
+ from vkx.models.formatting import parse_format
179
+
180
+ text, items = parse_format("**жирный** и _курсив_")
181
+ ```
182
+
183
+ ## Серверный блок
184
+
185
+ ### Callback API
186
+
187
+ ```python
188
+ from vkx.server import parse_callback, CallbackServer, CallbackListener, create_callback_server
189
+
190
+ event = parse_callback(raw_bytes) # bytes/str/dict -> CallbackEvent
191
+ ```
192
+
193
+ `CallbackServer` — состояние одного колбек-сервера (secret, confirmation-код,
194
+ group_id, дедупликация `event_id` и контентная дедупликация комментариев).
195
+ `CallbackListener` — набор серверов, маршрутизация по `group_id`.
196
+ `create_callback_server(client, group_id, url, ...)` — регистрирует сервер через
197
+ `groups.addCallbackServer` и забирает confirmation-код.
198
+
199
+ ### Адаптеры
200
+
201
+ Готовые роуты для FastAPI, Starlette, aiohttp, Sanic, Flask, Django (фреймворки
202
+ опциональны, импортируются лениво):
203
+
204
+ ```python
205
+ from vkx.adapters.fastapi import create_callback_router
206
+ from vkx.server import CallbackDispatch
207
+
208
+ dispatch = CallbackDispatch(server)
209
+ router = create_callback_router(dispatch, path="/vk/callback")
210
+ ```
211
+
212
+ ### Long Poll
213
+
214
+ ```python
215
+ from vkx.server import LongPoll, BotsLongPoll
216
+
217
+ async with LongPoll(vk) as lp:
218
+ async for event in lp:
219
+ ...
220
+ ```
221
+
222
+ `BotsLongPoll(client, group_id=...)` — для сообществ (требует group_id при
223
+ пользовательском токене).
224
+
225
+ ## Примеры и тесты
226
+
227
+ Ручные/живые скрипты: `_example_client.py`, `_test_batch.py`, `_test_pagination.py`,
228
+ `_probe_format.py`. Тесты: `tests/test_*.py` (unittest, Python ≥ 3.12).
229
+
230
+ ```bash
231
+ .venv\Scripts\python.exe tests\test_message_format.py
232
+ .venv\Scripts\python.exe tests\test_resolve.py
233
+ ```
234
+
235
+ Линтер: `uvx ruff check src`. Типы: `uvx pyright`.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "vkx"
7
- version = "0.2.0"
7
+ version = "0.2.2"
8
8
  description = "Асинхронный клиент VK API: выбор токена по scope, батчинг через execute, типы API/событий и разбор Callback/Long Poll."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12"
@@ -9,6 +9,8 @@ from .client import (
9
9
  DEFAULT_GROUP_INTERVAL,
10
10
  DEFAULT_MAX_RETRIES,
11
11
  DEFAULT_PAGINATION_LIMIT,
12
+ DEFAULT_RESOLVE_CACHE_SIZE,
13
+ DEFAULT_RESOLVE_CACHE_TTL,
12
14
  DEFAULT_RETRY_BACKOFF,
13
15
  DEFAULT_USER_INTERVAL,
14
16
  EXECUTE_BATCH_LIMIT,
@@ -16,6 +18,7 @@ from .client import (
16
18
  INVALID_TOKEN_CODE,
17
19
  PAGINATION_LIMITS,
18
20
  RATE_LIMIT_ERROR_CODES,
21
+ RESOLVE_CACHE,
19
22
  SCOPE_TITLES,
20
23
  TRANSIENT_ERROR_CODES,
21
24
  HttpClient,
@@ -23,6 +26,9 @@ from .client import (
23
26
  JSONStore,
24
27
  MemoryStore,
25
28
  PendingApiCall,
29
+ ResolveCache,
30
+ ResolvedMention,
31
+ ResolveResult,
26
32
  SQLiteStore,
27
33
  State,
28
34
  StaticTokenSource,
@@ -75,6 +81,8 @@ __all__ = [
75
81
  "DEFAULT_GROUP_INTERVAL",
76
82
  "DEFAULT_MAX_RETRIES",
77
83
  "DEFAULT_PAGINATION_LIMIT",
84
+ "DEFAULT_RESOLVE_CACHE_SIZE",
85
+ "DEFAULT_RESOLVE_CACHE_TTL",
78
86
  "DEFAULT_RETRY_BACKOFF",
79
87
  "DEFAULT_USER_INTERVAL",
80
88
  "EXECUTE_BATCH_LIMIT",
@@ -82,6 +90,7 @@ __all__ = [
82
90
  "INVALID_TOKEN_CODE",
83
91
  "PAGINATION_LIMITS",
84
92
  "RATE_LIMIT_ERROR_CODES",
93
+ "RESOLVE_CACHE",
85
94
  "SCOPE_TITLES",
86
95
  "TRANSIENT_ERROR_CODES",
87
96
  "BotsLongPoll",
@@ -94,6 +103,9 @@ __all__ = [
94
103
  "LongPoll",
95
104
  "MemoryStore",
96
105
  "PendingApiCall",
106
+ "ResolveCache",
107
+ "ResolveResult",
108
+ "ResolvedMention",
97
109
  "SQLiteStore",
98
110
  "State",
99
111
  "StaticTokenSource",
@@ -39,6 +39,14 @@ from .pagination import (
39
39
  merge_pages,
40
40
  paginate,
41
41
  )
42
+ from .resolve import (
43
+ DEFAULT_RESOLVE_CACHE_SIZE,
44
+ DEFAULT_RESOLVE_CACHE_TTL,
45
+ RESOLVE_CACHE,
46
+ ResolveCache,
47
+ ResolvedMention,
48
+ ResolveResult,
49
+ )
42
50
  from .storage import (
43
51
  JSONStore,
44
52
  MemoryStore,
@@ -70,6 +78,8 @@ __all__ = [
70
78
  "DEFAULT_GROUP_INTERVAL",
71
79
  "DEFAULT_MAX_RETRIES",
72
80
  "DEFAULT_PAGINATION_LIMIT",
81
+ "DEFAULT_RESOLVE_CACHE_SIZE",
82
+ "DEFAULT_RESOLVE_CACHE_TTL",
73
83
  "DEFAULT_RETRY_BACKOFF",
74
84
  "DEFAULT_USER_INTERVAL",
75
85
  "EXECUTE_BATCH_LIMIT",
@@ -77,6 +87,7 @@ __all__ = [
77
87
  "INVALID_TOKEN_CODE",
78
88
  "PAGINATION_LIMITS",
79
89
  "RATE_LIMIT_ERROR_CODES",
90
+ "RESOLVE_CACHE",
80
91
  "SCOPE_TITLES",
81
92
  "TRANSIENT_ERROR_CODES",
82
93
  "HttpClient",
@@ -84,6 +95,9 @@ __all__ = [
84
95
  "JSONStore",
85
96
  "MemoryStore",
86
97
  "PendingApiCall",
98
+ "ResolveCache",
99
+ "ResolveResult",
100
+ "ResolvedMention",
87
101
  "SQLiteStore",
88
102
  "State",
89
103
  "StaticTokenSource",