qplay 0.1__py3-none-any.whl

qplay/__init__.py

@@ -0,0 +1,84 @@
+from typing import Any
+
+from .kernel import (
+    GlobalState,
+    FilePathRealer,
+    Kernel,
+    K
+)
+
+from .utils import (
+    DownloadWatcher,
+)
+
+from .identylib import (
+    IdentityLib,
+    IdentityRecord,
+    ID,
+    Identity,
+    Register,
+    Resolve,
+    Batch,
+    MACRO_PREFIX,
+    ID_PREFIX,
+)
+
+from .play import (
+    Element,
+    WebPage,
+    initplay,
+)
+
+from .ptable import (
+    WebTable,
+)
+
+from .persist import (
+    QWeb,
+)
+
+
+# Direct component access (from initialized kernel)
+G = K.G
+F = K.F
+H = K.H
+T = K.T
+
+
+
+__all__ = [
+    # Core components
+    'G', 'F', 'H', 'T', 'K',
+
+    # Kernel classes
+    'Kernel',
+    'GlobalState',
+    'FilePathRealer',
+
+    # Utils
+    'DownloadWatcher',
+
+    # Identity
+    'IdentityLib',
+    'IdentityRecord',
+    'ID',
+    'Identity',
+    'Register',
+    'Resolve',
+    'Batch',
+    'MACRO_PREFIX',
+    'ID_PREFIX',
+
+    # Playwright browser automation
+    'Element',
+    'WebPage',
+    'initplay',
+
+    # Persistent Qt web container
+    'QWeb',
+
+    # Table wrapper
+    'WebTable',
+
+]
+

qplay/identylib.py

@@ -0,0 +1,492 @@
+"""
+qplay identylib module - Identity library management
+
+Manages XPath-based element identifiers with macro support.
+Provides centralized storage and lookup for element identities.
+
+Identity format:
+- xpath: "//div[@id='main']"
+- @id: "@login" -> resolves to xpath "//*[@id='login']"
+- $macro: "$login_btn" -> resolves to stored xpath
+- inline def: "$btn: //button" -> registers and returns xpath
+- parameterized: "$btn('submit')" -> resolves with format substitution
+"""
+
+import os
+import re
+import json
+import threading
+from typing import Self
+from dataclasses import dataclass
+
+from .stdio import Info, Warn, Error
+
+
+MACRO_PREFIX = "$"
+ID_PREFIX = "@"
+IDENTITY_FILE = "identities.json"
+
+# Parameterized macro pattern: $Name('arg1', "arg2", ...)
+_PARAM_PATTERN = re.compile(r"\$([^\(]+)\(([^)]+)\)")
+# String literal pattern for parameter extraction
+_STRING_PATTERN = re.compile(r"['\"][^'\"]*['\"]")
+
+
+@dataclass
+class IdentityRecord:
+    """Identity record with metadata."""
+    xpath: str
+    desc: str = ""
+    tag: str = ""
+
+
+class IdentityLib:
+    """
+    Identity library for managing XPath-based element identifiers.
+
+    Supports macro definitions for shorthand access.
+    All identities are stored as XPath expressions.
+
+    Usage:
+        lib = IdentityLib()
+        lib.register("$login_btn", "//button[@id='login']", "Login button")
+
+        # Resolve different identity types
+        xpath = lib.resolve("$login_btn")  # -> "//button[@id='login']"
+        xpath = lib.resolve("@login")      # -> "//*[@id='login']"
+        xpath = lib.resolve("//div")       # -> returns as-is
+        xpath = lib.resolve("$btn: //button")  # registers and returns
+        xpath = lib.resolve("$btn('ok')")  # -> "//button[text()='ok']"
+    """
+
+    _instance: "IdentityLib | None" = None
+    _initialized: bool = False
+    _lock: threading.Lock = threading.Lock()
+
+    def __new__(cls) -> "IdentityLib":
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        with IdentityLib._lock:
+            if IdentityLib._initialized:
+                return
+            IdentityLib._initialized = True
+
+            self._macros: dict[str, IdentityRecord] = {}
+            self._storage_path: str | None = None
+
+    def init(self, storage_dir: str | None = None) -> Self:
+        """
+        Initialize library with storage directory.
+
+        Args:
+            storage_dir: Directory for persistence, None for memory-only
+
+        Returns:
+            self for chaining
+        """
+        if storage_dir is not None:
+            self._storage_path = os.path.join(storage_dir, IDENTITY_FILE)
+            self._load()
+        return self
+
+    def _load(self) -> None:
+        """Load identities from storage."""
+        if self._storage_path is None or not os.path.exists(self._storage_path):
+            return
+
+        try:
+            with open(self._storage_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            for key, value in data.items():
+                if isinstance(value, str):
+                    self._macros[key] = IdentityRecord(xpath=value)
+                elif isinstance(value, dict):
+                    self._macros[key] = IdentityRecord(
+                        xpath=value.get("xpath", ""),
+                        desc=value.get("desc", ""),
+                        tag=value.get("tag", "")
+                    )
+            Info("idlib", "loaded", f"{len(self._macros)} macros")
+        except Exception as e:
+            Warn("idlib", "load failed", str(e))
+
+    def save(self) -> Self:
+        """
+        Save identities to storage.
+
+        Returns:
+            self for chaining
+        """
+        if self._storage_path is None:
+            Warn("idlib", "no storage path set")
+            return self
+
+        try:
+            data: dict[str, dict] = {}
+            for key, record in self._macros.items():
+                data[key] = {
+                    "xpath": record.xpath,
+                    "desc": record.desc,
+                    "tag": record.tag
+                }
+            _dir = os.path.dirname(self._storage_path)
+            os.makedirs(_dir, exist_ok=True)
+            # Atomic write: temp file in same dir, then os.replace (atomic on
+            # same filesystem). Prevents a crash mid-write from leaving a
+            # truncated/corrupt identities store.
+            import tempfile
+            _fd, _tmp = tempfile.mkstemp(dir=_dir, suffix=".tmp")
+            try:
+                with os.fdopen(_fd, "w", encoding="utf-8") as f:
+                    json.dump(data, f, ensure_ascii=False, indent=2)
+                os.replace(_tmp, self._storage_path)
+            except Exception:
+                try:
+                    os.remove(_tmp)
+                except OSError:
+                    pass
+                raise
+            Info("idlib", "saved", f"{len(self._macros)} macros")
+        except Exception as e:
+            Error("idlib", "save failed", str(e))
+        return self
+
+    def register(self, macro: str, xpath: str, desc: str = "", tag: str = "") -> Self:
+        """
+        Register a macro identity.
+
+        Args:
+            macro: Macro name (auto-prefixed with $ if missing)
+            xpath: XPath expression
+            desc: Description
+            tag: Category tag
+
+        Returns:
+            self for chaining
+        """
+        if not macro.startswith(MACRO_PREFIX):
+            macro = MACRO_PREFIX + macro
+
+        self._macros[macro] = IdentityRecord(
+            xpath=xpath,
+            desc=desc,
+            tag=tag
+        )
+        Info("idlib", "registered", macro)
+        return self
+
+    def unregister(self, macro: str) -> bool:
+        """
+        Unregister a macro.
+
+        Args:
+            macro: Macro name to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        if not macro.startswith(MACRO_PREFIX):
+            macro = MACRO_PREFIX + macro
+
+        if macro in self._macros:
+            del self._macros[macro]
+            Info("idlib", "unregistered", macro)
+            return True
+        return False
+
+    def resolve(self, identity: str) -> str:
+        """
+        Resolve identity to XPath.
+
+        Supports:
+        - Plain xpath: "//div[@id='main']" -> returns as-is
+        - ID prefix: "@login" -> "//*[@id='login']"
+        - Macro: "$login_btn" -> resolves from library
+        - Inline register: "$btn: //button" -> registers and returns
+        - Parameterized: "$btn('ok')" -> applies format
+
+        Args:
+            identity: identity string
+
+        Returns:
+            XPath expression
+
+        Raises:
+            KeyError: If macro not found
+            ValueError: If parameterized macro format is invalid
+        """
+        _ident = identity.strip()
+
+        if not _ident:
+            return _ident
+
+        # Case 1: ID prefix @id -> xpath "//*[@id='id']"
+        if _ident.startswith(ID_PREFIX):
+            _id_value = _ident[1:].strip()
+            return f"//*[@id='{_id_value}']"
+
+        # Case 2: Macro prefix $
+        if _ident.startswith(MACRO_PREFIX):
+            return self._resolveMacro(_ident)
+
+        # Case 3: Plain xpath or other - return as-is
+        return _ident
+
+    def _resolveMacro(self, identity: str) -> str:
+        """
+        Resolve macro expression.
+
+        Handles:
+        - $macro -> lookup in library
+        - $macro: xpath -> inline register
+        - $macro('arg') -> parameterized lookup
+        """
+        # Check for inline definition: $macro: xpath
+        _colon_idx = identity.find(":")
+        if _colon_idx != -1:
+            # Make sure it's not part of a parameterized call like $macro('arg'): xpath
+            _paren_idx = identity.find("(")
+            if _paren_idx == -1 or _colon_idx < _paren_idx:
+                _key = re.sub(r"\s", "", identity[:_colon_idx])
+                if "(" in _key or ")" in _key:
+                    raise KeyError(f"[IdentityError]: Cannot use '()' in def. Like: '$xxx():YYYY'.")
+                _value = identity[_colon_idx + 1:].strip()
+                self._library[_key] = IdentityRecord(xpath=_value)
+                Info("idlib", "inline registered", _key)
+                return _value
+
+        # Check for parameterized: $macro('arg1', "arg2")
+        _match = _PARAM_PATTERN.match(identity)
+        if _match:
+            _key = re.sub(r"\s", "", _match.group(1))
+            if not _key.startswith(MACRO_PREFIX):
+                _key = MACRO_PREFIX + _key
+            _params_str = _match.group(2)
+            # Extract string literals
+            _params = re.findall(_STRING_PATTERN, _params_str)
+            # Remove quotes from params
+            _params = [p[1:-1] for p in _params]
+
+            if _key not in self._macros:
+                raise KeyError(f"[IdentityMissing]: Do not have identity:{_key} in library.")
+
+            _xpath = self._macros[_key].xpath
+            if _params:
+                try:
+                    _xpath = _xpath.format(*_params)
+                except Exception as e:
+                    raise ValueError(f"Format Failed: {e}. \n\traw:'{_xpath}'\n\treplaces:{_params}")
+            return _xpath
+
+        # Simple macro lookup
+        if identity not in self._macros:
+            raise KeyError(f"Macro '{identity}' not found")
+
+        return self._macros[identity].xpath
+
+    def get(self, macro: str) -> IdentityRecord | None:
+        """
+        Get identity record by macro.
+
+        Args:
+            macro: Macro name
+
+        Returns:
+            IdentityRecord or None
+        """
+        if not macro.startswith(MACRO_PREFIX):
+            macro = MACRO_PREFIX + macro
+        return self._macros.get(macro)
+
+    def test(self, identity: str) -> bool:
+        """
+        Test if identity is valid (macro exists or valid xpath).
+
+        Args:
+            identity: xpath or $macro to test
+
+        Returns:
+            True if valid
+        """
+        try:
+            self.resolve(identity)
+            return True
+        except (KeyError, ValueError):
+            return False
+
+    def list(self, tag: str | None = None) -> list[str]:
+        """
+        List all registered macros.
+
+        Args:
+            tag: Filter by tag, None for all
+
+        Returns:
+            List of macro names
+        """
+        if tag is None:
+            return list(self._macros.keys())
+        return [k for k, v in self._macros.items() if v.tag == tag]
+
+    def clear(self) -> Self:
+        """
+        Clear all macros.
+
+        Returns:
+            self for chaining
+        """
+        self._macros.clear()
+        Info("idlib", "cleared")
+        return self
+
+    def batch(self, identities: dict[str, str], tag: str = "") -> Self:
+        """
+        Batch register identities.
+
+        Args:
+            identities: Dict of macro -> xpath
+            tag: Default tag for all
+
+        Returns:
+            self for chaining
+        """
+        for macro, xpath in identities.items():
+            self.register(macro, xpath, tag=tag)
+        return self
+
+    def to_dict(self) -> dict[str, dict]:
+        """Export all identities to dictionary."""
+        return {
+            k: {"xpath": v.xpath, "desc": v.desc, "tag": v.tag}
+            for k, v in self._macros.items()
+        }
+
+    def from_dict(self, data: dict[str, dict | str]) -> Self:
+        """
+        Import identities from dictionary.
+
+        Args:
+            data: Dict of macro -> record or xpath string
+
+        Returns:
+            self for chaining
+        """
+        for key, value in data.items():
+            if isinstance(value, str):
+                self.register(key, value)
+            else:
+                self.register(
+                    key,
+                    value.get("xpath", ""),
+                    value.get("desc", ""),
+                    value.get("tag", "")
+                )
+        return self
+
+    @property
+    def count(self) -> int:
+        """Number of registered macros."""
+        return len(self._macros)
+
+    @property
+    def storage(self) -> str | None:
+        """Current storage path."""
+        return self._storage_path
+
+    @property
+    def _library(self) -> dict[str, IdentityRecord]:
+        """Direct access to macro library (for compatibility with inline register)."""
+        return self._macros
+
+
+# Global identity library instance
+ID = IdentityLib()
+
+
+def Identity(macro: str, xpath: str = "", desc: str = "") -> str:
+    """
+    Register or resolve identity.
+
+    If xpath provided: register macro and return xpath
+    If xpath empty: resolve macro to xpath
+
+    Args:
+        macro: Macro name (auto-prefixed with $)
+        xpath: XPath expression (optional)
+        desc: Description (optional)
+
+    Returns:
+        XPath expression
+    """
+    if xpath:
+        ID.register(macro, xpath, desc)
+        return xpath
+    return ID.resolve(macro)
+
+
+def Register(macro: str, xpath: str, desc: str = "", tag: str = "") -> IdentityLib:
+    """
+    Register identity macro.
+
+    Args:
+        macro: Macro name (auto-prefixed with $)
+        xpath: XPath expression
+        desc: Description
+        tag: Category tag
+
+    Returns:
+        IdentityLib instance for chaining
+    """
+    return ID.register(macro, xpath, desc, tag)
+
+
+def Resolve(identity: str) -> str:
+    """
+    Resolve identity to XPath.
+
+    Supports:
+    - Plain xpath: "//div[@id='main']"
+    - ID prefix: "@login" -> "//*[@id='login']"
+    - Macro: "$login_btn" -> resolves from library
+    - Inline: "$btn: //button" -> registers and returns
+    - Parameterized: "$btn('ok')" -> applies format
+
+    Args:
+        identity: xpath, @id, $macro, etc.
+
+    Returns:
+        XPath expression
+    """
+    return ID.resolve(identity)
+
+
+def Batch(identities: dict[str, str], tag: str = "") -> IdentityLib:
+    """
+    Batch register identities.
+
+    Args:
+        identities: Dict of macro -> xpath
+        tag: Default tag
+
+    Returns:
+        IdentityLib instance
+    """
+    return ID.batch(identities, tag)
+
+
+__all__ = [
+    "IdentityLib",
+    "IdentityRecord",
+    "ID",
+    "Identity",
+    "Register",
+    "Resolve",
+    "Batch",
+    "MACRO_PREFIX",
+    "ID_PREFIX",
+]