plaita 0.4.0__tar.gz

plaita-0.4.0/MANIFEST.in

@@ -0,0 +1 @@
+include requirements.txt

plaita-0.4.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: plaita
+Version: 0.4.0
+Summary: Official Python Runtime for Plaita -- Logic Compose Engine
+Author-email: Jeff kit <bbmyth@gmail.com>
+Project-URL: Homepage, https://jeffkit.github.io/plaita/
+Project-URL: Repository, https://github.com/jeffkit/plaita
+Project-URL: Documentation, https://jeffkit.github.io/plaita/
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyparsing>=3.0
+Requires-Dist: isodate
+Provides-Extra: redis
+Requires-Dist: redis>=4.0.0; extra == "redis"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.68.0; extra == "server"
+Requires-Dist: uvicorn>=0.15.0; extra == "server"
+Requires-Dist: python-multipart>=0.0.5; extra == "server"
+Requires-Dist: python-jose[cryptography]>=3.3.0; extra == "server"
+Requires-Dist: passlib[bcrypt]>=1.7.4; extra == "server"
+Requires-Dist: SQLAlchemy>=1.4.0; extra == "server"
+Requires-Dist: cachetools>=5.0.0; extra == "server"
+Provides-Extra: code
+Requires-Dist: PyExecJS; extra == "code"
+Provides-Extra: http
+Requires-Dist: requests; extra == "http"
+Requires-Dist: aiohttp>=3.8.0; extra == "http"
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: fakeredis; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: mypy; extra == "lint"
+Requires-Dist: flake8; extra == "lint"
+Requires-Dist: black; extra == "lint"
+Provides-Extra: all
+Requires-Dist: plaita[code,http,redis,server,yaml]; extra == "all"

plaita-0.4.0/plaita/__init__.py

@@ -0,0 +1,178 @@
+__version__ = "0.3.16"
+
+import logging as _logging
+
+_logger = _logging.getLogger(__name__)
+
+_EXTRAS_GUIDE = {
+    "redis": ("redis", "pip install plaita[redis]"),
+    "server": ("fastapi", "pip install plaita[server]"),
+    "code": ("execjs", "pip install plaita[code]"),
+    "http": ("requests", "pip install plaita[http]"),
+}
+
+
+def _emit_extras_guidance():
+    """Log guidance once when optional extras are missing, at DEBUG level."""
+    missing = []
+    for extra, (probe_module, install_cmd) in _EXTRAS_GUIDE.items():
+        try:
+            __import__(probe_module)
+        except ImportError:
+            missing.append((extra, install_cmd))
+    if missing:
+        names = ", ".join(name for name, _ in missing)
+        _logger.debug(
+            "Optional plaita extras not installed: %s. "
+            "Install what you need, e.g.: pip install plaita[all]",
+            names,
+        )
+
+
+_emit_extras_guidance()
+
+
+def _check_extra_available(extra_name: str) -> bool:
+    """Check if a specific extra dependency group is available.
+
+    Returns True if the probe module for the extra can be imported.
+    Raises ImportError with an actionable message if not.
+    """
+    if extra_name not in _EXTRAS_GUIDE:
+        return True
+    probe_module, install_cmd = _EXTRAS_GUIDE[extra_name]
+    try:
+        __import__(probe_module)
+        return True
+    except ImportError:
+        raise ImportError(
+            f"The '{extra_name}' extra is required for this feature but is not installed. "
+            f"Install it with: {install_cmd}\n"
+            f"Or install all extras: pip install plaita[all]"
+        )
+
+
+# 依赖反转: 注册一个 lazy 的默认 event bus provider, 让 plaita.core.context
+# 在需要时自动取默认总线, 而 core 层不必 import plaita.event (避免 core→event
+# 反向依赖)。provider 仅在第一次被调用时才 import plaita.event。
+def _default_event_bus_provider():
+    from plaita.event import get_default_event_bus
+    return get_default_event_bus()
+
+
+def _register_default_event_bus_provider() -> None:
+    try:
+        from plaita.core.context import set_default_event_bus_provider
+        set_default_event_bus_provider(_default_event_bus_provider)
+    except Exception:
+        _logger.debug("Unable to register default event bus provider", exc_info=True)
+
+
+_register_default_event_bus_provider()
+
+
+# Upgrade guide: provide clear error messages when accessing optional features
+# without the corresponding extras installed. Consumed by __getattr__ below.
+_FEATURE_EXTRAS_MAP = {
+    "FlowWorker": "server",
+    "ManagementAPI": "server",
+    "RedisStorage": "redis",
+    "RedisEventBus": "redis",
+    "CodeNode": "code",
+    "HTTP": "http",
+}
+
+# Canonical home for each lazily re-exported public name. Kept explicit so
+# that `from plaita import Flow` works out of the box without eagerly pulling
+# the core layer into memory at package import time.
+_LAZY_EXPORTS = {
+    # plaita.core.flow
+    "Flow": "plaita.core.flow",
+    "parse": "plaita.core.flow",
+    "parse_and_run": "plaita.core.flow",
+    # plaita.core.executor
+    "FlowExecution": "plaita.core.executor",
+    "ExecutionMode": "plaita.core.executor",
+    # plaita.core.errors
+    "FlowExecutionException": "plaita.core.errors",
+    "FlowErrorType": "plaita.core.errors",
+    "FlowResultError": "plaita.core.errors",
+    "NodeException": "plaita.core.errors",
+    "ErrorStrategy": "plaita.core.errors",
+    "ErrorHandler": "plaita.core.errors",
+    "RecoverableErrorHandler": "plaita.core.errors",
+    # plaita.core.callback
+    "FlowCallback": "plaita.core.callback",
+    "FlowEvent": "plaita.core.callback",
+    "CallbackManager": "plaita.core.callback",
+    "BaseCallbackManager": "plaita.core.callback",
+    "LoggerCallback": "plaita.core.callback",
+    # plaita.node
+    "Node": "plaita.node",
+    "node_register": "plaita.node",
+    "parse_node": "plaita.node",
+    "nodes": "plaita.node",
+    "NodeRegistry": "plaita.node",
+    "get_default_registry": "plaita.node",
+}
+
+# For optional-feature names: once the required extra is confirmed available,
+# the name lives in this canonical module. ``HTTP`` (not ``HTTPNode``) is the
+# real class name exported by ``plaita.node.http``.
+_EXTRA_EXPORTS = {
+    "FlowWorker": "plaita.server.flow_worker",
+    "ManagementAPI": "plaita.server.control",
+    "RedisStorage": "plaita.storage.redis",
+    "RedisEventBus": "plaita.event.redis",
+    "CodeNode": "plaita.node.code",
+    "HTTP": "plaita.node.http",
+}
+
+
+def __getattr__(name: str):
+    """Lazy top-level re-exports + actionable extras guidance.
+
+    - ``from plaita import Flow`` / ``parse`` / ``Node`` / ``node_register`` ...
+      resolve to the canonical ``plaita.core.*`` / ``plaita.node`` symbols without
+      importing the core layer at package import time.
+    - ``from plaita import types`` returns the ``plaita.core.types`` module so the
+      deprecated ``plaita.types`` shim is NOT triggered.
+    - Optional features (``FlowWorker``, ``HTTP``, ``RedisEventBus`` ...) raise
+      a clear ImportError naming the missing extra instead of a bare ImportError.
+    """
+    import importlib
+
+    if name in _LAZY_EXPORTS:
+        module = importlib.import_module(_LAZY_EXPORTS[name])
+        value = getattr(module, name)
+        globals()[name] = value  # cache so subsequent access bypasses __getattr__
+        return value
+
+    if name == "types":
+        module = importlib.import_module("plaita.core.types")
+        globals()["types"] = module
+        return module
+
+    if name in _FEATURE_EXTRAS_MAP:
+        # Raises an actionable ImportError if the extra is missing.
+        _check_extra_available(_FEATURE_EXTRAS_MAP[name])
+        module = importlib.import_module(_EXTRA_EXPORTS[name])
+        value = getattr(module, name)
+        globals()[name] = value
+        return value
+
+    raise AttributeError(f"module 'plaita' has no attribute {name!r}")
+
+
+def __dir__():
+    """Make lazy re-exports discoverable by IDEs / ``dir(plaita)``."""
+    return sorted(
+        set(globals())
+        | set(_LAZY_EXPORTS)
+        | set(_FEATURE_EXTRAS_MAP)
+        | {"types"}
+    )
+
+
+if __name__ == "__main__":
+    print(__version__)

plaita-0.4.0/plaita/client.py

@@ -0,0 +1,407 @@
+import hashlib
+import hmac
+import json
+import logging
+from threading import Lock
+from time import time
+from typing import Any, Dict, Optional, Union
+from urllib.parse import urlencode
+
+import requests
+
+from plaita.flow import Flow
+
+# 获取logger
+logger = logging.getLogger("plaita.client")
+
+# Constants
+DEFAULT_SIGNATURE_EXPIRATION = 3  # 3 seconds
+DEFAULT_REDIS_TTL = 3600  # 1 hour cache TTL in Redis
+# 默认指向本仓库 plaita-console 控制台提供的流程定义契约接口
+# （POST /api/flowVersion/semver/detail，HMAC 鉴权）。可通过 url 参数覆盖。
+DEFAULT_CONSOLE_URL = "http://localhost:8080/api/flowVersion/semver/detail"
+
+
+def _get_config_key(flow_id, version):
+    return f"flow:{flow_id}:{version}"
+
+
+class RedisConfig:
+    """Redis 配置类"""
+    
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 6379,
+        db: int = 0,
+        password: Optional[str] = None,
+        socket_timeout: float = 5.0,
+        socket_connect_timeout: float = 5.0,
+        decode_responses: bool = True,
+        **kwargs
+    ):
+        self.host = host
+        self.port = port
+        self.db = db
+        self.password = password
+        self.socket_timeout = socket_timeout
+        self.socket_connect_timeout = socket_connect_timeout
+        self.decode_responses = decode_responses
+        self.extra_options = kwargs
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """转换为字典格式"""
+        config = {
+            "host": self.host,
+            "port": self.port,
+            "db": self.db,
+            "socket_timeout": self.socket_timeout,
+            "socket_connect_timeout": self.socket_connect_timeout,
+            "decode_responses": self.decode_responses,
+        }
+        if self.password:
+            config["password"] = self.password
+        config.update(self.extra_options)
+        return config
+
+
+class PlaitaClient:
+    """
+    Plaita 客户端，用于从远程服务获取流程定义并执行
+    
+    支持多级缓存：
+    1. 内存缓存（最快）
+    2. Redis缓存（可选，跨进程共享）
+    3. 远程服务（最新数据）
+    
+    使用示例：
+        # 基础用法
+        client = PlaitaClient(secret_id='xxx', secret_key='yyy', url='https://your-plaita-server/api/flowVersion/semver/detail')
+        result = client.run_flow('flow_id', '1.0.0', {"param": "value"})
+        
+        # 使用 Redis 缓存
+        client = PlaitaClient(
+            secret_id='xxx',
+            secret_key='yyy',
+            url='https://your-plaita-server/api/flowVersion/semver/detail',
+            redis_config=RedisConfig(host='localhost', port=6379)
+        )
+        
+        # 使用已有的 Redis 客户端
+        import redis
+        redis_client = redis.Redis(host='localhost', port=6379, decode_responses=True)
+        client = PlaitaClient(
+            secret_id='xxx',
+            secret_key='yyy',
+            url='https://your-plaita-server/api/flowVersion/semver/detail',
+            redis_client=redis_client
+        )
+    """
+    
+    def __init__(
+        self,
+        secret_id: str,
+        secret_key: str,
+        url: str = DEFAULT_CONSOLE_URL,
+        signature_validity: int = DEFAULT_SIGNATURE_EXPIRATION,
+        headers: Optional[Dict[str, str]] = None,
+        redis_client: Optional[Any] = None,
+        redis_config: Optional[Union[RedisConfig, Dict[str, Any]]] = None,
+        redis_ttl: int = DEFAULT_REDIS_TTL,
+    ):
+        """
+        初始化 PlaitaClient
+
+        Args:
+            secret_id: API 密钥 ID
+            secret_key: API 密钥
+            url: API 服务地址，默认指向本仓库 plaita-console 控制台的
+                ``/api/flowVersion/semver/detail`` 契约接口（本地部署）。
+                生产环境请通过该参数指向你部署的控制台地址。
+            signature_validity: 签名有效期（秒）
+            headers: 额外的请求头
+            redis_client: 已有的 Redis 客户端实例（优先使用）
+            redis_config: Redis 配置（当 redis_client 为 None 时使用）
+            redis_ttl: Redis 缓存过期时间（秒）
+        """
+        self.secret_id = secret_id
+        self.secret_key = secret_key
+        self.signature_validity = signature_validity
+        self.url = url
+        self.headers = headers if headers is not None else {}
+        self.redis_ttl = redis_ttl
+        self.memory_cache = {}
+        self.memory_cache_lock = Lock()
+        
+        # 初始化 Redis 客户端
+        self._redis_client = None
+        self._redis_available = False
+        
+        if redis_client is not None:
+            # 使用传入的 Redis 客户端
+            self._redis_client = redis_client
+            self._validate_redis_connection()
+        elif redis_config is not None:
+            # 根据配置创建 Redis 客户端
+            self._init_redis_from_config(redis_config)
+    
+    def _init_redis_from_config(self, config: Union[RedisConfig, Dict[str, Any]]) -> None:
+        """
+        根据配置初始化 Redis 客户端
+        
+        Args:
+            config: Redis 配置对象或字典
+        """
+        try:
+            import redis
+        except ImportError:
+            logger.warning("Redis 库未安装，Redis 缓存将不可用。请运行: pip install redis")
+            return
+        
+        try:
+            if isinstance(config, dict):
+                config = RedisConfig(**config)
+            
+            self._redis_client = redis.Redis(**config.to_dict())
+            self._validate_redis_connection()
+        except Exception as e:
+            logger.warning(f"初始化 Redis 客户端失败: {e}")
+            self._redis_client = None
+            self._redis_available = False
+    
+    def _validate_redis_connection(self) -> bool:
+        """
+        验证 Redis 连接是否可用
+        
+        Returns:
+            bool: 连接是否可用
+        """
+        if self._redis_client is None:
+            self._redis_available = False
+            return False
+        
+        try:
+            self._redis_client.ping()
+            self._redis_available = True
+            logger.info("Redis 连接验证成功")
+            return True
+        except Exception as e:
+            logger.warning(f"Redis 连接验证失败: {e}")
+            self._redis_available = False
+            return False
+    
+    @property
+    def redis_client(self) -> Optional[Any]:
+        """获取 Redis 客户端（兼容旧代码）"""
+        return self._redis_client if self._redis_available else None
+
+    def run_flow(self, flow_id: str, version: str, input_data: Optional[Dict] = None):
+        """
+        获取并执行流程
+        
+        Args:
+            flow_id: 流程 ID
+            version: 流程版本
+            input_data: 输入参数
+            
+        Returns:
+            流程执行结果
+        """
+        flow = self.get_flow(flow_id, version)
+        return flow.run(input_data)
+
+    def get_flow(self, flow_id: str, version: str) -> Flow:
+        """
+        获取流程定义
+        
+        优先级：内存缓存 > Redis缓存 > 远程服务
+        
+        Args:
+            flow_id: 流程 ID
+            version: 流程版本
+            
+        Returns:
+            Flow: 流程对象
+        """
+        cache_key = _get_config_key(flow_id, version)
+        
+        # 1. 优先从内存缓存获取
+        with self.memory_cache_lock:
+            cached_flow = self.memory_cache.get(cache_key)
+            if cached_flow:
+                logger.debug(f"从内存缓存获取流程: {cache_key}")
+                return cached_flow
+
+        # 2. 尝试从 Redis 缓存获取
+        if self._redis_available and self._redis_client:
+            try:
+                config_data = self._redis_client.get(cache_key)
+                if config_data:
+                    logger.debug(f"从 Redis 缓存获取流程: {cache_key}")
+                    flow_obj = Flow.model_validate_json(json.loads(config_data))
+                    # 更新内存缓存
+                    with self.memory_cache_lock:
+                        self.memory_cache[cache_key] = flow_obj
+                    return flow_obj
+            except Exception as e:
+                logger.warning(f"从 Redis 获取缓存失败: {e}")
+
+        # 3. 从远程服务获取
+        logger.debug(f"从远程服务获取流程: {cache_key}")
+        flow_data = self._fetch_flow(flow_id, version)
+        flow_obj = Flow.model_validate_json(flow_data)
+        
+        # 更新缓存
+        self._update_cache(cache_key, flow_obj, flow_data)
+        
+        return flow_obj
+    
+    def _update_cache(self, cache_key: str, flow_obj: Flow, flow_data: Any) -> None:
+        """
+        更新缓存
+        
+        Args:
+            cache_key: 缓存键
+            flow_obj: 流程对象
+            flow_data: 原始流程数据
+        """
+        # 更新内存缓存
+        with self.memory_cache_lock:
+            self.memory_cache[cache_key] = flow_obj
+        
+        # 更新 Redis 缓存
+        if self._redis_available and self._redis_client:
+            try:
+                self._redis_client.set(
+                    cache_key, 
+                    json.dumps(flow_data),
+                    ex=self.redis_ttl  # 设置过期时间
+                )
+                logger.debug(f"已更新 Redis 缓存: {cache_key}, TTL: {self.redis_ttl}s")
+            except Exception as e:
+                logger.warning(f"更新 Redis 缓存失败: {e}")
+    
+    def clear_cache(self, flow_id: Optional[str] = None, version: Optional[str] = None) -> int:
+        """
+        清除缓存
+        
+        Args:
+            flow_id: 流程 ID（可选，不指定则清除所有）
+            version: 流程版本（可选）
+            
+        Returns:
+            int: 清除的缓存项数量
+        """
+        cleared_count = 0
+        
+        if flow_id and version:
+            # 清除特定版本的缓存
+            cache_key = _get_config_key(flow_id, version)
+            with self.memory_cache_lock:
+                if cache_key in self.memory_cache:
+                    del self.memory_cache[cache_key]
+                    cleared_count += 1
+            
+            if self._redis_available and self._redis_client:
+                try:
+                    self._redis_client.delete(cache_key)
+                except Exception as e:
+                    logger.warning(f"清除 Redis 缓存失败: {e}")
+        else:
+            # 清除所有缓存
+            with self.memory_cache_lock:
+                cleared_count = len(self.memory_cache)
+                self.memory_cache.clear()
+            
+            logger.info(f"已清除 {cleared_count} 个内存缓存项")
+        
+        return cleared_count
+
+    def _fetch_flow(self, flow_id: str, version: str) -> Any:
+        """
+        从远程服务获取流程定义
+        
+        Args:
+            flow_id: 流程 ID
+            version: 流程版本
+            
+        Returns:
+            解析后的流程定义数据
+            
+        Raises:
+            Exception: 获取流程失败时抛出异常
+        """
+        data = {"flowId": flow_id, "version": version}
+        headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Authorization": generate_signature(self.secret_key, self.secret_id, self.signature_validity, int(time())),
+        }
+        headers.update(self.headers)  # 合并额外的请求头
+        
+        try:
+            response = requests.post(self.url, headers=headers, data=data, timeout=30)
+        except requests.exceptions.Timeout:
+            raise Exception(f"请求超时: flow_id={flow_id}, version={version}")
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"请求失败: {e}")
+        
+        if response.status_code != 200:
+            raise Exception(f"获取流程配置失败, HTTP状态码: {response.status_code}")
+        
+        try:
+            response_data = response.json()
+        except json.JSONDecodeError:
+            raise Exception("响应数据不是有效的 JSON 格式")
+        
+        if response_data.get("code"):
+            raise Exception(f"获取流程配置失败: {response_data.get('message', '未知错误')}")
+        
+        if response_data.get("data") is None:
+            raise Exception("获取流程配置失败: 响应数据为空")
+
+        flow_str = response_data["data"].get("flow")
+        if not flow_str:
+            raise Exception("获取流程配置失败: flow 字段为空")
+        
+        logger.debug(f"成功获取流程定义: flow_id={flow_id}, version={version}")
+        return json.loads(flow_str)
+
+
+def generate_signature(secret_key: str, secret_id: str, signature_validity: int, sign_time: int) -> str:
+    """
+    生成 API 请求签名
+    
+    Args:
+        secret_key: API 密钥
+        secret_id: API 密钥 ID
+        signature_validity: 签名有效期（秒）
+        sign_time: 签名时间戳
+        
+    Returns:
+        str: URL 编码的签名字符串
+    """
+    signature_validity = max(DEFAULT_SIGNATURE_EXPIRATION, signature_validity)
+
+    sign_expire = sign_time + signature_validity
+    key_time = f"{sign_time};{sign_expire}"
+
+    key = hmac.new(secret_key.encode(), key_time.encode(), hashlib.sha256)
+    key_string = key.hexdigest()
+
+    string_to_sign = f"{sign_time}\n"
+    signature_key = hmac.new(key_string.encode(), string_to_sign.encode(), hashlib.sha256)
+    sign = signature_key.hexdigest()
+
+    data = urlencode({"secret-id": secret_id, "sign-time": str(sign_time), "key-time": key_time, "signature": sign})
+    return data
+
+
+# Example Usage
+#
+# client = PlaitaClient(
+#  'your secret id',
+#  'your secret key',
+#  url='https://your-plaita-server/api/flowVersion/semver/detail',
+# )
+# result = client.run_flow('259', '0.0.2', {"age": 14})
+# print(result)