dawg-replay-kit 1.1.3__tar.gz

dawg_replay_kit-1.1.3/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/

dawg_replay_kit-1.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dawgswarm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dawg_replay_kit-1.1.3/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: dawg-replay-kit
+Version: 1.1.3
+Summary: Библиотека для скриптов dawg-replay: параметры, события, браузеры DAWG
+Project-URL: Homepage, https://dawgswarm.ru
+Project-URL: Source, https://github.com/dawgswarm/dawg-replay
+Project-URL: Issues, https://github.com/dawgswarm/dawg-replay/issues
+Author: dawgswarm
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2; python_version < '3.11'
+Provides-Extra: browser
+Requires-Dist: dawg-sdk-python<0.5,>=0.4; extra == 'browser'
+Requires-Dist: httpx>=0.27; extra == 'browser'
+Requires-Dist: playwright<2,>=1.58; extra == 'browser'
+Description-Content-Type: text/markdown
+
+# dawg-replay-kit
+
+Библиотека для скриптов приложения [dawg-replay](https://pypi.org/project/dawg-replay/): параметры запуска, события прогресса и результата, облачные браузеры DAWG, которые закрываются при выходе, ошибке и отмене.
+
+Пакет нужен тем, кто пишет скрипты для dawg-replay. Обычно это кодинг-агент со скиллом dawg-replay-builder, руками ставить пакет не нужно: скрипт объявляет его в заголовке PEP 723, и `uv run` подтягивает его сам.
+
+```python
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["dawg-replay-kit>=1.1,<2"]
+# ///
+import dawg_replay_kit as kit
+
+kit.stage("Сбор")
+kit.progress("pages", "Страницы", 1, 5)
+kit.result("ok", "собрано 120 карточек")
+```
+
+Мажорная версия kit совпадает с мажорной версией контракта скрипта. Контракт (манифест, типы параметров, события, окружение запуска): https://github.com/dawgswarm/dawg-replay/blob/main/docs/contract.md
+
+Лицензия MIT.

dawg_replay_kit-1.1.3/README.md

@@ -0,0 +1,21 @@
+# dawg-replay-kit
+
+Библиотека для скриптов приложения [dawg-replay](https://pypi.org/project/dawg-replay/): параметры запуска, события прогресса и результата, облачные браузеры DAWG, которые закрываются при выходе, ошибке и отмене.
+
+Пакет нужен тем, кто пишет скрипты для dawg-replay. Обычно это кодинг-агент со скиллом dawg-replay-builder, руками ставить пакет не нужно: скрипт объявляет его в заголовке PEP 723, и `uv run` подтягивает его сам.
+
+```python
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["dawg-replay-kit>=1.1,<2"]
+# ///
+import dawg_replay_kit as kit
+
+kit.stage("Сбор")
+kit.progress("pages", "Страницы", 1, 5)
+kit.result("ok", "собрано 120 карточек")
+```
+
+Мажорная версия kit совпадает с мажорной версией контракта скрипта. Контракт (манифест, типы параметров, события, окружение запуска): https://github.com/dawgswarm/dawg-replay/blob/main/docs/contract.md
+
+Лицензия MIT.

dawg_replay_kit-1.1.3/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "dawg-replay-kit"
+dynamic = ["version"]
+description = "Библиотека для скриптов dawg-replay: параметры, события, браузеры DAWG"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "dawgswarm" }]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = ["tomli>=2; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://dawgswarm.ru"
+Source = "https://github.com/dawgswarm/dawg-replay"
+Issues = "https://github.com/dawgswarm/dawg-replay/issues"
+
+[project.optional-dependencies]
+# Для kit.browser(). В скриптах эти пакеты и так перечислены в заголовке PEP 723.
+browser = ["dawg-sdk-python>=0.4,<0.5", "playwright>=1.58,<2", "httpx>=0.27"]
+
+[tool.hatch.version]
+# Единственное место версии: __version__ в пакете. Мажор kit совпадает с мажором контракта.
+path = "src/dawg_replay_kit/__init__.py"
+
+[tool.uv]
+# Версия динамическая (__version__ в __init__.py), а uv по умолчанию пересобирает пакет только
+# при изменении pyproject.toml. Без этого ключа uv sync и uv run оставляют старую версию kit.
+# Ключи заменяют набор uv по умолчанию, поэтому pyproject.toml указан явно.
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/dawg_replay_kit/__init__.py" }]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

dawg_replay_kit-1.1.3/src/dawg_replay_kit/__init__.py

@@ -0,0 +1,141 @@
+"""dawg-replay-kit: библиотека для скриптов dawg-replay.
+
+    import dawg_replay_kit as kit
+
+    kit.stage("Поиск")
+    for page in range(1, kit.params.max_pages + 1):
+        ...
+        kit.progress("pages", "Страницы", page, kit.params.max_pages)
+    kit.result("ok", "Собрано 120 карточек")
+
+Окружение читается при первом обращении к kit: манифест из файла скрипта,
+параметры из `DAWG_SCRIPT_PARAMS` или из аргументов командной строки.
+Если параметры не подходят, скрипт завершается с кодом 2 и объяснением в stderr.
+
+При импорте kit переводит stdout и stderr в UTF-8: на Windows вывод в файл
+иначе идёт в кодировке локали, и кириллица в print ломает скрипт.
+
+При инициализации kit ставит обработчик SIGTERM (на Windows ещё CTRL_BREAK)
+и следит за файлом остановки из `DAWG_SCRIPT_STOP_FILE`: отмена запуска из
+приложения превращается в SystemExit(143), поэтому `finally` и `atexit`
+срабатывают, а отложенные события дописываются в файл.
+"""
+
+from __future__ import annotations
+
+import atexit
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from dawg_replay_kit import cancel, stdio
+from dawg_replay_kit.browser import BrowserLimitReached, BrowserSession
+from dawg_replay_kit.dawg_api import BrowserError, BrowserLimitError
+from dawg_replay_kit.events import Log
+from dawg_replay_kit.manifest import SUPPORTED_CONTRACTS
+from dawg_replay_kit.runtime import EXIT_BAD_PARAMS, Kit, StartupError
+
+__version__ = "1.1.3"  # мажор равен мажору контракта; версия задаётся только здесь
+
+__all__ = [
+    "SUPPORTED_CONTRACTS",
+    "BrowserError",
+    "BrowserLimitError",
+    "BrowserLimitReached",
+    "BrowserSession",
+    "Kit",
+    "StartupError",
+    "__version__",
+    "artifact",
+    "browser",
+    "init",
+    "log",
+    "metric",
+    "progress",
+    "result",
+    "rows",
+    "set_browser_limit",
+    "stage",
+]
+
+stdio.use_utf8()
+
+_kit: Kit | None = None
+_lock = threading.Lock()
+
+
+def init(**kwargs: Any) -> Kit:
+    """Явная инициализация. Обычно не нужна: kit поднимается при первом обращении.
+
+    Аргументы те же, что у `Kit.from_environment`. Ошибку старта kit печатает
+    в stderr и завершает процесс с кодом 2.
+    """
+    global _kit
+    with _lock:
+        if _kit is None:
+            try:
+                _kit = Kit.from_environment(**kwargs)
+            except StartupError as e:
+                print(f"dawg-replay-kit: {e}", file=sys.stderr, flush=True)
+                raise SystemExit(EXIT_BAD_PARAMS) from None
+            atexit.register(_kit.close)
+            # Сигнал отмены и файл остановки превращаются в SystemExit: finally и atexit успевают отработать.
+            cancel.install()
+        return _kit
+
+
+def _runtime() -> Kit:
+    return _kit if _kit is not None else init()
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("params", "output_dir", "run_id", "autonomous"):
+        return getattr(_runtime(), name)
+    raise AttributeError(f"module 'dawg_replay_kit' has no attribute {name!r}")
+
+
+log = Log(lambda: _runtime().events)
+
+
+def stage(name: str) -> None:
+    _runtime().events.stage(name)
+
+
+def progress(id: str, label: str, done: int | float, total: int | float | None = None) -> None:
+    _runtime().events.progress(id, label, done, total)
+
+
+def metric(key: str, label: str, value: int | float | str, unit: str | None = None) -> None:
+    _runtime().events.metric(key, label, value, unit)
+
+
+def rows(table: str, rows: Any, columns: Any = None) -> None:
+    _runtime().events.rows(table, rows, columns)
+
+
+def artifact(path: str | Path, label: str, mime: str | None = None) -> None:
+    _runtime().events.artifact(path, label, mime)
+
+
+def result(status: str, summary: str) -> None:
+    _runtime().events.result(status, summary)
+
+
+def browser(
+    proxy: str | None = None,
+    geo: str | tuple[float, float] | None = None,
+    ready_timeout: float = 120.0,
+) -> BrowserSession:
+    """Браузер DAWG для `with` или `async with`.
+
+    proxy: `socks5://user:pass@host:port` и подобное; geo: slug города (`moskva`)
+    или координаты `"55.75,37.61"`. Внутри доступны `.page`, `.context`, `.browser`,
+    `.session_id`.
+    """
+    return BrowserSession(_runtime().browsers, proxy, geo, ready_timeout)
+
+
+def set_browser_limit(n: int) -> None:
+    """Сколько браузеров скрипт держит одновременно. По умолчанию 1."""
+    _runtime().browsers.set_limit(n)

dawg_replay_kit-1.1.3/src/dawg_replay_kit/browser.py

@@ -0,0 +1,378 @@
+"""`kit.browser()`: облачный Chromium DAWG через Playwright по CDP (docs/contract.md, раздел 6).
+
+    with kit.browser(geo="moskva") as b:
+        b.page.goto("https://www.ozon.ru")
+
+    async with kit.browser() as b:
+        await b.page.goto("https://www.ozon.ru")
+
+Порядок событий `session`:
+
+- `provisioning` до запроса на создание;
+- `open` с `session_id` сразу после ответа на POST, до ожидания готовности;
+- `close` после освобождения, когда сессии больше нет в списке ключа;
+- `failed`, если платформа ответила ошибкой и браузер точно не создан.
+
+Браузер освобождается при выходе из `with`, при исключении, по сигналу отмены
+(kit превращает его в SystemExit) и при выходе из процесса (atexit). Если процесс
+убит жёстко, браузер освобождает приложение по событиям `open` без `close`.
+
+Сколько браузеров одновременно держит скрипт, задаётся явно:
+`kit.set_browser_limit(n)`, по умолчанию 1. Превышение даёт ошибку сразу,
+без ожидания.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from dawg_replay_kit.dawg_api import (
+    READY_TIMEOUT,
+    AsyncRestProvisioner,
+    BrowserError,
+    Created,
+    RestProvisioner,
+    Sessions,
+    build_payload,
+)
+from dawg_replay_kit.events import Emitter
+
+DEFAULT_LIMIT = 1
+
+
+class BrowserLimitReached(BrowserError):
+    """Скрипт пытается открыть больше браузеров, чем разрешил kit.set_browser_limit()."""
+
+
+@dataclass
+class Connection:
+    browser: Any
+    context: Any
+    page: Any
+    close: Callable[[], Any]  # для async возвращает корутину
+
+
+# --- подключение Playwright -------------------------------------------------
+
+_local = threading.local()
+
+
+def _sync_connect(ws_url: str) -> Connection:
+    """Подключение sync API. Один экземпляр Playwright на поток, пока открыт хоть один браузер."""
+    from playwright.sync_api import sync_playwright
+
+    if getattr(_local, "pw", None) is None:
+        _local.pw = sync_playwright().start()
+        _local.users = 0
+    _local.users += 1
+    try:
+        browser = _local.pw.chromium.connect_over_cdp(ws_url)
+        context = browser.contexts[0] if browser.contexts else browser.new_context()
+        page = context.pages[0] if context.pages else context.new_page()
+    except BaseException:
+        _sync_release_pw()
+        raise
+
+    def close() -> None:
+        try:
+            browser.close()
+        finally:
+            _sync_release_pw()
+
+    return Connection(browser, context, page, close)
+
+
+def _sync_release_pw() -> None:
+    _local.users -= 1
+    if _local.users <= 0 and _local.pw is not None:
+        pw, _local.pw = _local.pw, None
+        try:
+            pw.stop()
+        except Exception:
+            pass
+
+
+_async_pw: dict[int, list[Any]] = {}  # id цикла -> [playwright, users]
+
+
+async def _async_connect(ws_url: str) -> Connection:
+    from playwright.async_api import async_playwright
+
+    key = id(asyncio.get_running_loop())
+    if key not in _async_pw:
+        _async_pw[key] = [await async_playwright().start(), 0]
+    entry = _async_pw[key]
+    entry[1] += 1
+    try:
+        browser = await entry[0].chromium.connect_over_cdp(ws_url)
+        context = browser.contexts[0] if browser.contexts else await browser.new_context()
+        page = context.pages[0] if context.pages else await context.new_page()
+    except BaseException:
+        await _async_release_pw(key)
+        raise
+
+    async def close() -> None:
+        try:
+            await browser.close()
+        finally:
+            await _async_release_pw(key)
+
+    return Connection(browser, context, page, close)
+
+
+async def _async_release_pw(key: int) -> None:
+    entry = _async_pw.get(key)
+    if entry is None:
+        return
+    entry[1] -= 1
+    if entry[1] <= 0:
+        _async_pw.pop(key, None)
+        try:
+            await entry[0].stop()
+        except Exception:
+            pass
+
+
+# --- менеджер ---------------------------------------------------------------
+
+
+class Browsers:
+    """Учёт браузеров скрипта: лимит, события, освобождение."""
+
+    def __init__(
+        self,
+        events: Emitter,
+        api_key: str | None,
+        base_url: str,
+        *,
+        provisioner: Callable[[], RestProvisioner] | None = None,
+        async_provisioner: Callable[[], AsyncRestProvisioner] | None = None,
+        sessions: Callable[[], Sessions] | None = None,
+        connect: Callable[[str], Connection] = _sync_connect,
+        aconnect: Callable[[str], Any] = _async_connect,
+    ):
+        self.events = events
+        self._api_key = api_key
+        self._base_url = base_url
+        self._provisioner = provisioner or (lambda: RestProvisioner(self._key(), self._base_url))
+        self._async_provisioner = async_provisioner or (lambda: AsyncRestProvisioner(self._key(), self._base_url))
+        self._sessions_factory = sessions or (lambda: Sessions(self._key(), self._base_url))
+        self._sessions: Sessions | None = None
+        self.connect = connect
+        self.aconnect = aconnect
+        self._limit = DEFAULT_LIMIT
+        self._in_use = 0
+        self._open: dict[str, str] = {}  # session_id -> browser_id, ещё не освобождённые
+        self._lock = threading.Lock()
+
+    def _key(self) -> str:
+        if not self._api_key:
+            raise BrowserError("нет ключа DAWG: задайте переменную DAWG_API_KEY", created=False)
+        return self._api_key
+
+    @property
+    def limit(self) -> int:
+        return self._limit
+
+    def set_limit(self, n: int) -> None:
+        if isinstance(n, bool) or not isinstance(n, int) or n < 1:
+            raise ValueError("лимит браузеров должен быть целым не меньше 1")
+        self._limit = n
+
+    def open_sessions(self) -> dict[str, str]:
+        with self._lock:
+            return dict(self._open)
+
+    # --- слот лимита ---
+
+    def acquire(self) -> None:
+        with self._lock:
+            if self._in_use >= self._limit:
+                raise BrowserLimitReached(
+                    f"скрипт уже держит {self._in_use} из {self._limit} разрешённых браузеров; "
+                    "закройте один или поднимите лимит kit.set_browser_limit(n)",
+                    created=False,
+                )
+            self._in_use += 1
+
+    def release_slot(self) -> None:
+        with self._lock:
+            self._in_use = max(0, self._in_use - 1)
+
+    # --- события ---
+
+    def on_retry(self, attempt: int, wait: float) -> None:
+        self.events.log("warn", f"платформа отказала в браузере (лимит тарифа), повтор {attempt} через {wait:.0f} с")
+
+    def provisioning(self) -> None:
+        self.events.session("provisioning")
+
+    def opened(self, created: Created) -> None:
+        with self._lock:
+            self._open[created.session_id] = created.browser_id
+        self.events.session("open", created.session_id, created.browser_id)
+
+    def failed(self, error: BrowserError) -> None:
+        if error.created is False:
+            self.events.session("failed")
+
+    # --- освобождение ---
+
+    def release(self, session_id: str) -> bool:
+        """Освобождает сессию. `close` пишется, только если её больше нет в списке ключа."""
+        with self._lock:
+            if session_id not in self._open:
+                return True
+        try:
+            if self._sessions is None:
+                self._sessions = self._sessions_factory()
+            gone = self._sessions.release(session_id)
+        except Exception as e:
+            self.events.log("error", f"браузер {session_id} не освобождён: {e}; его освободит приложение")
+            return False
+        if not gone:
+            self.events.log("error", f"браузер {session_id} всё ещё в списке сессий; его освободит приложение")
+            return False
+        with self._lock:
+            browser_id = self._open.pop(session_id, None)
+        self.events.session("close", session_id, browser_id)
+        return True
+
+    def release_all(self) -> None:
+        for sid in list(self.open_sessions()):
+            self.release(sid)
+
+    def close(self) -> None:
+        self.release_all()
+        if self._sessions is not None:
+            try:
+                self._sessions.close()
+            except Exception:
+                pass
+            self._sessions = None
+
+
+class BrowserSession:
+    """Результат `kit.browser()`. Работает как `with` и как `async with`."""
+
+    def __init__(
+        self,
+        manager: Browsers,
+        proxy: str | None = None,
+        geo: str | tuple[float, float] | None = None,
+        ready_timeout: float = READY_TIMEOUT,
+    ):
+        self._m = manager
+        self._payload = build_payload(proxy, geo)
+        self._ready_timeout = ready_timeout
+        self.session_id: str | None = None
+        self.browser_id: str | None = None
+        self.browser: Any = None
+        self.context: Any = None
+        self.page: Any = None
+        self._conn: Connection | None = None
+        self._slot = False
+
+    def __repr__(self) -> str:
+        return f"<BrowserSession {self.session_id or 'not open'}>"
+
+    # --- sync ---
+
+    def __enter__(self) -> BrowserSession:
+        self._m.acquire()
+        self._slot = True
+        try:
+            prov = self._m._provisioner()
+            try:
+                self._m.provisioning()
+                try:
+                    created = prov.create(self._payload, self._m.on_retry)
+                except BrowserError as e:
+                    self._m.failed(e)
+                    raise
+                self._opened(created)
+                ws_url = prov.wait_ready(created, self._ready_timeout)
+            finally:
+                prov.close()
+            self._attach(self._m.connect(ws_url))
+        except BaseException:
+            self._cleanup_sync()
+            raise
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._cleanup_sync()
+
+    def _cleanup_sync(self) -> None:
+        try:
+            if self._conn is not None:
+                conn, self._conn = self._conn, None
+                try:
+                    conn.close()
+                except Exception:
+                    pass
+        finally:
+            self._release_remote()
+
+    # --- async ---
+
+    async def __aenter__(self) -> BrowserSession:
+        self._m.acquire()
+        self._slot = True
+        try:
+            prov = self._m._async_provisioner()
+            try:
+                self._m.provisioning()
+                try:
+                    created = await prov.create(self._payload, self._m.on_retry)
+                except BrowserError as e:
+                    self._m.failed(e)
+                    raise
+                self._opened(created)
+                ws_url = await prov.wait_ready(created, self._ready_timeout)
+            finally:
+                await prov.close()
+            self._attach(await self._m.aconnect(ws_url))
+        except BaseException:
+            await self._cleanup_async()
+            raise
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self._cleanup_async()
+
+    async def _cleanup_async(self) -> None:
+        try:
+            if self._conn is not None:
+                conn, self._conn = self._conn, None
+                try:
+                    await conn.close()
+                except Exception:
+                    pass
+        finally:
+            # Освобождение короткое (DELETE и список), идёт синхронно: так оно
+            # не прерывается отменой задачи на выходе из цикла.
+            self._release_remote()
+
+    # --- общее ---
+
+    def _opened(self, created: Created) -> None:
+        self.session_id, self.browser_id = created.session_id, created.browser_id
+        self._m.opened(created)
+
+    def _attach(self, conn: Connection) -> None:
+        self._conn = conn
+        self.browser, self.context, self.page = conn.browser, conn.context, conn.page
+
+    def _release_remote(self) -> None:
+        try:
+            if self.session_id is not None:
+                self._m.release(self.session_id)
+        finally:
+            if self._slot:
+                self._slot = False
+                self._m.release_slot()