lib-x17-fintech 2.1.3__py3-none-any.whl

xfintech/data/job/tests/test_class_joblike_all.py

@@ -0,0 +1,482 @@
+"""
+Test suite for JobLike Protocol
+Tests cover protocol definition, compliance checking, and structural typing
+"""
+
+from typing import Any, Dict
+
+from xfintech.data.job.joblike import JobLike
+
+# ============================================================================
+# Helper Classes for Testing
+# ============================================================================
+
+
+class CompliantJob:
+    """Class that implements JobLike protocol"""
+
+    def run(self) -> Any:
+        return self._run()
+
+    def _run(self) -> Any:
+        return {"result": "success"}
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": "CompliantJob", "type": "test"}
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"name": "CompliantJob", "status": "active"}
+
+
+class PartialJob:
+    """Class that partially implements JobLike protocol"""
+
+    def run(self) -> Any:
+        return "result"
+
+    def _run(self) -> Any:
+        return "internal"
+
+    def describe(self) -> Dict[str, Any]:
+        return {"name": "PartialJob"}
+
+    # Missing to_dict method
+
+
+class NonCompliantJob:
+    """Class that doesn't implement JobLike protocol"""
+
+    def execute(self) -> Any:
+        return "result"
+
+
+class MinimalJob:
+    """Minimal implementation of JobLike"""
+
+    def run(self):
+        return None
+
+    def _run(self):
+        return None
+
+    def describe(self):
+        return {}
+
+    def to_dict(self):
+        return {}
+
+
+# ============================================================================
+# Protocol Compliance Tests
+# ============================================================================
+
+
+def test_joblike_compliant_job():
+    """Test that compliant class is recognized as JobLike"""
+    job = CompliantJob()
+    assert isinstance(job, JobLike)
+
+
+def test_joblike_partial_job():
+    """Test that partial implementation is not recognized as JobLike"""
+    job = PartialJob()
+    # Missing to_dict, so should not be fully compliant
+    # Note: runtime_checkable only checks for method existence
+    assert isinstance(job, JobLike) is False
+
+
+def test_joblike_non_compliant_job():
+    """Test that non-compliant class is not recognized as JobLike"""
+    job = NonCompliantJob()
+    assert isinstance(job, JobLike) is False
+
+
+def test_joblike_minimal_job():
+    """Test minimal implementation is recognized as JobLike"""
+    job = MinimalJob()
+    assert isinstance(job, JobLike)
+
+
+# ============================================================================
+# Protocol Method Tests
+# ============================================================================
+
+
+def test_joblike_has_run_method():
+    """Test JobLike protocol requires run method"""
+    job = CompliantJob()
+    assert hasattr(job, "run")
+    assert callable(job.run)
+
+
+def test_joblike_has_private_run_method():
+    """Test JobLike protocol requires _run method"""
+    job = CompliantJob()
+    assert hasattr(job, "_run")
+    assert callable(job._run)
+
+
+def test_joblike_has_describe_method():
+    """Test JobLike protocol requires describe method"""
+    job = CompliantJob()
+    assert hasattr(job, "describe")
+    assert callable(job.describe)
+
+
+def test_joblike_has_to_dict_method():
+    """Test JobLike protocol requires to_dict method"""
+    job = CompliantJob()
+    assert hasattr(job, "to_dict")
+    assert callable(job.to_dict)
+
+
+# ============================================================================
+# Method Signature Tests
+# ============================================================================
+
+
+def test_joblike_run_returns_any():
+    """Test run method can return any type"""
+    job = CompliantJob()
+    result = job.run()
+    assert result is not None
+
+
+def test_joblike_private_run_returns_any():
+    """Test _run method can return any type"""
+    job = CompliantJob()
+    result = job._run()
+    assert result == {"result": "success"}
+
+
+def test_joblike_describe_returns_dict():
+    """Test describe method returns dict"""
+    job = CompliantJob()
+    result = job.describe()
+    assert isinstance(result, dict)
+    assert "name" in result
+
+
+def test_joblike_to_dict_returns_dict():
+    """Test to_dict method returns dict"""
+    job = CompliantJob()
+    result = job.to_dict()
+    assert isinstance(result, dict)
+    assert "name" in result
+
+
+# ============================================================================
+# Protocol Usage Tests
+# ============================================================================
+
+
+def test_joblike_as_type_annotation():
+    """Test JobLike can be used as type annotation"""
+
+    def process_job(job: JobLike) -> Dict[str, Any]:
+        return job.describe()
+
+    job = CompliantJob()
+    result = process_job(job)
+
+    assert isinstance(result, dict)
+    assert result["name"] == "CompliantJob"
+
+
+def test_joblike_type_checking():
+    """Test JobLike enables structural type checking"""
+
+    def execute_job(job: JobLike) -> Any:
+        return job.run()
+
+    compliant = CompliantJob()
+    result = execute_job(compliant)
+
+    assert result == {"result": "success"}
+
+
+def test_joblike_duck_typing():
+    """Test JobLike supports duck typing"""
+
+    class DuckTypedJob:
+        def run(self):
+            return "duck result"
+
+        def _run(self):
+            return "internal duck"
+
+        def describe(self):
+            return {"type": "duck"}
+
+        def to_dict(self):
+            return {"duck": True}
+
+    job = DuckTypedJob()
+    assert isinstance(job, JobLike)
+
+
+# ============================================================================
+# Protocol Instance Tests
+# ============================================================================
+
+
+def test_joblike_multiple_implementations():
+    """Test multiple classes can implement JobLike"""
+
+    class Job1:
+        def run(self):
+            return 1
+
+        def _run(self):
+            return 1
+
+        def describe(self):
+            return {}
+
+        def to_dict(self):
+            return {}
+
+    class Job2:
+        def run(self):
+            return 2
+
+        def _run(self):
+            return 2
+
+        def describe(self):
+            return {}
+
+        def to_dict(self):
+            return {}
+
+    job1 = Job1()
+    job2 = Job2()
+
+    assert isinstance(job1, JobLike)
+    assert isinstance(job2, JobLike)
+
+
+def test_joblike_inheritance_not_required():
+    """Test classes don't need to inherit from JobLike"""
+
+    class IndependentJob:
+        def run(self):
+            return "independent"
+
+        def _run(self):
+            return "internal"
+
+        def describe(self):
+            return {"independent": True}
+
+        def to_dict(self):
+            return {"independent": True}
+
+    job = IndependentJob()
+    # Should be recognized as JobLike due to structural typing
+    assert isinstance(job, JobLike)
+
+
+# ============================================================================
+# Edge Case Tests
+# ============================================================================
+
+
+def test_joblike_with_extra_methods():
+    """Test class with extra methods is still JobLike compliant"""
+
+    class ExtendedJob:
+        def run(self):
+            return "extended"
+
+        def _run(self):
+            return "internal"
+
+        def describe(self):
+            return {}
+
+        def to_dict(self):
+            return {}
+
+        def extra_method(self):
+            return "extra"
+
+        def another_method(self):
+            return "another"
+
+    job = ExtendedJob()
+    assert isinstance(job, JobLike)
+    assert hasattr(job, "extra_method")
+
+
+def test_joblike_with_properties():
+    """Test class with properties can be JobLike compliant"""
+
+    class PropertyJob:
+        def __init__(self):
+            self.name = "PropertyJob"
+
+        def run(self):
+            return self.name
+
+        def _run(self):
+            return self.name
+
+        def describe(self):
+            return {"name": self.name}
+
+        def to_dict(self):
+            return {"name": self.name}
+
+    job = PropertyJob()
+    assert isinstance(job, JobLike)
+
+
+def test_joblike_method_with_arguments():
+    """Test JobLike methods can accept arguments"""
+
+    class ArgJob:
+        def run(self, *args, **kwargs):
+            return "with args"
+
+        def _run(self, *args, **kwargs):
+            return "internal with args"
+
+        def describe(self, verbose=False):
+            return {"verbose": verbose}
+
+        def to_dict(self, include_meta=True):
+            return {"meta": include_meta}
+
+    job = ArgJob()
+    assert isinstance(job, JobLike)
+
+
+# ============================================================================
+# Protocol Validation Tests
+# ============================================================================
+
+
+def test_joblike_missing_run():
+    """Test class missing run method is not JobLike"""
+
+    class MissingRun:
+        def _run(self):
+            return None
+
+        def describe(self):
+            return {}
+
+        def to_dict(self):
+            return {}
+
+    job = MissingRun()
+    assert not isinstance(job, JobLike)
+
+
+def test_joblike_missing_private_run():
+    """Test class missing _run method is not JobLike"""
+
+    class MissingPrivateRun:
+        def run(self):
+            return None
+
+        def describe(self):
+            return {}
+
+        def to_dict(self):
+            return {}
+
+    job = MissingPrivateRun()
+    assert not isinstance(job, JobLike)
+
+
+def test_joblike_missing_describe():
+    """Test class missing describe method is not JobLike"""
+
+    class MissingDescribe:
+        def run(self):
+            return None
+
+        def _run(self):
+            return None
+
+        def to_dict(self):
+            return {}
+
+    job = MissingDescribe()
+    assert not isinstance(job, JobLike)
+
+
+def test_joblike_missing_to_dict():
+    """Test class missing to_dict method is not JobLike"""
+
+    class MissingToDict:
+        def run(self):
+            return None
+
+        def _run(self):
+            return None
+
+        def describe(self):
+            return {}
+
+    job = MissingToDict()
+    assert not isinstance(job, JobLike)
+
+
+# ============================================================================
+# Integration Tests
+# ============================================================================
+
+
+def test_joblike_function_parameter():
+    """Test JobLike as function parameter type"""
+
+    def execute_and_describe(job: JobLike) -> tuple:
+        result = job.run()
+        description = job.describe()
+        return result, description
+
+    job = CompliantJob()
+    result, desc = execute_and_describe(job)
+
+    assert result == {"result": "success"}
+    assert desc["name"] == "CompliantJob"
+
+
+def test_joblike_list_of_jobs():
+    """Test list of JobLike objects"""
+    jobs = [CompliantJob(), MinimalJob()]
+
+    for job in jobs:
+        assert isinstance(job, JobLike)
+        assert callable(job.run)
+
+
+def test_joblike_runtime_check():
+    """Test runtime_checkable allows isinstance checks"""
+
+    class RuntimeJob:
+        def run(self):
+            return "runtime"
+
+        def _run(self):
+            return "internal"
+
+        def describe(self):
+            return {"runtime": True}
+
+        def to_dict(self):
+            return {"runtime": True}
+
+    job = RuntimeJob()
+
+    # This works because Protocol is runtime_checkable
+    assert isinstance(job, JobLike)
+
+
+def test_joblike_protocol_documentation():
+    """Test JobLike protocol has documentation"""
+    assert JobLike.__doc__ is not None
+    assert "描述" in JobLike.__doc__

xfintech/data/relay/__init__.py

@@ -0,0 +1,7 @@
+from .client import RelayClient
+from .clientlike import RelayClientLike
+
+__all__ = [
+    "RelayClient",
+    "RelayClientLike",
+]

xfintech/data/relay/client.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+from xfintech.data.relay.clientlike import RelayClientLike
+
+
+class RelayClient(RelayClientLike):
+    """
+    描述:
+    - 中继客户端基类，提供通用的中继服务器连接功能。
+    - 实现 URL、密钥和超时时间的验证与解析。
+    - 提供规范化 JSON 序列化方法，确保数据格式一致性。
+    - 作为具体中继客户端实现的基础类，子类需实现 call() 方法。
+
+    属性:
+    - url: str, 中继服务器 URL 地址（自动移除尾部斜杠）。
+    - secret: str, 用于认证的密钥（自动去除首尾空格）。
+    - timeout: int, 请求超时时间（秒），默认 180 秒。
+    - DEFAULT_TIMEOUT: int = 180, 默认超时时间常量。
+
+    方法:
+    - canonical_json(value): 将数据转换为规范化的 JSON 字节串（键排序、无空格）。
+    - call(): 抽象方法，由子类实现具体的 API 调用逻辑。
+
+    例子:
+    ```python
+        from xfintech.data.relay.client import RelayClient
+
+        # 创建子类实现
+        class MyRelayClient(RelayClient):
+            def call(self):
+                # 实现具体的调用逻辑
+                return {"result": "success"}
+
+        # 使用客户端
+        client = MyRelayClient(
+            url="https://relay.example.com",
+            secret="my-secret-key",
+            timeout=120
+        )
+
+        # URL 自动处理尾部斜杠
+        print(client.url)  # 输出: https://relay.example.com
+
+        # 规范化 JSON 序列化
+        data = {"name": "test", "value": 42}
+        json_bytes = client.canonical_json(data)
+        print(json_bytes)  # 输出: b'{"name":"test","value":42}'
+    ```
+    """
+
+    DEFAULT_TIMEOUT = 180
+
+    def __init__(
+        self,
+        url: str,
+        secret: str,
+        timeout: Optional[int] = None,
+        **kwargs: Any,
+    ) -> None:
+        self.url = self._resolve_url(url)
+        self.secret = self._resolve_secret(secret)
+        self.timeout = self._resolve_timeout(timeout)
+
+    def _resolve_url(
+        self,
+        url: str,
+    ) -> str:
+        if not url:
+            msg = "Relay URL must be provided."
+            raise ValueError(msg)
+        return url.rstrip("/")
+
+    def _resolve_secret(
+        self,
+        secret: str,
+    ) -> str:
+        if not secret:
+            msg = "Relay secret must be provided."
+            raise ValueError(msg)
+        secret = secret.strip()
+        if not secret:
+            msg = "Relay secret must be provided."
+            raise ValueError(msg)
+        return secret
+
+    def _resolve_timeout(
+        self,
+        timeout: Optional[int],
+    ) -> int:
+        if not timeout:
+            return self.DEFAULT_TIMEOUT
+        if not isinstance(timeout, int):
+            msg = "Timeout must be an integer."
+            raise ValueError(msg)
+        if timeout <= 0:
+            return self.DEFAULT_TIMEOUT
+        return timeout
+
+    def canonical_json(
+        self,
+        value: Any,
+    ) -> bytes:
+        return json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("utf-8")
+
+    def call(self) -> Any:
+        raise NotImplementedError()

xfintech/data/relay/clientlike.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RelayClientLike(Protocol):
+    """
+    描述:
+    - 中继客户端协议接口，定义中继客户端必须实现的核心属性和方法。
+    - 使用 Protocol 实现结构化类型检查（structural typing）。
+    - 任何实现这些属性和方法的类都会被视为符合 RelayClientLike 协议。
+
+    属性:
+    - url: str, 中继服务器 URL 地址。
+    - secret: str, 用于认证的密钥。
+    - timeout: int, 请求超时时间（秒）。
+
+    方法:
+    - call(): 执行 API 调用并返回结果。
+
+    例子:
+    ```python
+        from xfintech.data.relay.clientlike import RelayClientLike
+
+        # 任何实现这些属性和方法的类都符合 RelayClientLike 协议
+        class MyClient:
+            def __init__(self):
+                self.url = "https://api.example.com"
+                self.secret = "my-secret"
+                self.timeout = 180
+
+            def call(self):
+                return {"result": "success"}
+
+        # 类型检查会通过
+        client: RelayClientLike = MyClient()
+    ```
+    """
+
+    url: str
+    secret: str
+    timeout: int
+
+    def call(self) -> Any: ...