s-browserkit 0.0.1__py3-none-any.whl

browserkit/__init__.py

@@ -0,0 +1,185 @@
+"""browserkit — БРАУЗЕРНЫЙ СЛОЙ экосистемы китов: живой браузер, антибот, стелс.
+
+ФОРМА ГРАФА::
+
+        clikit          adapterkit          <- ветки-оболочки
+             \\             /
+              \\           /
+               librarykit                   <- ОРКЕСТРАТОР (сессии, лимиты, фабрики)
+                /        \\
+        browserkit        …                 <- СЛОЙ-КИТ (браузер и антибот)
+                \\        /
+                 corekit                    <- ОСНОВАНИЕ (значения и чистые правила)
+
+Что сюда переехало из `librarykit` (реальный код, не копия):
+
+* :mod:`browserkit.browser` — лаунчеры (системный Chromium по CDP, персистентный
+  контекст), anti-detect и undetected-бэкенды, `capture_tap` (нормализованный
+  event-tap над любым движком), `state` (storage-state, тёплый вход, детекторы
+  протухания), геометрия окна и брони портов;
+* :mod:`browserkit.antibot` — исполнители запроса, которые ходят «как браузер»:
+  TLS/JA3-импersonate без браузера, запрос через CDP-бэкенд, in-page fetch,
+  warmup-минтер одноразовых токенов;
+* :mod:`browserkit.profile_health` — предстартовая проверка браузерного профиля
+  (битые Cookies/Preferences, распухший кэш) и карантин;
+* :mod:`browserkit.proc` — запуск подпроцессов без всплывающих консолей;
+* :mod:`browserkit.ports` — Protocol'ы, которых киту не хватает снаружи.
+
+★ ГЛАВНОЕ — ФАСАД ВОЗМОЖНОСТЕЙ (:mod:`browserkit.capabilities`). Потребитель
+просит ЦЕЛЬ, а не движок::
+
+    import browserkit
+    backend = browserkit.open_browser(browserkit.Capability.STEALTH_SESSION,
+                                      profile_dir=profile)
+    http = browserkit.make_requester(browserkit.Capability.STEALTH_REQUEST)
+
+Замена движка (anti-detect Firefox начал палиться) — правка ОДНОЙ таблицы внутри
+кита; ни один навык не меняется, потому что ни один навык не назвал движок.
+
+ЛЕНИВОСТЬ. `import browserkit` НЕ поднимает браузер и НЕ импортирует ни одного
+тяжёлого движка: `browser`/`antibot` — реальные подпакеты, но резолвятся через
+PEP 562 по факту обращения; сами вендоры (playwright/camoufox/nodriver/curl_cffi)
+тянутся ещё позже — внутри бэкендов, где уже бросается внятное
+`BrowserUnavailable` с инструкцией по установке.
+
+СОВМЕСТИМОСТЬ. Прежние пути импорта (`librarykit.browser.*`,
+`librarykit.antibot.*`, `librarykit.profile_health`) продолжают работать: там
+оставлены АЛИАСЫ НА ТЕ ЖЕ модули (`sys.modules`), а не копии, поэтому
+monkeypatch, `isinstance` и `is`-сравнения ведут себя как до переноса.
+"""
+from __future__ import annotations
+
+from importlib import import_module as _import_module
+from importlib.util import find_spec as _find_spec
+from typing import TYPE_CHECKING
+
+from browserkit.capabilities import (
+    Capability,
+    CapabilityUnavailable,
+    capability_plan,
+    describe_capabilities,
+    is_capability_available,
+    make_requester,
+    open_browser,
+    set_capability_plan,
+)
+from browserkit.ports import (
+    BrowserEngineRole,
+    HttpRequestExecutor,
+    SyncHttpRequestExecutor,
+    SyncTransport,
+    Transport,
+)
+
+__version__ = "0.0.1"
+
+if TYPE_CHECKING:  # pragma: no cover - только статическая видимость для IDE/mypy
+    from typing import Any
+
+    from browserkit.antibot import (
+        CurlCffiTransport as CurlCffiTransport,
+    )
+    from browserkit.antibot import (
+        TokenHarvest as TokenHarvest,
+    )
+    from browserkit.antibot import (
+        WarmupTokenMinter as WarmupTokenMinter,
+    )
+    from browserkit.browser import (
+        BrowserUnavailable as BrowserUnavailable,
+    )
+    from browserkit.profile_health import (
+        ProfileHealth as ProfileHealth,
+    )
+    from browserkit.profile_health import (
+        check_profile as check_profile,
+    )
+    from browserkit.profile_health import (
+        ensure_healthy_profile as ensure_healthy_profile,
+    )
+
+#: Ленивые ИМЕНА корня: имя → модуль-источник. Держим их ленивыми по той же
+#: причине, что и в `librarykit`: `import browserkit` обязан стоить дёшево, чтобы
+#: фасад возможностей можно было спрашивать («умеешь ли ты стелс?»), не поднимая
+#: ни одного движка.
+_LAZY_NAMES: dict[str, str] = {
+    # browser
+    "BrowserUnavailable": "browserkit.browser",
+    "build_capture_backend": "browserkit.browser",
+    "attach_capture_tap": "browserkit.browser",
+    "camoufox_available": "browserkit.browser",
+    "nodriver_available": "browserkit.browser",
+    "playwright_available": "browserkit.browser",
+    # antibot
+    "CurlCffiTransport": "browserkit.antibot",
+    "TokenHarvest": "browserkit.antibot",
+    "WarmupTokenMinter": "browserkit.antibot",
+    "page_fetch": "browserkit.antibot",
+    # profile_health
+    "ProfileHealth": "browserkit.profile_health",
+    "ProfileProblem": "browserkit.profile_health",
+    "check_profile": "browserkit.profile_health",
+    "ensure_healthy_profile": "browserkit.profile_health",
+    "quarantine_profile": "browserkit.profile_health",
+    # proc
+    "ProcResult": "browserkit.proc",
+}
+
+__all__ = [
+    # ★ фасад возможностей — рекомендуемый вход
+    "Capability",
+    "CapabilityUnavailable",
+    "open_browser",
+    "make_requester",
+    "is_capability_available",
+    "describe_capabilities",
+    "capability_plan",
+    "set_capability_plan",
+    # порты (контракты)
+    "Transport",
+    "SyncTransport",
+    "HttpRequestExecutor",
+    "SyncHttpRequestExecutor",
+    "BrowserEngineRole",
+    # ленивые имена реализаций (совместимость с прежним корнем librarykit)
+    "BrowserUnavailable",
+    "build_capture_backend",
+    "attach_capture_tap",
+    "camoufox_available",
+    "nodriver_available",
+    "playwright_available",
+    "CurlCffiTransport",
+    "TokenHarvest",
+    "WarmupTokenMinter",
+    "page_fetch",
+    "ProfileHealth",
+    "ProfileProblem",
+    "check_profile",
+    "ensure_healthy_profile",
+    "quarantine_profile",
+    "ProcResult",
+]
+
+
+def __getattr__(name: str) -> Any:  # `Any` — только под TYPE_CHECKING
+    """Ленивый резолв (PEP 562): сперва карта имён, затем РЕАЛЬНЫЙ подмодуль."""
+    target = _LAZY_NAMES.get(name)
+    if target is None:
+        if not name.startswith("_"):
+            try:
+                found = _find_spec(f"{__name__}.{name}") is not None
+            except (ImportError, ValueError):
+                found = False
+            if found:
+                module = _import_module(f"{__name__}.{name}")
+                globals()[name] = module
+                return module
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(_import_module(target), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Полная поверхность корня: жадные атрибуты + `__all__` + ленивые имена."""
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_NAMES))

browserkit/antibot/__init__.py

@@ -0,0 +1,131 @@
+"""Антибот-стратегия как ВЫБОР ТРАНСПОРТА, а не переписывание кода вызова.
+
+ДОМ ПАКЕТА — БРАУЗЕРНЫЙ КИТ. Раньше код жил в `librarykit`
+(а до того в `adapterkit.antibot`); по обоим старым путям остались АЛИАСЫ на эти
+же модули. curl-cffi — ОПЦИОНАЛЬНЫЙ extra `[antibot]` (ленивый импорт внутри
+транспорта), кит без extras не падает на import пакета.
+
+Идея: антибот — это не «headless vs
+residential proxy», а пять уровней архитектуры (Tier 0-4). Сервис «опт-инится» в
+нужный уровень, просто выбрав транспорт у эндпоинта (`Endpoint.transport`):
+
+- `TransportKind.HTTP`      → `HttpxTransport`  (Tier 0, обычный httpx) — другой модуль;
+- `TransportKind.CURL_CFFI` → `CurlCffiTransport` (Tier 1-3, JA3-имитация Chrome);
+- `TransportKind.BROWSER`   → `CdpTransport`    (Tier 0-1, реальный системный Edge/Chrome).
+
+Каждый из них реализует ОДИН И ТОТ ЖЕ контракт `ports.Transport`
+(`async request(method, url, *, ...) -> httpx.Response`), поэтому вышестоящий код
+(`HttpClient`/`ErrorMapper`/адаптер) не различает транспорты — меняется только
+TLS-fingerprint и источник заголовков, но НЕ форма вызова. Маппинг кодов в
+доменные ошибки — НЕ здесь (это `HttpClient`/`ErrorMapper`); транспорт бросает
+`TransportError` только на сетевых сбоях и возвращает сырой `httpx.Response`.
+
+Этот пакет — ТОНКИЙ ФАСАД: механически разнесён по ответственности на подмодули
+(`._helpers` — обёртка ошибок + нормализация ответа; `.curl_cffi` —
+`CurlCffiTransport`/`pick_chrome_impersonate`; `.cdp` — `CdpTransport`/
+`SyncCdpTransport` + backend-контракты; `.page_evaluate` — `PageEvaluateTransport`/
+`page_fetch`/`_build_fetch_spec`). Публичный API прежний — все прежние имена
+реэкспортированы.
+
+Опциональные зависимости (`curl_cffi`, `playwright`/`patchright`) импортируются
+ЛЕНИВО — модуль импортируется без них (graceful), а понятная ошибка о
+недостающем пакете возникает только при реальной попытке использовать транспорт.
+
+────────────────────────────────────────────────────────────────────────────────
+Tier 0-4 — какой транспорт выбрать под нагрузку и характер защиты
+────────────────────────────────────────────────────────────────────────────────
+Антибот эскалируется уровнями; не «беги за прокси первым», а подбирай по симптому.
+
+- **Tier 0** — видимый браузер (headed) / обычный httpx. RAM ~800 МБ. dev / debug /
+  первый bootstrap-логин. Здесь: `CdpTransport(headless=False)` / `HttpxTransport`.
+- **Tier 1** — headless реальный браузер (CDP→Edge `--headless=new`), ~700 мс,
+  500-800 МБ; prod 1-100 calls/day, антибот средний. Здесь: `CdpTransport(headless=True)`.
+  Вариант того же уровня — curl-cffi (JA3-имитация Chrome), ~10 МБ: JA3/TLS-детект
+  (Akamai, Google) БЕЗ signing. Здесь: `CurlCffiTransport`.
+- **Tier 2** — jsdom one-shot subprocess, 3-5 с, 30-50 МБ; init-флоу известен,
+  sign-only без рендера. Вне этого модуля.
+- **Tier 3** — jsdom persistent daemon (RPC), ~50 мс, ~80 МБ; prod sweet-spot
+  100-10K calls/day. Вне этого модуля.
+- **Tier 4** — pure native (Python/Go/Rust), ~1 мс, ~10 МБ; bundle pinned forever
+  + есть команда сопровождения. Вне этого модуля.
+
+Дерево решений:
+- read-only без подписи запроса → Tier 0/1 (или официальный REST, если есть);
+- мутирующий вызов с подписью (X-Sign/X-Bogus/_signature/msToken):
+  * bootstrap-логин → `CdpTransport` (реальный Edge ставит нативные
+    `sec-fetch-*` / Client-Hints / TLS — patchright их НЕ шлёт);
+  * массовая prod-нагрузка → Tier 3 jsdom-daemon (вне adapterkit), а Python-сторона
+    шлёт уже подписанный URL через `CurlCffiTransport` (JA3 совпадает).
+
+Симптом → направление (три ОРТОГОНАЛЬНЫХ оси, выбирай по симптому, не «по простоте»):
+- `403`/`Access denied` на любом IP, RU-регион заблокирован → IP/proxy (дорого, last resort);
+- видимый captcha-виджет (hCaptcha/Turnstile) → внешний solver (reCAPTCHA v3 — score-based,
+  solver НЕ работает, только реальный браузер `CdpTransport`);
+- `signatures don't match` / `isTTwidDecryptedFail` / «unusual activity» / нет
+  `sec-fetch-*` → архитектура: `CdpTransport` (реальный Edge);
+- `ECONNRESET` / другой контент на JA3-detection endpoint → архитектура: `CurlCffiTransport`.
+
+Железные правила (анти-паттерны):
+- версию Chrome НЕ пинить: захардкоженный `chrome131` через 4+ версии — сигнал «бот»
+  (`CurlCffiTransport` подбирает свежайший доступный профиль автоматически);
+- UA major == sec-ch-ua major == curl-cffi `impersonate` major — рассинхрон палится;
+- `CdpTransport` берёт версию браузера сам — держи системный Edge/Chrome обновлённым.
+"""
+from __future__ import annotations
+
+from ._helpers import (  # noqa: F401  # seam: тесты/потребители импортируют приватные
+    _as_transport_error,
+    _to_httpx_response,
+)
+from .cdp import (
+    CdpBrowserBackend,
+    CdpTransport,
+    SyncCdpBrowserBackend,
+    SyncCdpTransport,
+)
+from .curl_cffi import CurlCffiTransport, pick_chrome_impersonate
+from .page_evaluate import (
+    PageEvaluateTransport,
+    PageFetchResult,
+    _build_fetch_spec,  # noqa: F401  # seam: browser+тесты импортируют
+    page_fetch,
+    sync_page_fetch,
+)
+from .warmup_minter import TokenHarvest, WarmupTokenMinter
+
+# Первичные ролевые имена исполнителей запроса (роль снаружи, вендор — внутри):
+#   ImpersonatedHttpExecutor  — TLS/JA3-impersonate (curl-cffi) [было CurlCffiTransport];
+#   BrowserRequestExecutor    — запрос «руками браузера» по CDP/CamouFox [было CdpTransport];
+#   BorrowedPageRequestExecutor — запрос в ЗАИМСТВОВАННОЙ странице [было PageEvaluateTransport];
+#   BrowserRequester          — роль «умеет выполнить запрос в браузере» ПОВЕРХ живой
+#                               contract.BrowserSession (fetch, не ЖЦ) [было CdpBrowserBackend].
+# Старые имена остаются deprecated-псевдонимами (ничего не удалено).
+ImpersonatedHttpExecutor = CurlCffiTransport
+BrowserRequestExecutor = CdpTransport
+SyncBrowserRequestExecutor = SyncCdpTransport
+BorrowedPageRequestExecutor = PageEvaluateTransport
+BrowserRequester = CdpBrowserBackend
+SyncBrowserRequester = SyncCdpBrowserBackend
+
+__all__ = [
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "SyncCdpTransport",
+    "SyncCdpBrowserBackend",
+    "PageEvaluateTransport",
+    "PageFetchResult",
+    "page_fetch",
+    "sync_page_fetch",
+    "pick_chrome_impersonate",
+    # warmup-минт одноразовых токенов тёплой страницей (генерик chatgpt-паттерна)
+    "WarmupTokenMinter",
+    "TokenHarvest",
+    # первичные ролевые имена (псевдонимы вендор-классов выше)
+    "ImpersonatedHttpExecutor",
+    "BrowserRequestExecutor",
+    "SyncBrowserRequestExecutor",
+    "BorrowedPageRequestExecutor",
+    "BrowserRequester",
+    "SyncBrowserRequester",
+]

browserkit/antibot/_helpers.py

@@ -0,0 +1,68 @@
+"""Общие хелперы антибот-транспортов: обёртка ошибок + нормализация ответа.
+
+Выделено из god-модуля `antibot.py`. Имена реэкспортируются фасадом
+`librarykit.antibot`; публичный API прежний.
+"""
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+from corekit.errors import TransportError
+
+
+@contextlib.contextmanager
+def _as_transport_error(prefix: str) -> Iterator[None]:
+    """Обернуть сбой backend'а транспорта в `TransportError` с единым префиксом.
+
+    Устраняет повтор ``except Exception → TransportError(f"<prefix>: ...")`` в
+    request-методах транспортов (curl_cffi / CDP / CDP(sync) / page.evaluate).
+    Уже-`TransportError` пробрасывается КАК ЕСТЬ — не заворачиваем дважды (префикс
+    и цепочка причин остаются исходными); прочее исключение backend'а
+    сворачивается в `TransportError` с типом и текстом.
+    """
+    try:
+        yield
+    except TransportError:
+        raise
+    except Exception as exc:
+        raise TransportError(f"{prefix}: {type(exc).__name__}: {exc}") from exc
+
+
+def _to_httpx_response(
+    raw: Any, *, request: httpx.Request, default_encoding: str = "utf-8"
+) -> httpx.Response:
+    """Сконвертировать ответ стороннего backend (curl-cffi) в `httpx.Response`.
+
+    Нормализует разнотипный ответ к единому контракту `Transport`: вышестоящий код
+    (`ErrorMapper`/адаптер) работает только с `httpx.Response`. Тянем status/headers/
+    тело и привязываем реконструированный `httpx.Request` (нужен для url в ошибках).
+    """
+    status = int(getattr(raw, "status_code", 0) or 0)
+    raw_headers = getattr(raw, "headers", None) or {}
+    headers = dict(raw_headers.items()) if hasattr(raw_headers, "items") else dict(raw_headers)
+    # curl-cffi (libcurl) уже РАСПАКОВАЛ тело (Accept-Encoding согласуется при
+    # impersonate), но оставил исходные Content-Encoding/Content-Length. Пробросив
+    # их в httpx.Response с уже-распакованным content, мы заставим httpx
+    # распаковать ПОВТОРНО на .text/.json/.content → `Error -3 while decompressing
+    # data: incorrect header check`. Тело здесь финальное → снимаем эти заголовки.
+    headers = {
+        name: value
+        for name, value in headers.items()
+        if name.lower() not in ("content-encoding", "content-length")
+    }
+    content = getattr(raw, "content", None)
+    if content is None:
+        text = getattr(raw, "text", "") or ""
+        content = text.encode(default_encoding)
+    elif isinstance(content, str):
+        content = content.encode(default_encoding)
+    return httpx.Response(
+        status,
+        headers=headers,
+        content=content,
+        request=request,
+        default_encoding=default_encoding,
+    )