persona-dsl 26.1.21.44__py3-none-any.whl

persona_dsl/skills/__init__.py

@@ -0,0 +1,7 @@
+from .use_api import UseAPI
+from .use_browser import UseBrowser
+from .use_database import UseDatabase
+from .use_kafka import UseKafka
+from .use_soap import UseSOAP
+
+__all__ = ["UseAPI", "UseBrowser", "UseDatabase", "UseKafka", "UseSOAP"]

persona_dsl/skills/core/base.py

@@ -0,0 +1,41 @@
+from typing import Any
+
+
+class Skill:
+    """Базовый класс-обертка для навыка, который управляет экземпляром драйвера/клиента."""
+
+    def __init__(self, driver: Any):
+        self.driver = driver
+
+    @property
+    def driver(self) -> Any:
+        return self._driver
+
+    @driver.setter
+    def driver(self, value: Any) -> None:
+        self._driver = value
+
+    @classmethod
+    def from_driver(cls, driver: Any) -> "Skill":
+        """Фабричный метод для создания экземпляра Навыка из готового драйвера/клиента."""
+        return cls(driver)
+
+    def acquire(self) -> None:
+        """Опциональный хук для ленивого создания драйвера."""
+        pass
+
+    def release(self) -> None:
+        """Опциональный хук для освобождения ресурсов драйвера."""
+        pass
+
+    def forget(self) -> None:
+        """
+        Единая точка освобождения ресурсов навыка.
+        По умолчанию делегирует в release(), подавляя возможные исключения,
+        и сбрасывает драйвер.
+        """
+        try:
+            self.release()
+        except Exception:
+            pass
+        self.driver = None

persona_dsl/skills/core/skill_definition.py

@@ -0,0 +1,30 @@
+from enum import Enum
+
+
+class SkillId(str, Enum):
+    """Идентификаторы (типы) стандартных навыков."""
+
+    BROWSER = "browser"
+    API = "api"
+    DB = "db"
+    KAFKA = "kafka"
+    SOAP = "soap"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class BaseSkill:
+    """
+    Библиотека стандартных идентификаторов навыков.
+    Содержит предопределенные базовые навыки.
+    Наследуйтесь от этого класса в своем проекте, чтобы добавить
+    кастомные именованные навыки для удобного доступа.
+    """
+
+    # --- Базовые навыки ---
+    BROWSER: tuple[SkillId, str] = (SkillId.BROWSER, "default")
+    API: tuple[SkillId, str] = (SkillId.API, "default")
+    DB: tuple[SkillId, str] = (SkillId.DB, "default")
+    KAFKA: tuple[SkillId, str] = (SkillId.KAFKA, "default")
+    SOAP: tuple[SkillId, str] = (SkillId.SOAP, "default")

persona_dsl/skills/use_api.py

@@ -0,0 +1,251 @@
+import allure
+import requests
+import time
+from typing import Any, cast, Optional
+from pydantic import TypeAdapter, ValidationError
+from persona_dsl.utils.metrics import metrics
+from .core.base import Skill
+
+
+class UseAPI(Skill):
+    """Навык для взаимодействия с REST API."""
+
+    def __init__(
+        self,
+        session: requests.Session,
+        base_url: str,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+        retries: int = 0,
+        backoff: float = 0.5,
+        log_bodies: bool = False,
+    ):
+        super().__init__(session)
+        self.base_url = base_url
+        self.timeout = timeout
+        self.retries = retries
+        self.backoff = backoff
+        self.log_bodies = log_bodies
+
+    @classmethod
+    def at(
+        cls,
+        base_url: str,
+        verify_ssl: bool = True,
+        timeout: float = 10.0,
+        retries: int = 0,
+        backoff: float = 0.5,
+        log_bodies: bool = False,
+        default_headers: Optional[dict] = None,
+    ) -> "UseAPI":
+        session = requests.Session()
+        session.verify = verify_ssl
+        if default_headers:
+            session.headers.update(default_headers)
+        inst = cls(session, base_url, verify_ssl, timeout, retries, backoff, log_bodies)
+        return inst
+
+    @property
+    def session(self) -> requests.Session:
+        return cast(requests.Session, self._driver)
+
+    def _full_url(self, path: str) -> str:
+        """Строит полный URL из базового и относительного пути."""
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        base = self.base_url.rstrip("/")
+        rel = path if path.startswith("/") else f"/{path}"
+        return f"{base}{rel}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
+        """Обертка над requests с метриками, ретраями и опциональными вложениями в Allure."""
+        url = self._full_url(path)
+        status = None
+        t0 = time.perf_counter()
+        attempts = self.retries + 1
+        last_exc = None
+        try:
+            for attempt in range(attempts):
+                try:
+                    # Преобразуем Pydantic-модели в dict перед отправкой (json/data могут содержать модели или их коллекции)
+                    def _to_jsonable(obj: Any) -> Any:
+                        if hasattr(obj, "model_dump"):
+                            return obj.model_dump()
+                        if isinstance(obj, dict):
+                            return {k: _to_jsonable(v) for k, v in obj.items()}
+                        if isinstance(obj, (list, tuple)):
+                            return [_to_jsonable(x) for x in obj]
+                        return obj
+
+                    if "json" in kwargs:
+                        kwargs["json"] = _to_jsonable(kwargs["json"])
+                    if "data" in kwargs:
+                        kwargs["data"] = _to_jsonable(kwargs["data"])
+
+                    resp = self.session.request(
+                        method=method.upper(),
+                        url=url,
+                        timeout=kwargs.pop("timeout", self.timeout),
+                        **kwargs,
+                    )
+                    status = resp.status_code
+                    # Повторяем при 5xx, если есть попытки
+                    if 500 <= status < 600 and attempt < self.retries:
+                        time.sleep(self.backoff * (2**attempt))
+                        continue
+                    if self.log_bodies:
+                        req_body = kwargs.get("json", kwargs.get("data"))
+                        # Собираем заголовки: session.headers (если доступны) + per-request headers
+                        combined_headers = {}
+                        try:
+                            base_headers_obj = getattr(self.session, "headers", {})
+                            base_headers = dict(base_headers_obj)
+                        except Exception:
+                            base_headers = {}
+                        req_headers = {}
+                        try:
+                            if isinstance(kwargs.get("headers"), dict):
+                                req_headers = dict(kwargs.get("headers") or {})
+                        except Exception:
+                            req_headers = {}
+                        combined_headers.update(base_headers)
+                        combined_headers.update(req_headers)
+                        if "Authorization" in combined_headers:
+                            combined_headers["Authorization"] = "***"
+                        allure.attach(
+                            f"Request: {method.upper()} {url}\nheaders={combined_headers}\nbody={req_body}",
+                            "HTTP Request",
+                            allure.attachment_type.TEXT,
+                        )
+                        allure.attach(
+                            f"Response: status={resp.status_code}\nheaders={dict(resp.headers)}\nbody={resp.text[:1000]}",
+                            "HTTP Response",
+                            allure.attachment_type.TEXT,
+                        )
+                    return resp
+                except requests.RequestException as e:
+                    last_exc = e
+                    if attempt < self.retries:
+                        time.sleep(self.backoff * (2**attempt))
+                        continue
+                    raise
+        except Exception:
+            status = -1
+            if last_exc:
+                raise last_exc
+            raise
+        finally:
+            duration = time.perf_counter() - t0
+            tags = {"method": method.upper(), "endpoint": path, "status": status}
+            metrics.gauge("api.request.duration", duration, tags)
+            metrics.counter("api.request", tags).inc()
+        # This code should be unreachable, as the loop will always either return a response
+        # or raise an exception.
+        raise RuntimeError(
+            "Unreachable code in UseAPI._request reached"
+        )  # pragma: no cover
+
+    def get(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("PATCH", path, **kwargs)
+
+    def head(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("HEAD", path, **kwargs)
+
+    def options(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("OPTIONS", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> requests.Response:
+        return self._request("DELETE", path, **kwargs)
+
+    def _validate_as(self, data: Any, model_type: Any) -> Any:
+        """
+        Преобразует произвольный JSON в указанный тип с помощью Pydantic v2.
+        Поддерживает сложные аннотации (например, list[MyModel]) через TypeAdapter.
+        При ошибке валидации выбрасывает исключение с подробной диагностикой (без скрытых фолбеков).
+        """
+        try:
+            return TypeAdapter(model_type).validate_python(data)
+        except (ValidationError, TypeError) as e:
+            raise ValueError(
+                f"Валидация ответа API не прошла для типа {model_type}: {e}"
+            ) from e
+
+    def get_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает GET и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        Пример: api.get_json_as('/users/1', User) или api.get_json_as('/users', list[User])
+        """
+        resp = self.get(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def post_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает POST и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        """
+        resp = self.post(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def put_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает PUT и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        """
+        resp = self.put(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def patch_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает PATCH и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        """
+        resp = self.patch(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def delete_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает DELETE и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        """
+        resp = self.delete(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def head_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает HEAD и валидирует JSON-ответ как указанный тип (если сервер всё же возвращает тело).
+        Примечание: согласно спецификации, ответ HEAD не должен содержать тело; метод добавлен для полноты API.
+        """
+        resp = self.head(path, **kwargs)
+        # Если тело ответа пустое — это валидный случай для HEAD-запроса.
+        if not resp.text:
+            return None
+        try:
+            data = resp.json()
+        except requests.JSONDecodeError as e:
+            raise ValueError(
+                f"HEAD {path}: ответ содержит тело, но оно не является валидным JSON: {e}"
+            ) from e
+        return self._validate_as(data, model_type)
+
+    def options_json_as(self, path: str, model_type: Any, **kwargs: Any) -> Any:
+        """
+        Делает OPTIONS и валидирует JSON-ответ как указанный тип (Pydantic v2).
+        """
+        resp = self.options(path, **kwargs)
+        return self._validate_as(resp.json(), model_type)
+
+    def release(self) -> None:
+        """Освобождает ресурсы HTTP-клиента (закрывает Session)."""
+        try:
+            self.session.close()
+        except Exception:
+            pass
+
+    def forget(self) -> None:
+        """Совместимость: делегирует в базовый Skill.forget()."""
+        return super().forget()

persona_dsl/skills/use_browser.py

@@ -0,0 +1,78 @@
+from typing import Optional, cast
+from pathlib import Path
+
+from playwright.sync_api import Page
+
+from .core.base import Skill
+
+
+class UseBrowser(Skill):
+    """Навык, который предоставляет доступ к драйверу страницы Playwright.
+
+    Хранит и применяет глобальные настройки таймаутов страницы:
+      - default_timeout: общий таймаут ожиданий (мс) для всех операций
+      - default_navigation_timeout: таймаут навигации/загрузки (мс)
+      - inject_runtime: автоматически внедрять Persona Runtime JS (по умолчанию True)
+    """
+
+    def __init__(
+        self,
+        page: Page,
+        base_url: Optional[str] = None,
+        default_timeout: Optional[float] = None,
+        default_navigation_timeout: Optional[float] = None,
+        inject_runtime: bool = True,
+    ):
+        super().__init__(page)
+        self.base_url = base_url
+        self._default_timeout = default_timeout
+        self._default_navigation_timeout = default_navigation_timeout
+        self._inject_runtime = inject_runtime
+
+        # Применяем таймауты к странице, если заданы
+        if self._default_timeout is not None:
+            page.set_default_timeout(float(self._default_timeout))
+        if self._default_navigation_timeout is not None:
+            page.set_default_navigation_timeout(float(self._default_navigation_timeout))
+
+        if self._inject_runtime:
+            self._inject_persona_runtime(page)
+
+    def _inject_persona_runtime(self, page: Page) -> None:
+        """Внедряет JS-ядро Persona Runtime на страницу."""
+        try:
+            # Путь к бандлу относительно текущего файла
+            # persona_dsl/skills/use_browser.py -> ... -> persona_dsl/runtime/dist/persona_bundle.js
+            current_dir = Path(__file__).parent
+            bundle_path = current_dir.parent / "runtime" / "dist" / "persona_bundle.js"
+
+            if bundle_path.exists():
+                js_content = bundle_path.read_text(encoding="utf-8")
+                page.add_init_script(js_content)
+            else:
+                # В dev-режиме или если не собрано — предупреждаем, но не падаем жестко,
+                # хотя функционал Runtime будет недоступен.
+                print(f"[Persona] Warning: Runtime bundle not found at {bundle_path}")
+        except Exception as e:
+            print(f"[Persona] Error injecting runtime: {e}")
+
+    @property
+    def page(self) -> Page:
+        return cast(Page, self.driver)
+
+    @classmethod
+    def from_page(
+        cls,
+        page: Page,
+        base_url: Optional[str] = None,
+        default_timeout: Optional[float] = None,
+        default_navigation_timeout: Optional[float] = None,
+        inject_runtime: bool = True,
+    ) -> "UseBrowser":
+        return cls(
+            page,
+            base_url=base_url,
+            default_timeout=default_timeout,
+            default_navigation_timeout=default_navigation_timeout,
+            inject_runtime=inject_runtime,
+        )

persona_dsl/skills/use_database.py

@@ -0,0 +1,129 @@
+import time
+from types import ModuleType
+from typing import Any, Optional
+from urllib.parse import urlparse
+from persona_dsl.utils.metrics import metrics
+from .core.base import Skill
+
+
+class UseDatabase(Skill):
+    """Навык для взаимодействия с реляционными базами данных."""
+
+    def __init__(self, dsn: str, driver: ModuleType):
+        super().__init__(driver)
+        self.dsn = dsn
+        self.connection: Optional[Any] = None
+
+    @staticmethod
+    def with_dsn(dsn: str, driver: ModuleType) -> "UseDatabase":
+        """Фабричный метод для создания экземпляра навыка.
+
+        Args:
+            dsn: DSN-строка для подключения к базе данных.
+            driver: Модуль-драйвер для работы с БД (например, psycopg или oracledb).
+
+        Returns:
+            Экземпляр UseDatabase.
+        """
+        return UseDatabase(dsn, driver)
+
+    def get_connection(self) -> Any:
+        """Возвращает активное соединение с базой данных.
+
+        Если соединение отсутствует или закрыто, создает новое.
+
+        Returns:
+            Активное соединение с БД.
+        """
+        need_reconnect = (
+            self.connection is None
+            or getattr(self.connection, "closed", False)
+            or (
+                callable(getattr(self.connection, "is_healthy", None))
+                and not self.connection.is_healthy()
+            )
+        )
+        if need_reconnect:
+            # Поддерживаем корректные способы подключения драйверов:
+            # - pg8000: требуем DSN в URL-формате postgresql://user:pass@host:port/db и конструируем именованные аргументы
+            # - psycopg/psycopg2: принимают conninfo строкой (передаём как есть)
+            # - oracledb: допускает строку вида "user/password@dsn" как позиционный аргумент
+            drv_name = getattr(self.driver, "__name__", "") or ""
+            if drv_name.startswith("pg8000"):
+                u = urlparse(self.dsn)
+                if u.scheme not in (
+                    "postgresql",
+                    "postgres",
+                    "postgresql+pg8000",
+                    "postgres+pg8000",
+                ):
+                    raise ValueError(
+                        "Для драйвера pg8000 DSN должен быть в URL-формате: postgresql://user:pass@host:port/dbname"
+                    )
+                user = u.username or ""
+                password = u.password or ""
+                host = u.hostname or ""
+                port = int(u.port or 5432)
+                db = u.path.lstrip("/") if u.path else ""
+                if not (user and host and db):
+                    raise ValueError(
+                        "pg8000: некорректный DSN URL (требуются user, host, database). Пример: postgresql://user:pass@localhost:5432/db"
+                    )
+                self.connection = self.driver.connect(
+                    user=user, password=password, host=host, port=port, database=db
+                )
+            else:
+                # Для остальных драйверов используем conninfo/позиционный аргумент согласно их API.
+                self.connection = self.driver.connect(self.dsn)
+        return self.connection
+
+    def execute(self, query: str, params: Optional[Any] = None) -> Any:
+        """Выполняет SQL-запрос с метриками и возвращает первую строку результата.
+
+        Args:
+            query: SQL-запрос.
+            params: Параметры запроса.
+
+        Returns:
+            Первая строка результата (или None).
+        """
+        t0 = time.perf_counter()
+        status = "ok"
+        try:
+            conn = self.get_connection()
+            cursor = conn.cursor()
+            try:
+                cursor.execute(query, params or ())
+                result = cursor.fetchone()
+                conn.commit()
+                return result
+            finally:
+                try:
+                    cursor.close()
+                except Exception:
+                    pass
+        except Exception:
+            status = "error"
+            raise
+        finally:
+            duration = time.perf_counter() - t0
+            tags = {
+                "driver": self.driver.__name__,
+                "query": query.split()[0].upper() if query else "UNKNOWN",
+                "status": status,
+            }
+            metrics.gauge("db.query.duration", duration, tags)
+            metrics.counter("db.query", tags).inc()
+
+    def release(self) -> None:
+        """Закрывает соединение с БД, если оно открыто."""
+        if self.connection:
+            if hasattr(self.connection, "closed") and not self.connection.closed:
+                self.connection.close()
+            elif hasattr(self.connection, "close"):  # Для oracledb, где нет closed
+                self.connection.close()
+            self.connection = None
+
+    def forget(self) -> None:
+        """Совместимость: делегирует в базовый Skill.forget()."""
+        return super().forget()

persona_dsl/skills/use_kafka.py

@@ -0,0 +1,135 @@
+import logging
+from typing import Optional, List, Dict, Any
+
+from kafka import KafkaConsumer, KafkaProducer
+
+from .core.base import Skill
+
+logger = logging.getLogger(__name__)
+
+
+class UseKafka(Skill):
+    """Навык для взаимодействия с Kafka."""
+
+    def __init__(
+        self,
+        bootstrap_servers: str,
+        group_id: Optional[str] = None,
+        from_offset: str = "latest",  # "earliest" | "latest"
+        timeout: float = 10.0,
+    ):
+        super().__init__(driver=None)
+        self.bootstrap_servers = bootstrap_servers
+        self.group_id = group_id
+        self.from_offset = (
+            from_offset if from_offset in ("earliest", "latest") else "latest"
+        )
+        self.timeout = float(timeout)
+        self._producer = None
+        self._consumer = None
+
+    @staticmethod
+    def with_servers(
+        bootstrap_servers: str,
+        group_id: Optional[str] = None,
+        from_offset: str = "latest",
+        timeout: float = 10.0,
+    ) -> "UseKafka":
+        """Фабричный метод для создания экземпляра навыка."""
+        return UseKafka(
+            bootstrap_servers=bootstrap_servers,
+            group_id=group_id,
+            from_offset=from_offset,
+            timeout=timeout,
+        )
+
+    def _get_producer(self) -> Any:
+        if self._producer is None:
+            self._producer = KafkaProducer(bootstrap_servers=self.bootstrap_servers)
+        return self._producer
+
+    def _get_consumer(self, topic: str) -> Any:
+        if self._consumer is None:
+            auto_offset_reset = self.from_offset
+            consumer_timeout_ms = int(self.timeout * 1000)
+            self._consumer = KafkaConsumer(
+                topic,
+                bootstrap_servers=self.bootstrap_servers,
+                group_id=self.group_id,
+                enable_auto_commit=False,
+                auto_offset_reset=auto_offset_reset,
+                consumer_timeout_ms=consumer_timeout_ms,
+            )
+        return self._consumer
+
+    def send_message(
+        self,
+        topic: str,
+        message: bytes,
+        key: Optional[bytes] = None,
+        headers: Optional[List[tuple[str, bytes]]] = None,
+    ) -> None:
+        """Отправляет сообщение в указанный топик Kafka."""
+        producer = self._get_producer()
+        try:
+            future = producer.send(topic, key=key, value=message, headers=headers or [])
+            future.get(timeout=self.timeout)
+            producer.flush(timeout=self.timeout)
+        except Exception as e:
+            logger.error(f"[UseKafka] Ошибка при отправке сообщения в '{topic}': {e}")
+            raise
+
+    def consume(
+        self,
+        topic: str,
+        max_messages: int = 1,
+        timeout: Optional[float] = None,
+    ) -> List[Dict[str, Any]]:
+        """Читает сообщения из топика (до max_messages или до таймаута)."""
+        consumer = self._get_consumer(topic)
+        results: List[Dict[str, Any]] = []
+        end_after = timeout or self.timeout
+        try:
+            import time
+
+            start = time.time()
+            while len(results) < max_messages and (time.time() - start) < end_after:
+                try:
+                    msg = next(consumer)
+                except StopIteration:
+                    break
+                results.append(
+                    {
+                        "topic": msg.topic,
+                        "partition": msg.partition,
+                        "offset": msg.offset,
+                        "timestamp": msg.timestamp,
+                        "key": msg.key,
+                        "value": msg.value,
+                        "headers": dict(msg.headers or []),
+                    }
+                )
+        except Exception as e:
+            logger.error(f"[UseKafka] Ошибка при чтении сообщений из '{topic}': {e}")
+            raise
+        return results
+
+    def release(self) -> None:
+        """Закрывает все соединения и освобождает ресурсы."""
+        try:
+            if self._producer:
+                self._producer.flush(timeout=self.timeout)
+                self._producer.close()
+        except Exception:
+            pass
+        try:
+            if self._consumer:
+                self._consumer.close()
+        except Exception:
+            pass
+        self._producer = None
+        self._consumer = None
+
+    def forget(self) -> None:
+        """Совместимость: делегирует в базовый Skill.forget()."""
+        return super().forget()