finctx 0.3.0__py3-none-any.whl

finctx/data/marketdb-datasets.json

@@ -0,0 +1,124 @@
+{
+  "datasets": {
+    "a_share_daily": {
+      "endpoint": "daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "adj_factor": {
+      "endpoint": "adj_factor",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "bond_daily": {
+      "endpoint": "bond_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "bond_dailyprice": {
+      "endpoint": "get_bond_dailyprice",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {
+        "count_type": "1",
+        "fields": []
+      }
+    },
+    "cb_daily": {
+      "endpoint": "cb_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "concept_index_daily": {
+      "endpoint": "concept_index_daily",
+      "keys": [
+        "concept_code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "fund_daily": {
+      "endpoint": "fund_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "fund_dailyprice": {
+      "endpoint": "get_fund_dailyprice",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {
+        "adjust_type": "N",
+        "count_type": "1",
+        "fields": []
+      }
+    },
+    "fut_daily": {
+      "endpoint": "fut_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "hk_daily": {
+      "endpoint": "hk_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "index_daily": {
+      "endpoint": "index_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "opt_daily": {
+      "endpoint": "opt_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "sge_daily": {
+      "endpoint": "sge_daily",
+      "keys": [
+        "code",
+        "trade_date"
+      ],
+      "kwargs": {}
+    },
+    "trade_cal": {
+      "endpoint": "trade_cal",
+      "keys": [
+        "exchange",
+        "calendar_date"
+      ],
+      "kwargs": {}
+    }
+  },
+  "schema_version": 1
+}

finctx/discovery.py

@@ -0,0 +1,70 @@
+"""Offline endpoint and response-field discovery from the packaged registry."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import difflib
+from functools import lru_cache
+from importlib import resources
+import json
+from typing import Any, Optional
+
+
+@lru_cache(maxsize=1)
+def _registry() -> dict[str, Any]:
+    # ``files`` is available on Python 3.9 and works for wheel/zip resources.
+    resource = resources.files("finctx").joinpath("data").joinpath("endpoints.json")
+    with resource.open("r", encoding="utf-8") as handle:
+        document = json.load(handle)
+    if not isinstance(document, dict) or not isinstance(document.get("endpoints"), list):
+        raise ValueError("packaged Finctx endpoint registry has an invalid structure")
+    return document
+
+
+@lru_cache(maxsize=1)
+def _by_name() -> dict[str, dict[str, Any]]:
+    entries = _registry()["endpoints"]
+    index = {entry["name"]: entry for entry in entries}
+    if len(index) != len(entries):
+        raise ValueError("packaged Finctx endpoint registry contains duplicate names")
+    return index
+
+
+def catalog_document() -> dict[str, Any]:
+    """Return the full registry document, including catalog-level provenance."""
+
+    return deepcopy(_registry())
+
+
+def endpoints() -> dict[str, dict[str, Any]]:
+    """Return every endpoint keyed by its exact generated method name."""
+
+    return deepcopy(_by_name())
+
+
+def fields(endpoint: str, search: Optional[str] = None) -> list[dict[str, Any]]:
+    """Return documented response fields for one exact generated method name."""
+
+    if not isinstance(endpoint, str) or not endpoint:
+        raise ValueError("endpoint must be a non-empty method name")
+    index = _by_name()
+    entry = index.get(endpoint)
+    if entry is None:
+        guesses = difflib.get_close_matches(endpoint, index.keys(), n=3, cutoff=0.5)
+        hint = f"; did you mean {', '.join(guesses)}?" if guesses else ""
+        raise ValueError(f"unknown Finctx endpoint {endpoint!r}{hint}")
+    if search is not None and not isinstance(search, str):
+        raise TypeError("search must be a string or None")
+    documented = entry["response"]["fields"]
+    if not search or not search.strip():
+        return deepcopy(documented)
+    term = search.strip().casefold()
+    return deepcopy(
+        [
+            field
+            for field in documented
+            if term in field["name"].casefold()
+            or term in field.get("description", "").casefold()
+            or term in field.get("type", "").casefold()
+        ]
+    )

finctx/exceptions.py

@@ -0,0 +1,110 @@
+"""Exceptions raised by the Finctx Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+
+class FinctxError(Exception):
+    """Base class for all SDK-specific exceptions."""
+
+
+class FinctxTransportError(FinctxError):
+    """An HTTP or WebSocket transport operation could not be completed."""
+
+    def __init__(self, message: str, *, cause: BaseException) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class FinctxWebSocketMessageError(FinctxError):
+    """A WebSocket message did not match the documented JSON text protocol."""
+
+    def __init__(self, message: str, *, raw_message: Any) -> None:
+        super().__init__(message)
+        self.raw_message = raw_message
+
+
+class FinctxApiError(FinctxError):
+    """The Finctx endpoint returned a non-success HTTP status."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        error_code: Optional[str],
+        message: str,
+        request_id: Optional[str],
+        response: requests.Response,
+    ) -> None:
+        details = f"{status_code} {message}"
+        if error_code:
+            details += f" (error={error_code})"
+        if request_id:
+            details += f" (request_id={request_id})"
+        super().__init__(details)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.message = message
+        self.request_id = request_id
+        self.response = response
+
+
+class FinctxResponseError(FinctxError):
+    """A successful API response did not contain the JSON expected by an API function."""
+
+    def __init__(self, message: str, *, response: requests.Response) -> None:
+        super().__init__(message)
+        self.response = response
+        self.request_id = response.headers.get("X-Meridian-Request-ID")
+
+
+class FinctxResultError(FinctxError):
+    """A JSON result cannot be interpreted as a table of rows."""
+
+    def __init__(self, message: str, *, result: Any) -> None:
+        super().__init__(message)
+        self.result = result
+        raw_error = result.get("error") if isinstance(result, dict) else None
+        self.error_code = (
+            raw_error
+            if isinstance(raw_error, str)
+            else raw_error.get("code")
+            if isinstance(raw_error, dict)
+            else None
+        )
+
+
+def api_error_from_response(response: requests.Response) -> FinctxApiError:
+    """Create a stable, structured error without exposing an arbitrary response body."""
+
+    payload: Any = None
+    try:
+        payload = response.json()
+    except ValueError:
+        pass
+
+    error_code: Optional[str] = None
+    message: Optional[str] = None
+    if isinstance(payload, dict):
+        raw_error = payload.get("error")
+        if isinstance(raw_error, str):
+            error_code = raw_error
+        elif isinstance(raw_error, dict):
+            raw_code = raw_error.get("code")
+            if isinstance(raw_code, str):
+                error_code = raw_code
+
+        raw_message = payload.get("message")
+        if isinstance(raw_message, str) and raw_message:
+            message = raw_message
+
+    return FinctxApiError(
+        status_code=response.status_code,
+        error_code=error_code,
+        message=message or response.reason or "Finctx API request failed",
+        request_id=response.headers.get("X-Meridian-Request-ID"),
+        response=response,
+    )

finctx/generated/__init__.py

@@ -0,0 +1,5 @@
+"""自动生成的 legacy 业务函数。"""
+
+from .api import GeneratedApiMixin
+
+__all__ = ["GeneratedApiMixin"]