vkx 0.2.2__tar.gz → 0.2.4__tar.gz

{vkx-0.2.2 → vkx-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vkx
-Version: 0.2.2
+Version: 0.2.4
 Summary: Асинхронный клиент VK API: выбор токена по scope, батчинг через execute, типы API/событий и разбор Callback/Long Poll.
 Project-URL: Homepage, https://github.com/matrixd0t/vkx
 Project-URL: Repository, https://github.com/matrixd0t/vkx
@@ -100,18 +100,24 @@ asyncio.run(main())
 
 ### Создание
 
-Передать можно статичный токен, веб-cookies, готовые источники или всё вместе:
+Передать можно статичный токен, веб-cookies, логин/пароль, готовые источники или всё вместе:
 
 ```python
-from vkx import VKClient
+from vkx import VKClient, open_store
 
 vk = VKClient(tokens="vk1.a....")
 vk = VKClient(cookies={"p": "...", "remixsid": "..."})
 vk = VKClient(tokens=["tok_a", "tok_b"], cookies=[{"p": ..., "remixsid": ...}])
+vk = VKClient(cookies="cookies.json")  # в том числе JSON-файл, созданный vkqr
+vk = VKClient(login="user@example.com", password="...", store=open_store("auth.json"))
+# переопределить User-Agent HTTP-клиента:
+vk = VKClient(tokens="vk1.a....", user_agent="MyApp/1.0")
 ```
 
 Конструктор не ходит в сеть; сеть трогается при первом `call()` или явном
 `await vk.probe()`.
+Если передан `user_agent`, он заменяет заголовок `User-Agent` HTTP-клиента;
+переданный вручную `http_client` должен предоставлять изменяемый `headers`.
 
 ### Владелец и права
 
@@ -144,10 +150,58 @@ countries = await vk.database.get_countries(count=1500)
 
 ```python
 vk = VKClient(cookies={"p": "...", "remixsid": "..."})
+vk = VKClient(cookies="cookies.json")
+```
+
+Принимается словарь cookie, список таких словарей или JSON-файл. Поддерживаются
+простой JSON-объект `{"p": "...", "remixsid": "..."}`, список объектов и формат
+[`vkqr`](https://github.com/matrixd0t/vkqr):
+
+```json
+{
+  "cookies": [
+    {
+      "created_at": 1700000000,
+      "user_id": 580106999,
+      "p": "...",
+      "remixsid": "..."
+    }
+  ]
+}
+```
+
+Для формата `vkqr` можно передать путь прямо в `VKClient` — файл сам читается,
+метаданные `created_at` и `user_id` не отправляются как cookies. Веб-токен
+получается и обновляется автоматически; при переданном `store` токен и владелец
+сохраняются в нём. `open_store()` без пути создаёт SQLite в `.vkx/vkx.sqlite`.
+Если `open_store("cookies.json")`
+используется с JSON-файлом `vkqr`, VKX сохраняет cookie-записи в том же массиве
+`cookies`, а кеш токенов и состояния обычных токенов — в служебном поле `_vkx`.
+Старый формат JSONStore читается и преобразуется при следующем сохранении. Если
+в файле несколько разных аккаунтов, один `VKClient` всё равно будет привязан к
+первому успешно проверенному владельцу; для отдельных аккаунтов создавайте
+отдельные клиенты.
+
+### Авторизация по логину и паролю
+
+```python
+from vkx import VKClient, open_store
+
+store = open_store("auth.json")
+vk = VKClient(login="user@example.com", password="...", store=store)
 ```
 
-Веб-токен получается и обновляется автоматически; токен и владелец сохраняются
-в Store (по умолчанию SQLite в `.vkx/vkx.sqlite`).
+Источник сначала пробует сохранённые cookies и обновляет по ним web-токен. Если
+VK отклоняет cookie-сессию, он пробует получить новые cookies через VK ID по
+логину/паролю, сохраняет их и повторяет получение web-токена. При следующем
+запуске можно указать только `login` и тот же `store`: сохранённый пароль будет
+восстановлен. Если для входа VK требует капчу или код подтверждения, авторизация
+только по логину/паролю завершится понятной ошибкой — автоматического обхода
+дополнительной проверки нет.
+
+Пароль сохраняется в Store **без шифрования**. Ограничьте доступ к файлу/БД и не
+коммитьте их в репозиторий; для JSON используйте права доступа, ограниченные
+текущим пользователем.
 
 ### `resolve()`
 

{vkx-0.2.2 → vkx-0.2.4}/README.md

@@ -72,18 +72,24 @@ asyncio.run(main())
 
 ### Создание
 
-Передать можно статичный токен, веб-cookies, готовые источники или всё вместе:
+Передать можно статичный токен, веб-cookies, логин/пароль, готовые источники или всё вместе:
 
 ```python
-from vkx import VKClient
+from vkx import VKClient, open_store
 
 vk = VKClient(tokens="vk1.a....")
 vk = VKClient(cookies={"p": "...", "remixsid": "..."})
 vk = VKClient(tokens=["tok_a", "tok_b"], cookies=[{"p": ..., "remixsid": ...}])
+vk = VKClient(cookies="cookies.json")  # в том числе JSON-файл, созданный vkqr
+vk = VKClient(login="user@example.com", password="...", store=open_store("auth.json"))
+# переопределить User-Agent HTTP-клиента:
+vk = VKClient(tokens="vk1.a....", user_agent="MyApp/1.0")
 ```
 
 Конструктор не ходит в сеть; сеть трогается при первом `call()` или явном
 `await vk.probe()`.
+Если передан `user_agent`, он заменяет заголовок `User-Agent` HTTP-клиента;
+переданный вручную `http_client` должен предоставлять изменяемый `headers`.
 
 ### Владелец и права
 
@@ -116,10 +122,58 @@ countries = await vk.database.get_countries(count=1500)
 
 ```python
 vk = VKClient(cookies={"p": "...", "remixsid": "..."})
+vk = VKClient(cookies="cookies.json")
+```
+
+Принимается словарь cookie, список таких словарей или JSON-файл. Поддерживаются
+простой JSON-объект `{"p": "...", "remixsid": "..."}`, список объектов и формат
+[`vkqr`](https://github.com/matrixd0t/vkqr):
+
+```json
+{
+  "cookies": [
+    {
+      "created_at": 1700000000,
+      "user_id": 580106999,
+      "p": "...",
+      "remixsid": "..."
+    }
+  ]
+}
+```
+
+Для формата `vkqr` можно передать путь прямо в `VKClient` — файл сам читается,
+метаданные `created_at` и `user_id` не отправляются как cookies. Веб-токен
+получается и обновляется автоматически; при переданном `store` токен и владелец
+сохраняются в нём. `open_store()` без пути создаёт SQLite в `.vkx/vkx.sqlite`.
+Если `open_store("cookies.json")`
+используется с JSON-файлом `vkqr`, VKX сохраняет cookie-записи в том же массиве
+`cookies`, а кеш токенов и состояния обычных токенов — в служебном поле `_vkx`.
+Старый формат JSONStore читается и преобразуется при следующем сохранении. Если
+в файле несколько разных аккаунтов, один `VKClient` всё равно будет привязан к
+первому успешно проверенному владельцу; для отдельных аккаунтов создавайте
+отдельные клиенты.
+
+### Авторизация по логину и паролю
+
+```python
+from vkx import VKClient, open_store
+
+store = open_store("auth.json")
+vk = VKClient(login="user@example.com", password="...", store=store)
 ```
 
-Веб-токен получается и обновляется автоматически; токен и владелец сохраняются
-в Store (по умолчанию SQLite в `.vkx/vkx.sqlite`).
+Источник сначала пробует сохранённые cookies и обновляет по ним web-токен. Если
+VK отклоняет cookie-сессию, он пробует получить новые cookies через VK ID по
+логину/паролю, сохраняет их и повторяет получение web-токена. При следующем
+запуске можно указать только `login` и тот же `store`: сохранённый пароль будет
+восстановлен. Если для входа VK требует капчу или код подтверждения, авторизация
+только по логину/паролю завершится понятной ошибкой — автоматического обхода
+дополнительной проверки нет.
+
+Пароль сохраняется в Store **без шифрования**. Ограничьте доступ к файлу/БД и не
+коммитьте их в репозиторий; для JSON используйте права доступа, ограниченные
+текущим пользователем.
 
 ### `resolve()`
 

{vkx-0.2.2 → vkx-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vkx"
-version = "0.2.2"
+version = "0.2.4"
 description = "Асинхронный клиент VK API: выбор токена по scope, батчинг через execute, типы API/событий и разбор Callback/Long Poll."
 readme = "README.md"
 requires-python = ">=3.12"

{vkx-0.2.2 → vkx-0.2.4}/src/vkx/__init__.py

@@ -25,6 +25,7 @@ from .client import (
     HttpResponse,
     JSONStore,
     MemoryStore,
+    PasswordCookieSource,
     PendingApiCall,
     ResolveCache,
     ResolvedMention,
@@ -102,6 +103,7 @@ __all__ = [
     "JSONStore",
     "LongPoll",
     "MemoryStore",
+    "PasswordCookieSource",
     "PendingApiCall",
     "ResolveCache",
     "ResolveResult",

{vkx-0.2.2 → vkx-0.2.4}/src/vkx/client/__init__.py

@@ -59,6 +59,7 @@ from .storage import (
 from .tokens import (
     CATEGORY_SCOPES,
     SCOPE_TITLES,
+    PasswordCookieSource,
     StaticTokenSource,
     TokenSource,
     TokenSourceError,
@@ -94,6 +95,7 @@ __all__ = [
     "HttpResponse",
     "JSONStore",
     "MemoryStore",
+    "PasswordCookieSource",
     "PendingApiCall",
     "ResolveCache",
     "ResolveResult",

{vkx-0.2.2 → vkx-0.2.4}/src/vkx/client/client.py

@@ -10,8 +10,9 @@ groups.getById (токен группы). Владельцем становит
     vk.permissions  # ['Сообщения', 'Друзья', ...]
     await vk.call("messages.send", peer_id=1, message="hi")
 
-Источники токенов задаются тремя необязательными полями: tokens (строки или
-TokenSource), cookies (словари с p и remixsid) и sources (готовые TokenSource).
+Источники токенов задаются необязательными tokens (строки или TokenSource),
+cookies (словари, JSON-записи или путь к JSON-файлу), login/password или sources
+(готовые TokenSource).
 Из tokens/cookies источники создаются автоматически; можно передавать один
 элемент или iterable. Все полученные источники опрашиваются при probe: нерабочие
 отбрасываются с логированием причины, а источники с чужим владельцем — по id
@@ -19,10 +20,10 @@ TokenSource), cookies (словари с p и remixsid) и sources (готовы
 
 HTTP: клиент работает с протоколом HttpClient (асинхронные get/post); httpx —
 опциональная зависимость, создаётся лениво, если свой клиент не передан.
-http_client / base_api_url / v задаются у клиента и могут быть переопределены
-для отдельного запроса (call); method_versions задаёт версии по умолчанию
-отдельных методов (messages.send и messages.edit используют v=5.281). Явный v вызова
-приоритетнее.
+user_agent при передаче заменяет User-Agent в заголовках HTTP-клиента.
+http_client / base_api_url / v задаются у клиента и могут быть переопределены для
+отдельного запроса (call); method_versions задаёт версии по умолчанию отдельных
+методов (messages.send и messages.edit используют v=5.281). Явный v вызова приоритетнее.
 
 Очередь и батчинг: call() фиксирует маршрут запроса (_Queued: кандидаты, HTTP-
 настройки и текущий источник) и кладёт его в очередь; PendingApiCall ждёт
@@ -50,6 +51,7 @@ import time
 from collections import deque
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Mapping
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, Self, overload
 
 from ..models.categories import APICategories
@@ -60,7 +62,7 @@ from ..models.formatting import (
 )
 from . import pagination
 from .errors import VKError, VKTimeoutError, VKTransportError, build_error
-from .http import API_HOST, API_VERSION, HttpClient, create_http_client
+from .http import API_HOST, API_VERSION, HttpClient, create_http_client, override_user_agent
 from .resolve import (
     DEFAULT_RESOLVE_CACHE_SIZE,
     DEFAULT_RESOLVE_CACHE_TTL,
@@ -74,6 +76,7 @@ from .resolve import (
 from .storage import Store
 from .tokens import (
     ALL_SCOPES,
+    PasswordCookieSource,
     StaticTokenSource,
     TokenSource,
     TokenSourceError,
@@ -103,7 +106,7 @@ _FORMAT_METHODS: frozenset[str] = frozenset({"messages.send", "messages.edit"})
 CookieMap = Mapping[str, str]
 TokenInput = str | TokenSource
 TokensInput = TokenInput | Iterable[TokenInput] | None
-CookiesInput = CookieMap | Iterable[CookieMap] | None
+CookiesInput = CookieMap | Iterable[CookieMap] | str | Path | None
 SourcesInput = TokenSource | Iterable[TokenSource] | None
 CaptchaHandler = Callable[[VKError], "Awaitable[Mapping[str, str] | None] | Mapping[str, str] | None"]
 """Обработчик капчи: получает VKCaptchaError, возвращает лишние параметры запроса."""
@@ -244,15 +247,43 @@ def _as_list(value: Any) -> list[Any]:
 
 
 def _iter_cookie_dicts(cookies: CookiesInput) -> list[dict[str, str]]:
-    """Нормализует cookies (один словарь или iterable) и проверяет p + remixsid."""
+    """Читает и нормализует cookies из словаря, iterable или JSON-файла."""
     if cookies is None:
         return []
-    items = [cookies] if isinstance(cookies, Mapping) else list(cookies)
+
+    payload: Any = cookies
+    if isinstance(cookies, (str, Path)):
+        path = Path(cookies)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise TokenSourceError(f"не удалось прочитать JSON cookies из {path}") from exc
+
+    if isinstance(payload, Mapping):
+        if "cookies" in payload and not all(
+            name in payload for name in ("p", "remixsid")
+        ):
+            items = payload["cookies"]
+            if not isinstance(items, list):
+                raise TokenSourceError('cookies: поле "cookies" в JSON должно быть списком')
+        else:
+            items = [payload]
+    elif isinstance(payload, Iterable) and not isinstance(payload, (str, bytes)):
+        items = list(payload)
+    else:
+        raise TokenSourceError(
+            "cookies: ожидался словарь, список cookie-записей или JSON-файл"
+        )
+
     result: list[dict[str, str]] = []
     for item in items:
         if not isinstance(item, Mapping):
-            raise TypeError(f"cookies: ожидался словарь, получено {item!r}")
+            raise TokenSourceError("cookies: каждая запись должна быть JSON-объектом")
         value = {str(key): str(val) for key, val in item.items()}
+        if "p" in item and "remixsid" in item:
+            # Метаданные записей vkqr — не cookie и не должны уходить HTTP-клиенту.
+            for name in ("created_at", "user_id", "_vkx"):
+                value.pop(name, None)
         validate_web_cookies(value)
         result.append(value)
     return result
@@ -487,8 +518,9 @@ class VKClient(APICategories):
     """Клиент VK API: источники токенов одного владельца, очередь и батчинг execute.
 
     Источники задаются необязательными tokens (строки/TokenSource), cookies
-    (словари с p и remixsid; проверяются сразу) и sources (готовые TokenSource);
-    tokens/cookies превращаются в источники автоматически, можно смешивать.
+    (словари с p и remixsid, JSON-структура или путь к JSON-файлу), логином/паролем
+    или готовыми sources (TokenSource). Источники проверяются при probe; клиент
+    сохраняет привязку к владельцу первого рабочего источника.
     Конструктор не обращается к сети. probe() (автоматически при первом call())
     опрашивает все источники: нерабочие отбрасываются с логированием причины,
     клиент привязывается к владельцу первого валидного токена (user_id
@@ -504,11 +536,14 @@ class VKClient(APICategories):
         *,
         logger: logging.Logger | None = None,
         http_client: HttpClient | None = None,
+        user_agent: str | None = None,
         base_api_url: str = API_HOST,
         v: str = API_VERSION,
         method_versions: Mapping[str, str] | None = None,
         lang: int = 0,
         store: Store | None = None,
+        login: str | None = None,
+        password: str | None = None,
         interval: float | None = None,
         max_retries: int = DEFAULT_MAX_RETRIES,
         retry_backoff: float = DEFAULT_RETRY_BACKOFF,
@@ -534,18 +569,38 @@ class VKClient(APICategories):
             raise ValueError("resolve_cache_ttl: ttl кеша не может быть отрицательным")
         if resolve_cache_size < 0:
             raise ValueError("resolve_cache_size: размер кеша не может быть отрицательным")
+        if login is not None and not login.strip():
+            raise ValueError("login: укажите логин VK")
+        if password is not None and login is None:
+            raise ValueError("password: для пароля требуется login")
+        if password == "":
+            raise ValueError("password: пароль не может быть пустым")
         cookie_dicts = _iter_cookie_dicts(cookies)
         token_sources = _token_sources(tokens, store=store)
         explicit_sources = _source_objects(sources)
         self._own_http = http_client is None
         self._http: HttpClient = http_client or create_http_client()
+        if user_agent is not None:
+            override_user_agent(self._http, user_agent)
         self._base_api_url = base_api_url.rstrip("/")
+        self._password_source = (
+            PasswordCookieSource(
+                login,
+                password,
+                http=http_client,
+                store=store,
+                user_agent=user_agent,
+            )
+            if login is not None
+            else None
+        )
         built: list[TokenSource] = [
             *token_sources,
             *(
                 WebCookieSource(item, http=self._http, store=store, source=f"web{index}")
                 for index, item in enumerate(cookie_dicts)
             ),
+            *([self._password_source] if self._password_source is not None else []),
             *explicit_sources,
         ]
         self._entries = [TokenSourceEntry(s) for s in built]
@@ -1612,6 +1667,8 @@ class VKClient(APICategories):
         error = VKError("клиент закрыт", client=self)
         while self._queue:
             self._queue.popleft().request.set_error(error)
+        if self._password_source is not None:
+            await self._password_source.aclose()
         if self._own_http:
             await self._http.aclose()
 

{vkx-0.2.2 → vkx-0.2.4}/src/vkx/client/http.py

@@ -8,6 +8,7 @@ status_code / text / json(). httpx — опциональная зависимо
 
 from __future__ import annotations
 
+from collections.abc import MutableMapping
 from typing import Any, Protocol, cast, runtime_checkable
 
 DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:159.0) Gecko/20100101 Firefox/159.0"
@@ -43,6 +44,20 @@ class HttpClient(Protocol):
     async def aclose(self) -> None: ...
 
 
+def override_user_agent(http_client: HttpClient, user_agent: str) -> None:
+    """Переопределить User-Agent в заголовках HTTP-клиента."""
+    headers = getattr(http_client, "headers", None)
+    if not isinstance(headers, MutableMapping):
+        raise TypeError(
+            "user_agent: HTTP-клиент должен предоставлять изменяемые заголовки headers"
+        )
+
+    for name in tuple(headers):
+        if isinstance(name, str) and name.casefold() == "user-agent":
+            del headers[name]
+    headers["User-Agent"] = user_agent
+
+
 def create_http_client() -> HttpClient:
     """HTTP-клиент по умолчанию; httpx импортируется лениво (опциональная зависимость)."""
     try: