s-adapterkit 0.1.1__py3-none-any.whl

adapterkit/__init__.py

@@ -0,0 +1,293 @@
+"""adapterkit — переиспользуемый SDK сетевых адаптеров (поверх clikit).
+
+Сетевой слой, который пишется один раз и потребляется всеми адаптерами
+`bublictr` и `reverse-factory`: транспорт + retry + auth + session + antibot,
+декларативный контракт плагинов (`typing.Protocol` + `ADAPTER_API_VERSION`) и
+базовый фасад адаптера. adapterkit зависит ТОЛЬКО от `clikit` (и стандартных
+сетевых библиотек) — без импортов домена, чтобы reverse-factory брал тот же SDK.
+
+Публичный API сгруппирован по слоям (как в `clikit.__init__`): ошибки → контракт
+→ retry → transport → client → auth → errmap → pagination → sessions → base →
+registry → antibot. Браузерный слой (`adapterkit.browser`) тащит опциональный
+Playwright и здесь НЕ ре-экспортируется на верхний уровень — импортируется явно
+из подмодуля (``from adapterkit.browser import maximized_chromium``), чтобы
+верхнеуровневый импорт пакета не зависел от extra `browser`.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.1"
+
+# Импорты сгруппированы по слоям, но отсортированы по алфавиту (isort/ruff):
+# заголовки-комментарии ниже маркируют слой каждого подмодуля, а __all__ в конце
+# держит исходную смысловую группировку (ошибки → контракт → транспорт → ...).
+
+# --------------------------------------------------------------------------- #
+# antibot — выбор транспорта (curl-cffi JA3 / реальный браузер по CDP)          #
+# --------------------------------------------------------------------------- #
+from adapterkit.antibot import (
+    CdpBrowserBackend,
+    CdpTransport,
+    CurlCffiTransport,
+    pick_chrome_impersonate,
+)
+
+# --------------------------------------------------------------------------- #
+# auth — стратегии авторизации + персистентность сессии                        #
+# --------------------------------------------------------------------------- #
+from adapterkit.auth import (
+    BrowserLoginAuth,
+    CookieSessionAuth,
+    OAuth2Auth,
+    TokenAuth,
+    decrypt_settings,
+    dump_settings,
+    encrypt_settings,
+    load_settings,
+)
+
+# --------------------------------------------------------------------------- #
+# base — базовый адаптер + ресурс-под-сервисы (Stripe-фасад)                    #
+# --------------------------------------------------------------------------- #
+from adapterkit.base import (
+    BaseAdapter,
+    CommentsResource,
+    ContentResource,
+    HttpClientLike,
+    MetricsResource,
+    Resource,
+    SearchResource,
+)
+
+# --------------------------------------------------------------------------- #
+# client — единый choke-point HTTP-вызовов                                     #
+# --------------------------------------------------------------------------- #
+from adapterkit.client import HttpClient
+
+# --------------------------------------------------------------------------- #
+# contract — Protocol-«талия» + версии контракта + DTO/enum                    #
+# --------------------------------------------------------------------------- #
+from adapterkit.contract import (
+    ADAPTER_API_VERSION,
+    MIN_SUPPORTED_API_VERSION,
+    Auth,
+    AuthMode,
+    Creds,
+    Endpoint,
+    ErrorMapper,
+    NetworkAdapter,
+    PaginationMode,
+    Paginator,
+    Refreshable,
+    SessionRef,
+    SessionStoreProtocol,
+    Transport,
+    TransportKind,
+)
+
+# --------------------------------------------------------------------------- #
+# errmap — декларативный маппинг ответа в доменную ошибку                       #
+# --------------------------------------------------------------------------- #
+from adapterkit.errmap import (
+    DEFAULT_ERROR_MAP,
+    AuthExpired,
+    BodyRule,
+    ErrorMap,
+    ErrorMapBuilder,
+    ExcFactory,
+    build_error_map,
+)
+
+# --------------------------------------------------------------------------- #
+# errors — единая иерархия (реэкспорт clikit + сетевые подклассы)              #
+# --------------------------------------------------------------------------- #
+from adapterkit.errors import (
+    RETRYABLE,
+    AdapterError,
+    AuthRequired,
+    Blocked,
+    CliError,
+    NotFound,
+    RateLimited,
+    ServerError,
+    SessionExpired,
+    TransportError,
+    ValidationError,
+)
+
+# --------------------------------------------------------------------------- #
+# onboarding_contract — опциональные онбординг/health-контракты (api_version 2) #
+# --------------------------------------------------------------------------- #
+from adapterkit.onboarding_contract import (
+    HealthProtocol,
+    HealthState,
+    HealthStatus,
+    InteractiveFlow,
+    LoginMode,
+    LoginRequirements,
+    OnboardingProtocol,
+)
+
+# --------------------------------------------------------------------------- #
+# orchestration_api — тонкий registry-driven API онбординга/health (W5)         #
+# --------------------------------------------------------------------------- #
+from adapterkit.orchestration_api import (
+    OnboardReport,
+    OnboardResult,
+    health_check_all,
+    onboard_all,
+)
+
+# --------------------------------------------------------------------------- #
+# pagination — три стратегии листания + tweepy-обёртки                          #
+# --------------------------------------------------------------------------- #
+from adapterkit.pagination import (
+    DEFAULT_PAGE_PARAMS,
+    CursorExtractor,
+    CursorPaginator,
+    ItemsExtractor,
+    PageParams,
+    default_extract_cursor,
+    default_extract_items,
+    with_page_params,
+)
+
+# --------------------------------------------------------------------------- #
+# registry — discovery плагинов + ручная регистрация                           #
+# --------------------------------------------------------------------------- #
+from adapterkit.registry import (
+    ENTRY_POINT_GROUP,
+    AdapterClass,
+    AdapterRegistry,
+    default_registry,
+    discover_adapters,
+    get_adapter_class,
+    get_health_adapters,
+    get_onboarding_adapters,
+    register_adapter,
+)
+
+# --------------------------------------------------------------------------- #
+# retry — header-driven политика повторов                                      #
+# --------------------------------------------------------------------------- #
+from adapterkit.retry import DEFAULT_RETRY, RetryPolicy
+
+# --------------------------------------------------------------------------- #
+# sessions — единое хранилище сессий (каталог + SQLite-индекс)                  #
+# --------------------------------------------------------------------------- #
+from adapterkit.sessions import (
+    KekUnavailableError,
+    SessionStore,
+    SessionStoreError,
+    resolve_kek,
+)
+
+# --------------------------------------------------------------------------- #
+# transport — конкретный httpx-транспорт                                       #
+# --------------------------------------------------------------------------- #
+from adapterkit.transport import HttpxTransport
+
+__all__ = [
+    "__version__",
+    # errors (единая иерархия поверх clikit)
+    "CliError",
+    "AuthRequired",
+    "SessionExpired",
+    "RateLimited",
+    "ValidationError",
+    "AdapterError",
+    "TransportError",
+    "NotFound",
+    "Blocked",
+    "ServerError",
+    "RETRYABLE",
+    # contract: версии + Protocol-«талия» + DTO/enum
+    "ADAPTER_API_VERSION",
+    "MIN_SUPPORTED_API_VERSION",
+    "Transport",
+    "Auth",
+    "Refreshable",
+    "ErrorMapper",
+    "Paginator",
+    "SessionStoreProtocol",
+    "NetworkAdapter",
+    "Endpoint",
+    "SessionRef",
+    "Creds",
+    "PaginationMode",
+    "AuthMode",
+    "TransportKind",
+    # onboarding/health контракты (api_version 2, опциональные)
+    "LoginMode",
+    "LoginRequirements",
+    "InteractiveFlow",
+    "OnboardingProtocol",
+    "HealthState",
+    "HealthStatus",
+    "HealthProtocol",
+    # retry
+    "RetryPolicy",
+    "DEFAULT_RETRY",
+    # transport
+    "HttpxTransport",
+    # client (choke-point)
+    "HttpClient",
+    # auth: стратегии + персистентность сессии
+    "TokenAuth",
+    "CookieSessionAuth",
+    "OAuth2Auth",
+    "BrowserLoginAuth",
+    "dump_settings",
+    "load_settings",
+    "encrypt_settings",
+    "decrypt_settings",
+    # errmap
+    "ErrorMap",
+    "ErrorMapBuilder",
+    "BodyRule",
+    "ExcFactory",
+    "AuthExpired",
+    "build_error_map",
+    "DEFAULT_ERROR_MAP",
+    # pagination
+    "CursorPaginator",
+    "PageParams",
+    "DEFAULT_PAGE_PARAMS",
+    "ItemsExtractor",
+    "CursorExtractor",
+    "default_extract_items",
+    "default_extract_cursor",
+    "with_page_params",
+    # sessions
+    "SessionStore",
+    "SessionStoreError",
+    "KekUnavailableError",
+    "resolve_kek",
+    # base (адаптер + ресурсы)
+    "BaseAdapter",
+    "Resource",
+    "ContentResource",
+    "CommentsResource",
+    "MetricsResource",
+    "SearchResource",
+    "HttpClientLike",
+    # registry
+    "AdapterRegistry",
+    "AdapterClass",
+    "ENTRY_POINT_GROUP",
+    "default_registry",
+    "register_adapter",
+    "get_adapter_class",
+    "discover_adapters",
+    "get_onboarding_adapters",
+    "get_health_adapters",
+    # orchestration_api (тонкий registry-driven онбординг/health поверх librarykit)
+    "onboard_all",
+    "health_check_all",
+    "OnboardResult",
+    "OnboardReport",
+    # antibot (выбор транспорта)
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "pick_chrome_impersonate",
+]

adapterkit/antibot.py

@@ -0,0 +1,27 @@
+"""Антибот-транспорты adapterkit — ТОНКИЙ реэкспорт из ``librarykit.antibot``.
+
+Выбор транспорта под сложность антибота (``CurlCffiTransport`` — JA3-имитация
+Chrome через curl-cffi; ``CdpTransport`` + ``CdpBrowserBackend`` — реальный
+браузер по CDP; ``pick_chrome_impersonate`` — подбор impersonate-профиля) переехал
+в жирный КОРЕНЬ ``librarykit.antibot`` (граф ``librarykit <- adapterkit <-
+clikit``). Здесь — тонкий реэкспорт ради back-compat: ``from adapterkit.antibot
+import CurlCffiTransport`` работает идентично.
+
+curl-cffi — опциональный extra (``antibot``), импортируется ЛЕНИВО внутри
+транспорта: импорт самого модуля не требует extra.
+"""
+from __future__ import annotations
+
+from librarykit.antibot import (
+    CdpBrowserBackend,
+    CdpTransport,
+    CurlCffiTransport,
+    pick_chrome_impersonate,
+)
+
+__all__ = [
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "pick_chrome_impersonate",
+]

adapterkit/auth.py

@@ -0,0 +1,42 @@
+"""Стратегии авторизации adapterkit — ТОНКИЙ реэкспорт из ``librarykit.auth``.
+
+Реализации ``contract.Auth`` (``TokenAuth`` / ``CookieSessionAuth`` / ``OAuth2Auth``
+/ ``BrowserLoginAuth``) и хелперы персистентности сессии (``dump_settings`` /
+``load_settings`` / ``encrypt_settings`` / ``decrypt_settings``) переехали в жирный
+КОРЕНЬ ``librarykit.auth`` (граф ``librarykit <- adapterkit <- clikit``). Здесь —
+тонкий реэкспорт ради back-compat: ``from adapterkit.auth import TokenAuth,
+dump_settings`` работает идентично.
+
+Внутренние ленивые загрузчики ``_require_authlib`` / ``_load_fernet`` тоже
+реэкспортируются — это исторические monkeypatch-таргеты тестов. ВНИМАНИЕ: их
+``OAuth2Auth._ensure_client`` / ``encrypt_settings`` резолвят по module-global в
+``librarykit.auth``, поэтому подмену для эффекта делать на ``librarykit.auth``,
+а не на этом shim'е.
+"""
+from __future__ import annotations
+
+from librarykit.auth import (
+    BrowserLoginAuth,
+    CookieSessionAuth,
+    OAuth2Auth,
+    TokenAuth,
+    _load_fernet,  # noqa: F401  # исторический monkeypatch-таргет
+    _require_authlib,  # noqa: F401  # исторический monkeypatch-таргет
+    decrypt_settings,
+    dump_settings,
+    encrypt_settings,
+    load_settings,
+)
+
+__all__ = [
+    # стратегии Auth
+    "TokenAuth",
+    "CookieSessionAuth",
+    "OAuth2Auth",
+    "BrowserLoginAuth",
+    # персистентность сессии
+    "dump_settings",
+    "load_settings",
+    "encrypt_settings",
+    "decrypt_settings",
+]