qmt-sdk 0.3.0__py3-none-any.whl

qmt_sdk/__init__.py

@@ -0,0 +1,29 @@
+"""Unified QMT SDK.
+
+The SDK exposes one client for QMT and MiniQMT backends.  The existing
+``xtquant_compat`` module remains available as a migration surface, while new
+code should use the domain clients below.
+"""
+
+from .client import QmtClient
+from .bridge import configure
+import os
+import sys
+import sysconfig
+
+
+def get_template_dir():
+    """Return the installed directory containing QMT strategy templates."""
+    candidates = []
+    data_root = sysconfig.get_path("data")
+    if data_root:
+        candidates.append(os.path.join(data_root, "qmt_strategy"))
+    # Source checkouts remain directly usable without building a wheel.
+    candidates.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", "qmt_strategy")))
+    for path in candidates:
+        if os.path.isfile(os.path.join(path, "XTQUANT_COMPAT_BRIDGE.py")):
+            return path
+    raise FileNotFoundError("QMT strategy templates are not installed")
+
+__all__ = ["QmtClient", "configure", "get_template_dir"]
+__version__ = "0.3.0"

qmt_sdk/api_surface.py

@@ -0,0 +1,48 @@
+"""Install environment-dependent adapters from the official API snapshot."""
+
+import inspect
+import json
+from importlib import resources
+
+
+def load_official_api_spec():
+    with resources.open_text("xtquant_compat", "official_xtdata_api.json", encoding="utf-8") as stream:
+        return json.load(stream)
+
+
+def _annotation(name):
+    return {"str": str, "list": list, "int": int, "float": float, "bool": bool}.get(name, name)
+
+
+def _signature(item):
+    parameters = []
+    for source in item["parameters"]:
+        kind = getattr(inspect.Parameter, source["kind"])
+        default = source.get("default", inspect.Parameter.empty)
+        annotation = _annotation(source["annotation"]) if "annotation" in source else inspect.Parameter.empty
+        parameters.append(inspect.Parameter(
+            source["name"], kind=kind, default=default, annotation=annotation,
+        ))
+    return inspect.Signature(parameters)
+
+
+def install_missing_api(module_globals, request):
+    spec = load_official_api_spec()
+    for item in spec["functions"]:
+        name = item["name"]
+        if callable(module_globals.get(name)):
+            continue
+        signature = _signature(item)
+
+        def adapter(*args, __name=name, __signature=signature, **kwargs):
+            bound = __signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            return request(__name, **bound.arguments)
+
+        adapter.__name__ = name
+        adapter.__qualname__ = name
+        adapter.__doc__ = "Environment-dependent adapter for xtquant.xtdata.%s." % name
+        adapter.__module__ = module_globals.get("__name__", "xtquant_compat.xtdata")
+        adapter.__signature__ = signature
+        module_globals[name] = adapter
+    return spec

qmt_sdk/backends/__init__.py

@@ -0,0 +1,4 @@
+from .qmt import QmtBackend
+from .miniqmt import MiniQmtBackend
+
+__all__ = ["QmtBackend", "MiniQmtBackend"]

qmt_sdk/backends/miniqmt.py

@@ -0,0 +1,11 @@
+"""MiniQMT backend.
+
+The initial implementation shares the same client contract. A direct native
+MiniQMT transport can be added later without changing domain clients.
+"""
+
+from .qmt import QmtBackend
+
+
+class MiniQmtBackend(QmtBackend):
+    pass

qmt_sdk/backends/qmt.py

@@ -0,0 +1,27 @@
+"""QMT runtime backend using the shared file bridge."""
+
+from .. import data
+from ..bridge import get_client
+
+
+class QmtBackend:
+    """Backend that exposes the unified request operations."""
+
+    def call(self, method, *args, **kwargs):
+        # Typed market methods use the native query path directly.  This
+        # avoids legacy xtdata wrappers in the embedded runtime (some builds
+        # import pandas there) and preserves QMT's raw payload.
+        if method in ("get_market_data_ex", "get_market_data") and args:
+            names = ("fields", "stock_code", "period", "start_time", "end_time",
+                     "count", "dividend_type", "fill_data")
+            if method == "get_market_data_ex":
+                names += ("subscribe",)
+            params = dict(zip(names, args))
+            params.update(kwargs)
+            return self.query(method, params)
+        function = getattr(data, method)
+        return function(*args, **kwargs)
+
+    def query(self, method, params=None, timeout=None):
+        """Call a query method through the shared bridge without xtquant shaping."""
+        return get_client().request(method, params or {}, timeout=timeout)

qmt_sdk/bridge/__init__.py

@@ -0,0 +1,6 @@
+"""Shared file bridge transport used by all qmt_sdk domains."""
+
+from .client import FileBridgeClient, get_client, reset_client
+from .config import configure, get_config
+
+__all__ = ["FileBridgeClient", "get_client", "reset_client", "configure", "get_config"]

qmt_sdk/bridge/client.py

@@ -0,0 +1,179 @@
+import os
+import json
+import pickle
+import threading
+import time
+import uuid
+
+from .config import get_config
+from .exceptions import BridgeRemoteError, BridgeTimeoutError
+from .protocol import PROTOCOL_VERSION, atomic_write_json, read_json
+
+
+class FileBridgeClient:
+    def __init__(self, config):
+        self.config = config
+        self.client_id = "%s-%s" % (os.getpid(), uuid.uuid4().hex)
+        self._callbacks = {}
+        self._stop = threading.Event()
+        self._event_thread = None
+        for name in ("requests", "responses", "errors", "events", "processed", "cancellations", "status"):
+            os.makedirs(os.path.join(config.root, name), exist_ok=True)
+
+    def request(self, method, params=None, timeout=None):
+        request_id = uuid.uuid4().hex
+        filename = "REQ_%s.json" % request_id
+        payload = {
+            "protocol_version": PROTOCOL_VERSION,
+            "request_id": request_id,
+            "client_id": self.client_id,
+            "method": method,
+            "params": params or {},
+            "created_at": time.time(),
+        }
+        atomic_write_json(os.path.join(self.config.root, "requests", filename), payload)
+        atomic_write_json(os.path.join(self.config.root, "status", request_id + ".json"), {
+            "request_id": request_id, "state": "pending", "processed": 0,
+            "total": 0, "failed": 0, "created_at": payload["created_at"],
+        })
+        deadline = time.monotonic() + (self.config.timeout if timeout is None else float(timeout))
+        try:
+            while time.monotonic() < deadline:
+                for folder in ("responses", "errors"):
+                    path = os.path.join(self.config.root, folder, filename)
+                    if not os.path.exists(path):
+                        continue
+                    try:
+                        result = read_json(path)
+                    except (OSError, ValueError, json.JSONDecodeError):
+                        time.sleep(min(self.config.poll_interval, 0.05))
+                        continue
+                    try:
+                        os.remove(path)
+                    except OSError:
+                        pass
+                    if folder == "errors" or not result.get("ok", False):
+                        if result.get("cancelled"):
+                            from .exceptions import BridgeCancelledError
+                            raise BridgeCancelledError(result.get("error") or "request cancelled")
+                        message = result.get("error") or "unknown QMT bridge error"
+                        if "NotImplementedError" in message or "unavailable" in message.lower():
+                            from .exceptions import BridgeMethodNotSupportedError
+                            raise BridgeMethodNotSupportedError(message)
+                        raise BridgeRemoteError(message)
+                    if result.get("data_format") == "pickle-v1":
+                        binary_name = os.path.basename(str(result.get("data_file", "")))
+                        binary_path = os.path.join(self.config.root, "responses", binary_name)
+                        try:
+                            with open(binary_path, "rb") as stream:
+                                return pickle.load(stream)
+                        finally:
+                            try:
+                                os.remove(binary_path)
+                            except OSError:
+                                pass
+                    return result.get("data")
+                time.sleep(self.config.poll_interval)
+        except KeyboardInterrupt:
+            self.cancel(request_id)
+            raise
+        self.cancel(request_id)
+        raise BridgeTimeoutError("timeout waiting for %s (%s)" % (method, request_id))
+
+    def cancel(self, request_id):
+        atomic_write_json(os.path.join(self.config.root, "cancellations", request_id + ".json"), {
+            "request_id": request_id, "created_at": time.time(),
+        })
+
+    def request_status(self, request_id):
+        path = os.path.join(self.config.root, "status", str(request_id) + ".json")
+        if not os.path.exists(path):
+            return None
+        try:
+            return read_json(path)
+        except (OSError, ValueError, json.JSONDecodeError):
+            return None
+
+    def subscribe_method(self, method, params, callback):
+        result = self.request(method, params)
+        subscription_id = result.get("subscription_id") if isinstance(result, dict) else result
+        if callback is not None:
+            self._callbacks[str(subscription_id)] = callback
+            self._ensure_event_thread()
+        return subscription_id
+
+    def subscribe(self, stock_code, period, start_time, end_time, count, callback):
+        return self.subscribe_method("subscribe_quote", {
+            "stock_code": stock_code,
+            "period": period,
+            "start_time": start_time,
+            "end_time": end_time,
+            "count": count,
+        }, callback)
+
+    def unsubscribe(self, subscription_id):
+        return self.unsubscribe_method("unsubscribe_quote", subscription_id)
+
+    def unsubscribe_method(self, method, subscription_id, parameter="subscription_id"):
+        self._callbacks.pop(str(subscription_id), None)
+        return self.request(method, {parameter: subscription_id})
+
+    def _ensure_event_thread(self):
+        if self._event_thread and self._event_thread.is_alive():
+            return
+        self._stop.clear()
+        self._event_thread = threading.Thread(target=self._event_loop, name="xtquant-compat-events", daemon=True)
+        self._event_thread.start()
+
+    def _event_loop(self):
+        event_root = os.path.join(self.config.root, "events", self.client_id)
+        processed_root = os.path.join(self.config.root, "processed", self.client_id)
+        while not self._stop.wait(self.config.poll_interval):
+            if not os.path.isdir(event_root):
+                continue
+            for subscription_id in sorted(os.listdir(event_root)):
+                folder = os.path.join(event_root, subscription_id)
+                if not os.path.isdir(folder):
+                    continue
+                callback = self._callbacks.get(subscription_id)
+                if callback is None:
+                    continue
+                for name in sorted(n for n in os.listdir(folder) if n.endswith(".json")):
+                    source = os.path.join(folder, name)
+                    try:
+                        event = read_json(source)
+                        callback(event.get("data"))
+                        destination = os.path.join(processed_root, subscription_id, name)
+                        os.makedirs(os.path.dirname(destination), exist_ok=True)
+                        os.replace(source, destination)
+                    except FileNotFoundError:
+                        continue
+                    except Exception:
+                        # Keep the event for at-least-once retry after callback failure.
+                        time.sleep(self.config.poll_interval)
+                        break
+
+    def close(self):
+        self._stop.set()
+        if self._event_thread and self._event_thread.is_alive():
+            self._event_thread.join(timeout=1)
+
+
+_client = None
+_client_lock = threading.Lock()
+
+
+def get_client():
+    global _client
+    with _client_lock:
+        if _client is None:
+            _client = FileBridgeClient(get_config())
+        return _client
+
+
+def reset_client():
+    global _client
+    with _client_lock:
+        if _client is not None:
+            _client.close()
+        _client = None

qmt_sdk/bridge/config.py

@@ -0,0 +1,38 @@
+import os
+import threading
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class Config:
+    root: str = os.environ.get(
+        "XTQUANT_COMPAT_ROOT", r"D:\FinTools\QMT\xtquant_compat_bridge",
+    )
+    timeout: float = float(os.environ.get("XTQUANT_COMPAT_TIMEOUT", "30"))
+    poll_interval: float = float(os.environ.get("XTQUANT_COMPAT_POLL_INTERVAL", "0.05"))
+
+
+_lock = threading.Lock()
+_config = Config()
+
+
+def configure(root=None, timeout=None, poll_interval=None):
+    """Configure the global file transport and reset the active client."""
+    global _config
+    changes = {}
+    if root is not None:
+        changes["root"] = os.path.abspath(os.fspath(root))
+    if timeout is not None:
+        changes["timeout"] = float(timeout)
+    if poll_interval is not None:
+        changes["poll_interval"] = float(poll_interval)
+    with _lock:
+        _config = replace(_config, **changes)
+    from .client import reset_client
+    reset_client()
+    return _config
+
+
+def get_config():
+    with _lock:
+        return _config

qmt_sdk/bridge/exceptions.py

@@ -0,0 +1,26 @@
+class XtQuantCompatError(RuntimeError):
+    """Base error raised by xtquant-compat."""
+
+
+class BridgeTimeoutError(XtQuantCompatError, TimeoutError):
+    """The QMT bridge did not respond before the configured timeout."""
+
+
+class BridgeRemoteError(XtQuantCompatError):
+    """The QMT bridge returned an exception."""
+
+
+class BridgeCancelledError(XtQuantCompatError):
+    """A long-running bridge request was cancelled."""
+
+
+class BridgeUnavailableError(XtQuantCompatError):
+    """The file bridge is not running or has restarted."""
+
+
+class BridgeMethodNotSupportedError(BridgeRemoteError):
+    """The active QMT build does not expose the requested method."""
+
+
+class BridgePartialResultError(BridgeRemoteError):
+    """A request returned only a partial result."""

qmt_sdk/bridge/protocol.py

@@ -0,0 +1,20 @@
+import json
+import os
+import uuid
+
+PROTOCOL_VERSION = 1
+
+
+def atomic_write_json(path, payload):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temp = "%s.%s.tmp" % (path, uuid.uuid4().hex)
+    with open(temp, "w", encoding="utf-8") as stream:
+        json.dump(payload, stream, ensure_ascii=False, separators=(",", ":"))
+        stream.flush()
+        os.fsync(stream.fileno())
+    os.replace(temp, path)
+
+
+def read_json(path):
+    with open(path, "r", encoding="utf-8") as stream:
+        return json.load(stream)

qmt_sdk/client.py

@@ -0,0 +1,43 @@
+"""High-level QMT client facade backed by the existing bridge client."""
+
+from .backends import MiniQmtBackend, QmtBackend
+from .financial import FinancialClient
+from .instruments import InstrumentClient
+from .jobs import JobClient
+from .market import MarketClient
+from .qmt import QmtQueryClient
+
+
+class QmtClient:
+    """Unified domain-oriented client.
+
+    ``backend`` is reserved for future direct MiniQMT/QMT selection; the
+    current implementation uses the configured file bridge for both.
+    """
+
+    def __init__(self, backend="qmt"):
+        if hasattr(backend, "call"):
+            self.backend_name = "custom"
+            self.backend = backend
+        elif backend in ("qmt", "auto"):
+            self.backend_name = "qmt"
+            self.backend = QmtBackend()
+        elif backend in ("mini", "miniqmt"):
+            self.backend_name = "miniqmt"
+            self.backend = MiniQmtBackend()
+        else:
+            raise ValueError("unsupported backend: %s" % backend)
+        self.market = MarketClient(self.backend)
+        self.financial = FinancialClient(self.backend)
+        self.instruments = InstrumentClient(self.backend)
+        self.jobs = JobClient(self.backend)
+        self.qmt = QmtQueryClient(self)
+
+    def query(self, method, params=None, timeout=None):
+        """Invoke a query capability by bridge method name.
+
+        This is the extension point for QMT-native read APIs that do not have
+        a MiniQMT equivalent yet. Domain clients should be preferred once a
+        capability has stable parameters and return semantics.
+        """
+        return self.backend.query(method, params=params, timeout=timeout)