pytdxfeed 0.2.0__py3-none-any.whl

pytdxfeed/__init__.py

@@ -0,0 +1,34 @@
+"""Shared tdx-api client and macOS runtime."""
+
+from pytdxfeed._version import __version__
+from pytdxfeed.client import (
+    BASE_URL,
+    DEFAULT_PORT,
+    HOST,
+    TdxApiClient,
+    local_base_url,
+    validate_port,
+)
+from pytdxfeed.errors import (
+    TdxApiDeploymentError,
+    TdxApiError,
+    TdxApiResponseError,
+    TdxApiTransportError,
+)
+from pytdxfeed.runtime import ServiceInfo, ensure_service
+
+__all__ = [
+    "BASE_URL",
+    "DEFAULT_PORT",
+    "HOST",
+    "ServiceInfo",
+    "TdxApiClient",
+    "TdxApiDeploymentError",
+    "TdxApiError",
+    "TdxApiResponseError",
+    "TdxApiTransportError",
+    "__version__",
+    "ensure_service",
+    "local_base_url",
+    "validate_port",
+]

pytdxfeed/_version.py

@@ -0,0 +1,3 @@
+"""Package version shared by runtime metadata and public exports."""
+
+__version__ = "0.2.0"

pytdxfeed/assets/manifest.json

@@ -0,0 +1,27 @@
+{
+  "api_major": 1,
+  "artifact_generation": 3,
+  "assets": {
+    "arm64": {
+      "filename": "tdx-api-ea07dccb67ae-darwin-arm64.tar.gz",
+      "sha256": "8b99f16639c248c3b634f613abfc9d8bd469f5428aa70b6f16ca38c700a7e8c5"
+    },
+    "x86_64": {
+      "filename": "tdx-api-ea07dccb67ae-darwin-x86_64.tar.gz",
+      "sha256": "9696b1332b826bb0d723da52cd3c558ae529ed31de6a6989f6d9e982659a4a31"
+    }
+  },
+  "patches": [
+    {
+      "filename": "tdx-api-ths-response-validation.patch",
+      "sha256": "6f27e36df68011cd60038b701b155788a7b90ad0cd7522c37144042cd6d17e20"
+    },
+    {
+      "filename": "tdx-api-configurable-port.patch",
+      "sha256": "f1c7d6824ce8f5c486d854a85ffab30ecef053e243b25b017c953b2b505e28a2"
+    }
+  ],
+  "schema_version": 1,
+  "upstream_sha": "ea07dccb67aeb92ebde851ac31503b4bf457a318",
+  "upstream_url": "https://github.com/oficcejo/tdx-api.git"
+}

pytdxfeed/client.py

@@ -0,0 +1,172 @@
+"""Thread-safe HTTP client for the local tdx-api service."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from threading import Lock, local
+from typing import Any
+
+import requests
+
+from pytdxfeed.errors import TdxApiResponseError, TdxApiTransportError
+
+HOST = "127.0.0.1"
+DEFAULT_PORT = 8080
+
+
+def validate_port(port: object) -> int:
+    """Require an explicit TCP port integer."""
+    if isinstance(port, bool) or not isinstance(port, int):
+        raise ValueError("port must be an integer between 1 and 65535")
+    if not 1 <= port <= 65535:
+        raise ValueError("port must be an integer between 1 and 65535")
+    return port
+
+
+def local_base_url(port: int = DEFAULT_PORT) -> str:
+    """Build the fixed-host service URL for one validated port."""
+    return f"http://{HOST}:{validate_port(port)}"
+
+
+BASE_URL = local_base_url()
+
+
+class TdxApiClient:
+    """Access the raw tdx-api JSON contract with per-thread HTTP sessions."""
+
+    def __init__(
+        self,
+        timeout_sec: float = 10.0,
+        *,
+        port: int = DEFAULT_PORT,
+        session_factory: Callable[[], requests.Session] = requests.Session,
+    ) -> None:
+        timeout = float(timeout_sec)
+        if timeout <= 0:
+            raise ValueError("timeout_sec must be positive")
+        self.timeout_sec = timeout
+        self.port = validate_port(port)
+        self.base_url = local_base_url(self.port)
+        self._session_factory = session_factory
+        self._local = local()
+        self._sessions: list[requests.Session] = []
+        self._sessions_lock = Lock()
+        self._closed = False
+
+    def __enter__(self) -> TdxApiClient:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close every session created by this client."""
+        with self._sessions_lock:
+            sessions = tuple(self._sessions)
+            self._sessions.clear()
+            self._closed = True
+        for session in sessions:
+            session.close()
+
+    def health(self) -> dict[str, Any]:
+        """Require the exact health response implemented by the pinned service."""
+        payload = self._request_json("GET", "/api/health")
+        if not isinstance(payload, dict):
+            raise TdxApiResponseError("[tdx-api] health response must be an object")
+        if str(payload.get("status") or "").lower() != "healthy":
+            raise TdxApiResponseError(
+                f"[tdx-api] health status is not healthy: {payload}"
+            )
+        return payload
+
+    def kline_all(
+        self,
+        code: str,
+        *,
+        source: str,
+        interval: str,
+        limit: int | None = None,
+    ) -> object:
+        """Return all stock K-lines from the explicit tdx or ths endpoint."""
+        if source not in {"tdx", "ths"}:
+            raise ValueError("source must be 'tdx' or 'ths'")
+        params: dict[str, object] = {"code": _required(code, "code"), "type": interval}
+        if limit is not None and limit > 0:
+            params["limit"] = int(limit)
+        return self._request_json("GET", f"/api/kline-all/{source}", params=params)
+
+    def index_all(
+        self, code: str, *, interval: str, limit: int | None = None
+    ) -> object:
+        """Return all index K-lines."""
+        params: dict[str, object] = {"code": _required(code, "code"), "type": interval}
+        if limit is not None and limit > 0:
+            params["limit"] = int(limit)
+        return self._request_json("GET", "/api/index/all", params=params)
+
+    def batch_quote(self, codes: Iterable[str]) -> object:
+        """Return a raw quote response for at most 50 explicit API codes."""
+        items = [_required(code, "code") for code in codes]
+        if not items:
+            raise ValueError("codes must not be empty")
+        if len(items) > 50:
+            raise ValueError("tdx-api accepts at most 50 quote codes per request")
+        return self._request_json("POST", "/api/batch-quote", json={"codes": items})
+
+    def trade(self, code: str) -> object:
+        """Return recent trades for one API code."""
+        return self._request_json(
+            "GET", "/api/trade", params={"code": _required(code, "code")}
+        )
+
+    def _session(self) -> requests.Session:
+        if self._closed:
+            raise RuntimeError("TdxApiClient is closed")
+        session = getattr(self._local, "session", None)
+        if session is None:
+            session = self._session_factory()
+            self._local.session = session
+            with self._sessions_lock:
+                self._sessions.append(session)
+        return session
+
+    def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, object] | None = None,
+        json: object | None = None,
+    ) -> object:
+        url = self.base_url + path
+        try:
+            response = self._session().request(
+                method,
+                url,
+                params=params,
+                json=json,
+                timeout=self.timeout_sec,
+            )
+            response.raise_for_status()
+        except requests.RequestException as exc:
+            raise TdxApiTransportError(
+                f"[tdx-api] request failed {url}: {exc}"
+            ) from exc
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            preview = str(getattr(response, "text", ""))[:200]
+            raise TdxApiTransportError(
+                f"[tdx-api] response is not JSON {url}: {preview}"
+            ) from exc
+        if isinstance(payload, dict) and payload.get("code") not in (None, 0):
+            message = payload.get("message") or payload.get("error") or payload
+            raise TdxApiResponseError(f"[tdx-api] {path} returned an error: {message}")
+        return payload
+
+
+def _required(value: object, field: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        raise ValueError(f"{field} must not be empty")
+    return text

pytdxfeed/errors.py

@@ -0,0 +1,17 @@
+"""Public exceptions raised by pytdxfeed."""
+
+
+class TdxApiError(RuntimeError):
+    """Base error for tdx-api client and runtime failures."""
+
+
+class TdxApiTransportError(TdxApiError):
+    """Raised when an HTTP request cannot be completed or decoded."""
+
+
+class TdxApiResponseError(TdxApiError):
+    """Raised when tdx-api returns an invalid or unsuccessful response."""
+
+
+class TdxApiDeploymentError(TdxApiError):
+    """Raised when the shared macOS service cannot be deployed."""

pytdxfeed/runtime.py

@@ -0,0 +1,648 @@
+"""Shared macOS lifecycle manager for the bundled tdx-api service."""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import platform
+import plistlib
+import shutil
+import socket
+import subprocess
+import tarfile
+import tempfile
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from pytdxfeed._version import __version__
+from pytdxfeed.client import (
+    DEFAULT_PORT,
+    HOST,
+    TdxApiClient,
+    local_base_url,
+    validate_port,
+)
+from pytdxfeed.errors import TdxApiDeploymentError, TdxApiError
+
+PORT = DEFAULT_PORT
+UPSTREAM_SHA = "ea07dccb67aeb92ebde851ac31503b4bf457a318"
+LAUNCHD_LABEL = "com.hermanzhaozzzz.pytdxfeed.tdx-api"
+LEGACY_VQT_LABEL = "com.hermanzhaozzzz.vqt.tdx-api"
+RUNTIME_DIRNAME = ".pytdxfeed"
+LEGACY_RUNTIME_DIRNAME = ".tdx-api"
+ASSET_MANIFEST = "manifest.json"
+STARTUP_TIMEOUT_SEC = 120.0
+PORT_RELEASE_TIMEOUT_SEC = 5.0
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceInfo:
+    """Description of the healthy local service selected for this process."""
+
+    base_url: str
+    port: int
+    managed: bool
+    launchd_label: str | None
+    runtime_root: Path | None
+    upstream_sha: str | None
+    artifact_generation: int | None
+
+
+def ensure_service(
+    *,
+    timeout_sec: float = 2.0,
+    startup_timeout_sec: float = STARTUP_TIMEOUT_SEC,
+    port: int = DEFAULT_PORT,
+) -> ServiceInfo:
+    """Return a healthy service, deploying the shared runtime on macOS if needed."""
+    resolved_port = validate_port(port)
+    client = TdxApiClient(timeout_sec=timeout_sec, port=resolved_port)
+    try:
+        if platform.system() != "Darwin":
+            try:
+                client.health()
+            except TdxApiError as exc:
+                raise TdxApiDeploymentError(
+                    "[pytdxfeed] tdx-api is unavailable; automatic deployment "
+                    "is supported only on macOS"
+                ) from exc
+            return _external_service_info(resolved_port)
+        return _RuntimeManager(
+            client=client,
+            home_dir=Path.home(),
+            startup_timeout_sec=startup_timeout_sec,
+            port=resolved_port,
+        ).ensure()
+    finally:
+        client.close()
+
+
+class _RuntimeManager:
+    def __init__(
+        self,
+        *,
+        client: TdxApiClient,
+        home_dir: Path,
+        startup_timeout_sec: float,
+        port: int = DEFAULT_PORT,
+    ) -> None:
+        self.client = client
+        self.home_dir = home_dir.expanduser().resolve()
+        self.runtime_root = self.home_dir / RUNTIME_DIRNAME
+        self.binary_path = self.runtime_root / "bin" / "tdx-api"
+        self.static_path = self.runtime_root / "static"
+        self.data_path = self.runtime_root / "data" / "database"
+        self.logs_path = self.runtime_root / "logs"
+        self.manifest_path = self.runtime_root / "deployment.json"
+        self.lock_path = self.runtime_root / "deployment.lock"
+        self.stdout_log_path = self.logs_path / "tdx-api.stdout.log"
+        self.stderr_log_path = self.logs_path / "tdx-api.stderr.log"
+        self.install_log_path = self.logs_path / "deployment.log"
+        self.plist_path = (
+            self.home_dir / "Library" / "LaunchAgents" / f"{LAUNCHD_LABEL}.plist"
+        )
+        self.legacy_vqt_plist_path = (
+            self.home_dir / "Library" / "LaunchAgents" / f"{LEGACY_VQT_LABEL}.plist"
+        )
+        self.domain = f"gui/{os.getuid()}"
+        self.service_target = f"{self.domain}/{LAUNCHD_LABEL}"
+        self.legacy_vqt_target = f"{self.domain}/{LEGACY_VQT_LABEL}"
+        self.startup_timeout_sec = float(startup_timeout_sec)
+        self.port = validate_port(port)
+        self.base_url = local_base_url(self.port)
+        if self.startup_timeout_sec <= 0:
+            raise ValueError("startup_timeout_sec must be positive")
+
+    def ensure(self) -> ServiceInfo:
+        """Reconcile the single per-user service."""
+        new_loaded = self._job_loaded(self.service_target)
+        legacy_loaded = self._job_loaded(self.legacy_vqt_target)
+        if not new_loaded and not legacy_loaded and self._healthy():
+            return _external_service_info(self.port)
+
+        self._prepare_directories()
+        with self.lock_path.open("a+", encoding="utf-8") as lock_file:
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                return self._ensure_locked()
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+
+    def _ensure_locked(self) -> ServiceInfo:
+        new_loaded = self._job_loaded(self.service_target)
+        legacy_loaded = self._job_loaded(self.legacy_vqt_target)
+        healthy = self._healthy()
+        asset_manifest = _load_asset_manifest()
+        deployment = self._read_json(self.manifest_path)
+        deployed_port = self._deployed_port(deployment)
+
+        if legacy_loaded:
+            self._seed_legacy_data()
+            return self._deploy(
+                asset_manifest,
+                old_target=self.legacy_vqt_target,
+                old_plist=self.legacy_vqt_plist_path,
+                remove_legacy_plist=True,
+                old_port=DEFAULT_PORT,
+            )
+
+        if new_loaded:
+            acceptable = self._deployment_acceptable(deployment, asset_manifest)
+            if healthy and acceptable:
+                return self._managed_service_info(deployment)
+            if deployed_port != self.port:
+                if healthy:
+                    self._retire_managed_service(deployed_port)
+                    return _external_service_info(self.port)
+                if _port_open(self.port):
+                    raise TdxApiDeploymentError(
+                        f"[pytdxfeed] {HOST}:{self.port} is occupied by an "
+                        "unhealthy unknown process; it will not be reused or terminated"
+                    )
+            return self._deploy(
+                asset_manifest,
+                old_target=self.service_target,
+                old_plist=self.plist_path,
+                remove_legacy_plist=False,
+                old_port=deployed_port,
+            )
+
+        if healthy:
+            return _external_service_info(self.port)
+        if _port_open(self.port):
+            raise TdxApiDeploymentError(
+                f"[pytdxfeed] {HOST}:{self.port} is occupied by an unhealthy "
+                "unknown process; it will not be reused or terminated"
+            )
+
+        self._seed_legacy_data()
+        return self._deploy(
+            asset_manifest,
+            old_target=None,
+            old_plist=None,
+            remove_legacy_plist=False,
+            old_port=None,
+        )
+
+    def _deployment_acceptable(
+        self, deployment: Mapping[str, Any] | None, assets: Mapping[str, Any]
+    ) -> bool:
+        if deployment is None:
+            return False
+        deployed_api = int(deployment.get("api_major", 0) or 0)
+        expected_api = int(assets["api_major"])
+        deployed_generation = int(deployment.get("artifact_generation", 0) or 0)
+        expected_generation = int(assets["artifact_generation"])
+        if deployed_api > expected_api:
+            raise TdxApiDeploymentError(
+                "[pytdxfeed] the managed service API is newer than this client; "
+                "refusing to downgrade it"
+            )
+        return (
+            deployed_api == expected_api
+            and deployed_generation >= expected_generation
+            and int(deployment.get("service_port", 0) or 0) == self.port
+            and self.binary_path.is_file()
+            and self.static_path.is_dir()
+        )
+
+    def _deploy(
+        self,
+        asset_manifest: Mapping[str, Any],
+        *,
+        old_target: str | None,
+        old_plist: Path | None,
+        remove_legacy_plist: bool,
+        old_port: int | None,
+    ) -> ServiceInfo:
+        old_plist_bytes = _read_bytes(old_plist) if old_plist is not None else None
+        with tempfile.TemporaryDirectory(
+            prefix="rollback-", dir=self.runtime_root
+        ) as rollback_text:
+            rollback = Path(rollback_text)
+            self._snapshot_runtime(rollback)
+            try:
+                deployment = self._install_asset(asset_manifest)
+                desired_plist = plistlib.dumps(self._plist_payload(), sort_keys=True)
+                _write_bytes_atomic(self.plist_path, desired_plist, mode=0o644)
+                if old_target is not None and self._job_loaded(old_target):
+                    self._launchctl(["bootout", old_target])
+                    self._wait_for_port_release(old_port or self.port)
+                if _port_open(self.port):
+                    raise TdxApiDeploymentError(
+                        f"[pytdxfeed] port {self.port} became occupied before bootstrap"
+                    )
+                self._launchctl(["bootstrap", self.domain, str(self.plist_path)])
+                self._launchctl(["kickstart", "-k", self.service_target])
+                self._wait_until_healthy()
+            except Exception as exc:
+                self._launchctl(["bootout", self.service_target], check=False)
+                self._restore_runtime(rollback)
+                if old_plist is not None and old_plist_bytes is not None:
+                    _write_bytes_atomic(old_plist, old_plist_bytes, mode=0o644)
+                    self._launchctl(
+                        ["bootstrap", self.domain, str(old_plist)], check=False
+                    )
+                    if old_target is not None:
+                        self._launchctl(["kickstart", "-k", old_target], check=False)
+                if isinstance(exc, TdxApiDeploymentError):
+                    raise
+                raise TdxApiDeploymentError(
+                    f"[pytdxfeed] deployment failed: {exc}"
+                ) from exc
+
+        if (
+            remove_legacy_plist
+            and old_plist is not None
+            and old_plist != self.plist_path
+        ):
+            old_plist.unlink(missing_ok=True)
+        return self._managed_service_info(deployment)
+
+    def _install_asset(self, asset_manifest: Mapping[str, Any]) -> dict[str, Any]:
+        architecture = _architecture()
+        asset = asset_manifest["assets"].get(architecture)
+        if not isinstance(asset, dict):
+            raise TdxApiDeploymentError(
+                f"[pytdxfeed] no bundled asset for architecture {architecture}"
+            )
+        filename = str(asset["filename"])
+        expected_checksum = str(asset["sha256"])
+        asset_ref = resources.files("pytdxfeed").joinpath("assets", filename)
+        with resources.as_file(asset_ref) as archive:
+            actual_checksum = _sha256(archive)
+            if actual_checksum != expected_checksum:
+                raise TdxApiDeploymentError(
+                    "[pytdxfeed] bundled asset checksum mismatch: "
+                    f"expected={expected_checksum} actual={actual_checksum}"
+                )
+            with tempfile.TemporaryDirectory(
+                prefix="install-", dir=self.runtime_root
+            ) as install_text:
+                install = Path(install_text)
+                _extract_archive_safe(archive, install)
+                source_binary = install / "bin" / "tdx-api"
+                source_static = install / "static"
+                source_data = install / "data" / "database"
+                if not source_binary.is_file() or not source_static.is_dir():
+                    raise TdxApiDeploymentError(
+                        "[pytdxfeed] bundled asset is missing binary or static files"
+                    )
+                temp_binary = self.binary_path.with_name(
+                    f".{self.binary_path.name}.{os.getpid()}.tmp"
+                )
+                shutil.copy2(source_binary, temp_binary)
+                temp_binary.chmod(0o755)
+                temp_binary.replace(self.binary_path)
+                self._replace_static(source_static)
+                _copy_missing_tree(source_data, self.data_path)
+
+        deployment = {
+            "schema_version": 2,
+            "api_major": int(asset_manifest["api_major"]),
+            "artifact_generation": int(asset_manifest["artifact_generation"]),
+            "package_version": __version__,
+            "upstream_sha": str(asset_manifest["upstream_sha"]),
+            "patches": list(asset_manifest.get("patches") or []),
+            "architecture": architecture,
+            "asset_filename": filename,
+            "asset_sha256": expected_checksum,
+            "binary_path": str(self.binary_path),
+            "service_port": self.port,
+            "installed_at": int(time.time()),
+        }
+        _write_json_atomic(self.manifest_path, deployment)
+        return deployment
+
+    def _replace_static(self, source: Path) -> None:
+        staged = self.runtime_root / f".static.{os.getpid()}.tmp"
+        previous = self.runtime_root / f".static.{os.getpid()}.old"
+        shutil.rmtree(staged, ignore_errors=True)
+        shutil.rmtree(previous, ignore_errors=True)
+        shutil.copytree(source, staged)
+        if self.static_path.exists():
+            self.static_path.replace(previous)
+        staged.replace(self.static_path)
+        shutil.rmtree(previous, ignore_errors=True)
+
+    def _seed_legacy_data(self) -> None:
+        sources: list[Path] = []
+        legacy_payload = _read_plist(self.legacy_vqt_plist_path)
+        if legacy_payload is not None:
+            working = str(legacy_payload.get("WorkingDirectory") or "").strip()
+            if working:
+                sources.append(Path(working).expanduser() / "data" / "database")
+
+        old_shared = self.home_dir / LEGACY_RUNTIME_DIRNAME
+        old_manifest = self._read_json(old_shared / "deployment.json")
+        if old_manifest is not None and old_manifest.get("upstream_sha"):
+            sources.append(old_shared / "data" / "database")
+
+        for source in sources:
+            _copy_missing_tree(source, self.data_path)
+
+    def _snapshot_runtime(self, target: Path) -> None:
+        if self.binary_path.is_file():
+            (target / "bin").mkdir(parents=True, exist_ok=True)
+            shutil.copy2(self.binary_path, target / "bin" / "tdx-api")
+        if self.static_path.is_dir():
+            shutil.copytree(self.static_path, target / "static")
+        if self.manifest_path.is_file():
+            shutil.copy2(self.manifest_path, target / "deployment.json")
+
+    def _restore_runtime(self, source: Path) -> None:
+        backup_binary = source / "bin" / "tdx-api"
+        if backup_binary.is_file():
+            shutil.copy2(backup_binary, self.binary_path)
+            self.binary_path.chmod(0o755)
+        backup_static = source / "static"
+        if backup_static.is_dir():
+            self._replace_static(backup_static)
+        backup_manifest = source / "deployment.json"
+        if backup_manifest.is_file():
+            shutil.copy2(backup_manifest, self.manifest_path)
+
+    def _prepare_directories(self) -> None:
+        for path in (
+            self.runtime_root,
+            self.binary_path.parent,
+            self.data_path,
+            self.logs_path,
+            self.plist_path.parent,
+        ):
+            path.mkdir(parents=True, exist_ok=True)
+        self.stdout_log_path.touch(exist_ok=True)
+        self.stderr_log_path.touch(exist_ok=True)
+        self.install_log_path.touch(exist_ok=True)
+
+    def _plist_payload(self) -> dict[str, object]:
+        return {
+            "Label": LAUNCHD_LABEL,
+            "ProgramArguments": [str(self.binary_path)],
+            "EnvironmentVariables": {"TDX_API_PORT": str(self.port)},
+            "WorkingDirectory": str(self.runtime_root),
+            "RunAtLoad": True,
+            "KeepAlive": True,
+            "ThrottleInterval": 30,
+            "ProcessType": "Standard",
+            "StandardOutPath": str(self.stdout_log_path),
+            "StandardErrorPath": str(self.stderr_log_path),
+        }
+
+    def _wait_for_port_release(self, port: int) -> None:
+        deadline = time.monotonic() + PORT_RELEASE_TIMEOUT_SEC
+        while _port_open(port) and time.monotonic() < deadline:
+            time.sleep(0.1)
+        if _port_open(port):
+            raise TdxApiDeploymentError(
+                f"[pytdxfeed] LaunchAgent stopped but port {port} is still occupied"
+            )
+
+    def _retire_managed_service(self, deployed_port: int) -> None:
+        """Stop a known managed job before reusing a healthy external service."""
+        self._launchctl(["bootout", self.service_target])
+        self._wait_for_port_release(deployed_port)
+        self.plist_path.unlink(missing_ok=True)
+
+    def _deployed_port(self, deployment: Mapping[str, Any] | None) -> int:
+        """Read the last managed port without guessing from an unknown process."""
+        if deployment is not None:
+            raw = deployment.get("service_port")
+            if isinstance(raw, int) and not isinstance(raw, bool):
+                try:
+                    return validate_port(raw)
+                except ValueError:
+                    pass
+        payload = _read_plist(self.plist_path)
+        environment = payload.get("EnvironmentVariables") if payload else None
+        if isinstance(environment, dict):
+            raw = environment.get("TDX_API_PORT")
+            try:
+                parsed = int(str(raw))
+            except (TypeError, ValueError):
+                pass
+            else:
+                try:
+                    return validate_port(parsed)
+                except ValueError:
+                    pass
+        return DEFAULT_PORT
+
+    def _wait_until_healthy(self) -> None:
+        deadline = time.monotonic() + self.startup_timeout_sec
+        last_error: Exception | None = None
+        while time.monotonic() < deadline:
+            try:
+                self.client.health()
+                return
+            except TdxApiError as exc:
+                last_error = exc
+                time.sleep(0.5)
+        launch_state = self._launchctl(
+            ["print", self.service_target], check=False
+        ).stdout
+        stderr_tail = _tail_file(self.stderr_log_path)
+        raise TdxApiDeploymentError(
+            "[pytdxfeed] service did not become healthy within "
+            f"{self.startup_timeout_sec:.0f}s; last_error={last_error}\n"
+            f"launchctl:\n{_tail_text(launch_state)}\n"
+            f"stderr:\n{stderr_tail}"
+        )
+
+    def _healthy(self) -> bool:
+        try:
+            self.client.health()
+        except TdxApiError:
+            return False
+        return True
+
+    def _job_loaded(self, target: str) -> bool:
+        return self._launchctl(["print", target], check=False).returncode == 0
+
+    def _launchctl(
+        self, args: Sequence[str], *, check: bool = True
+    ) -> subprocess.CompletedProcess[str]:
+        result = subprocess.run(  # noqa: S603 - fixed executable with explicit argv
+            ["/bin/launchctl", *args],
+            check=False,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            timeout=60,
+        )
+        if check and result.returncode != 0:
+            raise TdxApiDeploymentError(
+                f"[pytdxfeed] launchctl {' '.join(args)} failed "
+                f"with exit={result.returncode}:\n{_tail_text(result.stdout)}"
+            )
+        return result
+
+    @staticmethod
+    def _read_json(path: Path) -> dict[str, Any] | None:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        return payload if isinstance(payload, dict) else None
+
+    def _managed_service_info(self, deployment: Mapping[str, Any]) -> ServiceInfo:
+        return ServiceInfo(
+            base_url=self.base_url,
+            port=self.port,
+            managed=True,
+            launchd_label=LAUNCHD_LABEL,
+            runtime_root=self.runtime_root,
+            upstream_sha=str(deployment.get("upstream_sha") or UPSTREAM_SHA),
+            artifact_generation=int(deployment.get("artifact_generation", 0) or 0),
+        )
+
+
+def _external_service_info(port: int) -> ServiceInfo:
+    return ServiceInfo(
+        base_url=local_base_url(port),
+        port=port,
+        managed=False,
+        launchd_label=None,
+        runtime_root=None,
+        upstream_sha=None,
+        artifact_generation=None,
+    )
+
+
+def _load_asset_manifest() -> dict[str, Any]:
+    manifest_ref = resources.files("pytdxfeed").joinpath("assets", ASSET_MANIFEST)
+    try:
+        payload = json.loads(manifest_ref.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise TdxApiDeploymentError(
+            f"[pytdxfeed] bundled asset manifest is invalid: {exc}"
+        ) from exc
+    if not isinstance(payload, dict) or payload.get("upstream_sha") != UPSTREAM_SHA:
+        raise TdxApiDeploymentError(
+            "[pytdxfeed] bundled asset manifest does not match the locked upstream"
+        )
+    return payload
+
+
+def _architecture() -> str:
+    machine = platform.machine().lower()
+    aliases = {
+        "aarch64": "arm64",
+        "arm64": "arm64",
+        "amd64": "x86_64",
+        "x86_64": "x86_64",
+    }
+    try:
+        return aliases[machine]
+    except KeyError as exc:
+        raise TdxApiDeploymentError(
+            f"[pytdxfeed] unsupported macOS architecture: {machine}"
+        ) from exc
+
+
+def _port_open(port: int = DEFAULT_PORT) -> bool:
+    resolved_port = validate_port(port)
+    try:
+        with socket.create_connection((HOST, resolved_port), timeout=0.25):
+            return True
+    except OSError:
+        return False
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _extract_archive_safe(archive: Path, destination: Path) -> None:
+    with tarfile.open(archive, "r:gz") as tar:
+        for member in tar.getmembers():
+            relative = Path(member.name)
+            if relative.is_absolute() or ".." in relative.parts:
+                raise TdxApiDeploymentError(
+                    f"[pytdxfeed] unsafe archive member: {member.name}"
+                )
+            target = destination / relative
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            if not member.isfile():
+                raise TdxApiDeploymentError(
+                    f"[pytdxfeed] unsupported archive member: {member.name}"
+                )
+            target.parent.mkdir(parents=True, exist_ok=True)
+            source = tar.extractfile(member)
+            if source is None:
+                raise TdxApiDeploymentError(
+                    f"[pytdxfeed] cannot read archive member: {member.name}"
+                )
+            with source, target.open("wb") as output:
+                shutil.copyfileobj(source, output)
+            target.chmod(member.mode & 0o777)
+
+
+def _copy_missing_tree(source: Path, destination: Path) -> None:
+    if not source.is_dir():
+        return
+    destination.mkdir(parents=True, exist_ok=True)
+    for item in source.rglob("*"):
+        relative = item.relative_to(source)
+        target = destination / relative
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+        elif item.is_file() and not target.exists():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(item, target)
+
+
+def _read_plist(path: Path) -> dict[str, Any] | None:
+    try:
+        payload = plistlib.loads(path.read_bytes())
+    except (OSError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _read_bytes(path: Path | None) -> bytes | None:
+    if path is None:
+        return None
+    try:
+        return path.read_bytes()
+    except OSError:
+        return None
+
+
+def _write_json_atomic(path: Path, payload: Mapping[str, Any]) -> None:
+    encoded = (json.dumps(payload, ensure_ascii=False, indent=2) + "\n").encode()
+    _write_bytes_atomic(path, encoded, mode=0o644)
+
+
+def _write_bytes_atomic(path: Path, payload: bytes, *, mode: int) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temp.write_bytes(payload)
+        temp.chmod(mode)
+        temp.replace(path)
+    finally:
+        temp.unlink(missing_ok=True)
+
+
+def _tail_text(value: str, *, lines: int = 80) -> str:
+    return "\n".join(str(value or "").splitlines()[-lines:])
+
+
+def _tail_file(path: Path) -> str:
+    try:
+        return _tail_text(path.read_text(encoding="utf-8", errors="replace"))
+    except OSError as exc:
+        return f"<cannot read {path}: {exc}>"

pytdxfeed-0.2.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: pytdxfeed
+Version: 0.2.0
+Summary: Private macOS runtime and HTTP client for oficcejo/tdx-api.
+Author-email: Huanan Herman Zhao <hermanzhaozzzz@gmail.com>
+Requires-Python: <3.14,>=3.11
+Requires-Dist: requests<3.0.0,>=2.32.0
+Description-Content-Type: text/markdown
+
+# pytdxfeed
+
+`pytdxfeed` is a private Python wrapper around the local
+[`oficcejo/tdx-api`](https://github.com/oficcejo/tdx-api) service used by VQT
+and `vnpy_ths`. It provides one macOS LaunchAgent and one HTTP client contract,
+so both consumers share the same process instead of deploying competing copies.
+
+The package is installed only from the private Git repository. It is not the
+unrelated package formerly published under similar names on PyPI.
+
+## Runtime
+
+- Host: `127.0.0.1`
+- Port: `8080` by default; consumers may select another explicit port
+- Runtime root: `~/.pytdxfeed`
+- LaunchAgent: `com.hermanzhaozzzz.pytdxfeed.tdx-api`
+- Pinned upstream commit: `ea07dccb67aeb92ebde851ac31503b4bf457a318`
+
+On macOS, `ensure_service()` reuses an already healthy service or installs the
+bundled binary for the current architecture. The persistent upstream database
+is kept in `~/.pytdxfeed/data/database`. On other systems the function only
+checks an existing local service.
+
+```python
+from pytdxfeed import TdxApiClient, ensure_service
+
+service = ensure_service(port=18080)
+with TdxApiClient(timeout_sec=3.0, port=18080) as client:
+    health = client.health()
+    quotes = client.batch_quote(["sh600000", "sz159915"])
+```
+
+The host and LaunchAgent identity stay fixed. Port selection is explicit: the
+runtime never scans for a free port, and an unhealthy unknown process occupying
+the selected port causes startup to fail without terminating that process. The
+managed macOS service receives the selected port through `TDX_API_PORT`.
+
+## Development
+
+```bash
+uv sync --locked --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv build
+```
+
+Regenerate the private macOS assets when the locked upstream commit or reviewed
+private patch set changes:
+
+```bash
+uv run python scripts/build_assets.py --source /path/to/tdx-api
+```
+
+The build verifies the exact clean upstream checkout, applies the patches in
+`patches/`, runs their Go tests, and records every patch checksum in the asset
+manifest. Artifact generation 3 retains explicit THS JSONP validation and adds
+strict `TDX_API_PORT` handling to the Go service. It does not retry or switch
+market-data sources.
+
+The upstream repository currently has no declared license. This repository and
+its derived binaries must remain private/internal until redistribution terms are
+clear.

pytdxfeed-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pytdxfeed/__init__.py,sha256=6gCCdJT1txxDcnlzOKSChWGwqLO1YOrKyxaAmjNUxYY,698
+pytdxfeed/_version.py,sha256=mUzatm0zy0kkeuqzaWFobubGADb9Z4JAnkzlgBlhe9Y,92
+pytdxfeed/client.py,sha256=hIBf23B2wkDHgIrYlmRjkggS0mmouLRPKS7TcOC8Odc,6042
+pytdxfeed/errors.py,sha256=sEyDGLb4FP1mVPJdvDWI_bM8TxLdgSBW0d14Pn1CeQ8,483
+pytdxfeed/runtime.py,sha256=q4ccVWgGn6x8pLb_6pCiCIpw0yqFt6yw_mGCqLRKXlw,24823
+pytdxfeed/assets/manifest.json,sha256=P6lAnRdwF6uA_DZslmxUnEQi9TBFx8m-ybVQ1U4DOEs,872
+pytdxfeed/assets/tdx-api-ea07dccb67ae-darwin-arm64.tar.gz,sha256=i5nxZjnCSMO2NPYTq_ydi9Rp9UKKpwtvFso4xwCn6MU,6357661
+pytdxfeed/assets/tdx-api-ea07dccb67ae-darwin-x86_64.tar.gz,sha256=lpaxMyuCa7DXI9pSzTxViuUp7THeammJ9tnpgmWaSjE,6791327
+pytdxfeed-0.2.0.dist-info/METADATA,sha256=cm9rymQGQC528ZyueVd9rIdjR8eve79gukGRHGnFCm8,2648
+pytdxfeed-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pytdxfeed-0.2.0.dist-info/RECORD,,

pytdxfeed-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any