s-librarykit 0.3.0__tar.gz → 0.5.0__tar.gz

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s-librarykit
-Version: 0.3.0
+Version: 0.5.0
 Summary: Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов.
 Author: Dmitry
 License: MIT
@@ -25,6 +25,8 @@ Requires-Dist: hypothesis>=6; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: nodriver
+Requires-Dist: nodriver>=0.50; extra == 'nodriver'
 Provides-Extra: oauth
 Requires-Dist: authlib>=1.3; extra == 'oauth'
 Provides-Extra: ws

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/__init__.py

@@ -22,12 +22,34 @@ from librarykit.auth import (
     CsrfHeaderAuth,
     OAuth2Auth,
     TokenAuth,
+    cookies_with_meta_from_state,
     decrypt_settings,
     dump_settings,
     encrypt_settings,
     extract_token_from_text,
     load_settings,
 )
+from librarykit.cookie_refresh import (
+    COOKIE_REFRESH_META_KEY,
+    CategoryCookieAuth,
+    CategoryPolicy,
+    FreshnessOutcome,
+    LazyRefreshPolicy,
+)
+from librarykit.cookies import (
+    DEFAULT_MINT_NAMES,
+    DEFAULT_SESSION_NAMES,
+    CategoryFreshness,
+    Cookie,
+    CookieCategory,
+    CookieClassifier,
+    assess_freshness,
+    cookies_from_state,
+    earliest_expiry,
+    flat_cookies,
+    merge_state,
+    to_state_cookies,
+)
 from librarykit.blocks import (
     block_end,
     decode_text_block,
@@ -249,161 +271,118 @@ from librarykit.windows import (
     parse_window,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",
-    # checkpoint
-    "Checkpoint",
-    "JsonlSink",
-    "RunMetrics",
-    # errors (единая иерархия ERROR-HUB)
-    "CliError",
-    "ApiError",
-    "AuthRequired",
-    "SessionExpired",
-    "RateLimited",
-    "ValidationError",
-    "NotImplementedYet",
-    "NotFoundError",
-    "ServerError",
-    "TransportError",
-    "Blocked",
-    "RETRYABLE",
-    "AdapterError",
-    "NotFound",
-    "GraphQLError",
-    # config_util / paths
-    "deep_merge",
-    "interpolate_env",
-    "load_dotenv",
-    "slugify",
-    "normalize_account_id",
-    "atomic_write_text",
-    "chmod_600",
-    "AppPaths",
-    # session_paths — единый резолвер браузерных сессий (~/.sessions)
-    "sessions_home",
-    "browser_profile_dir",
-    "shared_google_profile_dir",
-    "make_profile_dir_resolver",
-    "make_session_store",
-    # contract — generic «талия» (Protocol + enums + DTO координат сессии/кредов)
-    "PaginationMode",
-    "AuthMode",
+    # requesting: транспорт-исполнители + режимы/протоколы запроса
     "TransportKind",
     "RequestExecutionMode",
-    "SessionRef",
-    "Creds",
     "RequestBody",
     "ResponseLike",
     "Transport",
     "SyncTransport",
     "HttpRequestExecutor",
     "SyncHttpRequestExecutor",
-    "StreamTransport",
+    "Codec",
+    "make_transport",
+    "register_transport",
+    "create_request_executor",
+    "register_request_provider",
+    "HttpxTransport",
+    "HttpxRequestExecutor",
+    "HttpClient",
+    "RestHttpClient",
+    "HttpxSyncTransport",
+    "HttpxSyncRequestExecutor",
+    "SyncHttpClient",
+    # browser/сессии: ЖЦ браузер-сессии + профили + warmup-минт
     "BrowserBackend",
     "SyncBrowserBackend",
     "BrowserSession",
     "SyncBrowserSession",
-    "Codec",
-    "Auth",
-    # factory — нейтральный выбор транспорта/браузера по роли (Enum → фабрика → реестр)
     "BrowserEngine",
     "BrowserProvider",
     "AutomationDriver",
     "BrowserOptions",
     "BrowserSessionSettings",
-    "make_transport",
-    "register_transport",
-    "create_request_executor",
-    "register_request_provider",
     "make_browser_backend",
     "register_browser_backend",
     "create_browser_session",
     "register_browser_provider",
+    "sessions_home",
+    "browser_profile_dir",
+    "shared_google_profile_dir",
+    "make_profile_dir_resolver",
+    "make_session_store",
+    "WarmupTokenMinter",
+    "TokenHarvest",
+    # auth + refresh: стратегии авторизации + проактивное обновление сессии
+    "AuthMode",
+    "Auth",
     "Refreshable",
     "ProactiveRefreshable",
     "SyncRefreshable",
     "SyncProactiveRefreshable",
-    "ErrorMapper",
-    "Paginator",
+    "TokenAuth",
+    "CookieSessionAuth",
+    "cookies_with_meta_from_state",
+    "CategoryCookieAuth",
+    "CategoryPolicy",
+    "LazyRefreshPolicy",
+    "FreshnessOutcome",
+    "COOKIE_REFRESH_META_KEY",
+    "Cookie",
+    "CookieCategory",
+    "CookieClassifier",
+    "CategoryFreshness",
+    "cookies_from_state",
+    "flat_cookies",
+    "to_state_cookies",
+    "merge_state",
+    "earliest_expiry",
+    "assess_freshness",
+    "DEFAULT_MINT_NAMES",
+    "DEFAULT_SESSION_NAMES",
+    "OAuth2Auth",
+    "BrowserLoginAuth",
+    "CsrfHeaderAuth",
+    "CSRF_DEFAULT_HEADER",
+    "extract_token_from_text",
+    "dump_settings",
+    "load_settings",
+    "encrypt_settings",
+    "decrypt_settings",
+    "RotatingAuth",
+    "Keepalive",
+    "RefreshableChain",
+    "DEFAULT_ROTATE_INTERVAL",
+    # sessions + secrets: envelope-хранилище сессий + креды + keyring-стор
+    "SessionRef",
+    "Creds",
     "SessionStoreProtocol",
-    # contract — квоты/лимиты (generic DTO)
-    "QuotaScope",
-    "QuotaInfo",
-    "LimitSpec",
-    # protocols — онбординг/health контракты (опциональные)
-    "LoginMode",
-    "LoginRequirements",
-    "InteractiveFlow",
-    "OnboardingProtocol",
-    "HealthState",
-    "HealthStatus",
-    "HealthProtocol",
-    # entities (W6) — нейтральные data-классы оркестраторов (почва под W7)
-    "Session",
-    "SessionChanges",
-    "SessionContext",
-    "HealthReport",
-    # secret_store — keyring + file-fallback
-    "SecretStore",
-    # sessions (W4): envelope-шифрованное хранилище сессий (spec §4)
     "SessionStore",
     "SessionStoreError",
     "KekUnavailableError",
     "resolve_kek",
-    # transport (W4): конкретный httpx-транспорт + choke-point клиент
-    "HttpxTransport",
-    "HttpxRequestExecutor",
-    "HttpClient",
-    "RestHttpClient",
-    # transport sync-сиблинги (для навыков без event-loop)
-    "HttpxSyncTransport",
-    "HttpxSyncRequestExecutor",
-    "SyncHttpClient",
-    # forms (W8): кодек form-urlencoded тел с nested-JSON полями
-    "FormCodec",
-    # graphql (W8): GENERIC GraphQL-клиент поверх RestHttpClient/HttpClient
-    "GraphQLClient",
-    # upload (W8): GENERIC resumable chunked uploader
-    "ChunkedUploader",
-    "UploadResult",
-    # blocks (W8): GENERIC draft.js richtext block-хелперы
-    "blocks",
-    "text_block",
-    "block_end",
-    "header_block",
-    "list_item_block",
-    "paragraphs",
-    "decode_text_block",
-    # limit: проактивный конфигуратор троттлинга / rate-limit по scope
-    "LimitWindow",
-    "LimitPolicy",
-    "LimitScope",
-    "RateLimiter",
-    # windows: обобщённые ОКНА лимитов (rolling/calendar/fixed) + фабрика
-    "Window",
-    "RollingWindow",
-    "CalendarWindow",
-    "FixedWindow",
-    "parse_window",
-    # antibot: warmup-минт одноразовых токенов тёплой страницей (генерик)
-    "WarmupTokenMinter",
-    "TokenHarvest",
-    # pool: балансер N аккаунтов одного сервиса (селектор поверх SessionStore)
-    "SessionPool",
-    "PoolChoice",
-    "DEFAULT_SKIP_STATUSES",
-    # rpc (E1): codec-слой + RPC choke-point поверх HttpClient
-    "JsonCodec",
-    "PrefixedJsonCodec",
-    "RpcClient",
-    # stream (E1): WS-подобные persistent-транспорты (Stub + websockets reference)
-    "StubStreamTransport",
-    "WebSocketsStreamTransport",
-    "StreamClosedError",
-    # errmap (W4): декларативная карта HTTP-ответ → доменная ошибка
+    "SecretStore",
+    # errors + errmap: единая иерархия ERROR-HUB + карта ответ→ошибка
+    "CliError",
+    "ApiError",
+    "AuthRequired",
+    "SessionExpired",
+    "RateLimited",
+    "ValidationError",
+    "NotImplementedYet",
+    "NotFoundError",
+    "ServerError",
+    "TransportError",
+    "Blocked",
+    "RETRYABLE",
+    "AdapterError",
+    "NotFound",
+    "GraphQLError",
+    "ErrorMapper",
     "ErrorMap",
     "ErrorMapBuilder",
     "BodyRule",
@@ -411,7 +390,27 @@ __all__ = [
     "AuthExpired",
     "build_error_map",
     "DEFAULT_ERROR_MAP",
-    # pagination (W4): листатель ресурса (offset/cursor/page) tweepy-стиля
+    # reliability: retry / limit / pool / checkpoint
+    "RetryPolicy",
+    "DEFAULT_RETRY",
+    "SimpleRetryPolicy",
+    "DEFAULT_SIMPLE_RETRY",
+    "LimitWindow",
+    "LimitPolicy",
+    "LimitScope",
+    "RateLimiter",
+    "LimitSpec",
+    "QuotaScope",
+    "QuotaInfo",
+    "SessionPool",
+    "PoolChoice",
+    "DEFAULT_SKIP_STATUSES",
+    "Checkpoint",
+    "JsonlSink",
+    "RunMetrics",
+    # pagination / bulk / upload: листание ресурса + батчи + resumable-догрузка
+    "PaginationMode",
+    "Paginator",
     "CursorPaginator",
     "PageParams",
     "DEFAULT_PAGE_PARAMS",
@@ -420,40 +419,52 @@ __all__ = [
     "default_extract_items",
     "default_extract_cursor",
     "with_page_params",
-    # pagination flat-page (W8): offset/total на верхнем уровне тела
     "FlatPage",
     "parse_flat_page",
     "next_flat_offset",
-    # auth (W4): стратегии авторизации + персистентность сессии
-    "TokenAuth",
-    "CookieSessionAuth",
-    "OAuth2Auth",
-    "BrowserLoginAuth",
-    "CsrfHeaderAuth",
-    "CSRF_DEFAULT_HEADER",
-    "extract_token_from_text",
-    "dump_settings",
-    "load_settings",
-    "encrypt_settings",
-    "decrypt_settings",
-    # refresh: проактивное обновление ротируемой сессии + keepalive + fallback
-    "RotatingAuth",
-    "Keepalive",
-    "RefreshableChain",
-    "DEFAULT_ROTATE_INTERVAL",
-    # retry
-    "RetryPolicy",
-    "DEFAULT_RETRY",
-    "SimpleRetryPolicy",
-    "DEFAULT_SIMPLE_RETRY",
-    # bulk: движок батч-операций над набором id (per-item outcome, не роняет батч)
     "BulkOutcome",
     "BulkOperationError",
     "BulkError",
     "BulkOperationResult",
     "run_bulk",
     "run_bulk_async",
-    # redaction: маски секретов + truncation для HTTP-заголовков/body (audit/логи)
+    "ChunkedUploader",
+    "UploadResult",
+    # orchestration / protocols / entities: онбординг/health + нейтральные data-классы
+    "LoginMode",
+    "LoginRequirements",
+    "InteractiveFlow",
+    "OnboardingProtocol",
+    "HealthState",
+    "HealthStatus",
+    "HealthProtocol",
+    "Session",
+    "SessionChanges",
+    "SessionContext",
+    "HealthReport",
+    # rpc / stream / graphql: codec-слой + persistent-транспорты + GraphQL-клиент
+    "StreamTransport",
+    "JsonCodec",
+    "PrefixedJsonCodec",
+    "RpcClient",
+    "StubStreamTransport",
+    "WebSocketsStreamTransport",
+    "StreamClosedError",
+    "GraphQLClient",
+    # blocks / forms / windows / redaction / config: примитивы тел, окна, маски, утили путей
+    "blocks",
+    "text_block",
+    "block_end",
+    "header_block",
+    "list_item_block",
+    "paragraphs",
+    "decode_text_block",
+    "FormCodec",
+    "Window",
+    "RollingWindow",
+    "CalendarWindow",
+    "FixedWindow",
+    "parse_window",
     "SECRET_MASK",
     "HEADER_BLACKLIST",
     "BODY_FIELD_PATTERNS",
@@ -461,4 +472,12 @@ __all__ = [
     "sanitize_body",
     "truncate_body",
     "excerpt_response_body",
+    "deep_merge",
+    "interpolate_env",
+    "load_dotenv",
+    "slugify",
+    "normalize_account_id",
+    "atomic_write_text",
+    "chmod_600",
+    "AppPaths",
 ]

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/antibot/__init__.py

@@ -97,7 +97,8 @@ from .warmup_minter import TokenHarvest, WarmupTokenMinter
 #   ImpersonatedHttpExecutor  — TLS/JA3-impersonate (curl-cffi) [было CurlCffiTransport];
 #   BrowserRequestExecutor    — запрос «руками браузера» по CDP/CamouFox [было CdpTransport];
 #   BorrowedPageRequestExecutor — запрос в ЗАИМСТВОВАННОЙ странице [было PageEvaluateTransport];
-#   BrowserRequester          — роль «умеет выполнить запрос в браузере» [было CdpBrowserBackend].
+#   BrowserRequester          — роль «умеет выполнить запрос в браузере» ПОВЕРХ живой
+#                               contract.BrowserSession (fetch, не ЖЦ) [было CdpBrowserBackend].
 # Старые имена остаются deprecated-псевдонимами (ничего не удалено).
 ImpersonatedHttpExecutor = CurlCffiTransport
 BrowserRequestExecutor = CdpTransport

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/antibot/cdp.py

@@ -23,12 +23,28 @@ from ._helpers import _as_transport_error, _to_httpx_response
 
 @runtime_checkable
 class CdpBrowserBackend(Protocol):
-    """Контракт «движка реального браузера» под `CdpTransport` (точка DI).
+    """Контракт «умеет ВЫПОЛНИТЬ запрос в браузере» (роль `BrowserRequester`), под
+    `CdpTransport` (точка DI).
 
     Скрывает за собой запуск системного Edge/Chrome с `--remote-debugging-port`
     и `connect_over_cdp` (см. recipes/antibot `cdp_real_browser.py`). Реализация —
     в `librarykit.browser` (Playwright/patchright); здесь — только контракт, чтобы
     `antibot` не тащил тяжёлый browser-стек и тестировался фейком той же формы.
+
+    Разделение с `librarykit.contract.BrowserSession` (= `BrowserBackend`) — это
+    ДВЕ РАЗНЫЕ роли, а не одна:
+
+    - `BrowserSession` — ЖИЗНЕННЫЙ ЦИКЛ живой сессии: поднять/держать/закрыть
+      браузер и отдать страницу с контекстом (`ensure_page`/`context`/`aclose`);
+    - `CdpBrowserBackend` (`BrowserRequester`) — СПОСОБНОСТЬ выполнить HTTP-запрос
+      руками уже живой сессии (`fetch`), поверх её страницы/контекста.
+
+    Как Protocol'ы они пересекаются лишь по `aclose()`; ни один не является
+    структурным подтипом другого (у Requester нет `ensure_page`/`context`, у
+    Session нет `fetch`). Конкретные бэкенды `librarykit.browser`
+    (`CdpChromeBackend`/`CamoufoxBackend`) реализуют ОБА контракта одним объектом:
+    он И держит живую сессию, И умеет `fetch` поверх неё — то есть
+    `BrowserRequester` НАДСТРАИВАЕТ исполнение запроса над сессией, не заменяя её.
     """
 
     async def fetch(
@@ -174,11 +190,17 @@ class CdpTransport(Transport):
 
 @runtime_checkable
 class SyncCdpBrowserBackend(Protocol):
-    """Sync-сиблинг `CdpBrowserBackend`: движок реального/stealth-браузера БЕЗ await.
+    """Sync-сиблинг `CdpBrowserBackend`: роль `SyncBrowserRequester` БЕЗ await.
 
-    Та же роль (выполнить запрос внутри живого браузера, вернуть ответоподобный
+    Та же роль «умеет ВЫПОЛНИТЬ запрос в браузере» (`fetch` → ответоподобный
     объект под `_to_httpx_response`), но синхронная сигнатура — для навыков без
     event-loop. Реализация — `librarykit.browser.SyncCamoufoxBackend`.
+
+    То же разделение, что у async-версии: это СПОСОБНОСТЬ исполнить запрос поверх
+    живой сессии, а не её жизненный цикл — ЖЦ (поднять/держать/закрыть, страница+
+    контекст) несёт `librarykit.contract.SyncBrowserSession` (= `SyncBrowserBackend`,
+    `ensure_page`/`context`). Пересечение Protocol'ов — только семантика закрытия;
+    конкретный sync-бэкенд реализует обе роли одним объектом.
     """
 
     def fetch(

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/auth.py

@@ -121,6 +121,17 @@ def _cookies_from_state(state: Mapping[str, Any]) -> dict[str, str]:
     return {str(k): str(v) for k, v in flat.items() if k != "origins"}
 
 
+def cookies_with_meta_from_state(state: Mapping[str, Any]) -> list[Any]:
+    """Как `_cookies_from_state`, но СОХРАНЯЕТ domain/expires/категорию (`list[cookies.Cookie]`).
+
+    Аддитивный сосед: `_cookies_from_state`/`CookieSessionAuth` теряют срок и не
+    категоризируют — здесь нужно для ленивого TTL-обновления (`cookie_refresh`).
+    """
+    from .cookies import cookies_from_state
+
+    return cookies_from_state(state)
+
+
 class CookieSessionAuth:
     """Cookie-сессия: cookies из `storage_state` → заголовок ``Cookie`` (`AuthMode.COOKIE`).
 

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/browser/__init__.py

@@ -55,9 +55,23 @@ from ._engine import (
     _load_async_playwright,
     _resolve_patchright,
     camoufox_available,
+    nodriver_available,
     playwright_available,
 )
 from .camoufox import CamoufoxBackend, SyncCamoufoxBackend
+from .nodriver import NodriverBackend
+from .persistent import PersistentChromiumBackend
+from .capture_tap import (
+    CAPTURE_ENGINES,
+    NormalizedAction,
+    NormalizedFailure,
+    NormalizedRequest,
+    NormalizedResponse,
+    NormalizedWsFrame,
+    TapHandle,
+    attach_capture_tap,
+    build_capture_backend,
+)
 from .geometry import (
     DEFAULT_ANTI_BOT_ARGS,
     detect_work_area,
@@ -807,7 +821,20 @@ __all__ = [
     "CamoufoxBackend",
     "SyncCamoufoxBackend",
     "camoufox_available",
+    "NodriverBackend",
+    "nodriver_available",
+    "PersistentChromiumBackend",
     "CdpChromeBackend",
+    # capture_tap: нормализованный event-tap над любым движком
+    "attach_capture_tap",
+    "build_capture_backend",
+    "CAPTURE_ENGINES",
+    "TapHandle",
+    "NormalizedRequest",
+    "NormalizedResponse",
+    "NormalizedFailure",
+    "NormalizedWsFrame",
+    "NormalizedAction",
     "detect_work_area",
     "find_chrome_exe",
     "is_session_dead",

{s_librarykit-0.3.0 → s_librarykit-0.5.0}/librarykit/browser/_engine.py

@@ -54,6 +54,17 @@ def camoufox_available() -> bool:
     return importlib.util.find_spec("camoufox") is not None
 
 
+def nodriver_available() -> bool:
+    """Установлен ли nodriver (undetected Chromium) — без его запуска.
+
+    Для `skipif` в тестах и выбора движка (nodriver против CDP-Chrome/CamouFox)
+    без побочных эффектов. Extra `[nodriver]`; браузер Chromium nodriver тянет сам.
+    """
+    import importlib.util
+
+    return importlib.util.find_spec("nodriver") is not None
+
+
 # Сентинел «легаси-параметр не передан явно»: отличает дефолт от осознанного
 # `use_patchright=...`, чтобы DeprecationWarning вылезал ТОЛЬКО на явную передачу.
 _LEGACY_UNSET: Any = object()