finctx 0.3.0__py3-none-any.whl

finctx/__init__.py

@@ -0,0 +1,24 @@
+"""Public interface for the Finctx Data API Python SDK."""
+
+from ._version import __version__
+from .client import FinctxClient, FinctxWebSocket
+from .exceptions import (
+    FinctxApiError,
+    FinctxError,
+    FinctxResponseError,
+    FinctxResultError,
+    FinctxTransportError,
+    FinctxWebSocketMessageError,
+)
+
+__all__ = [
+    "FinctxApiError",
+    "FinctxClient",
+    "FinctxError",
+    "FinctxResponseError",
+    "FinctxResultError",
+    "FinctxTransportError",
+    "FinctxWebSocket",
+    "FinctxWebSocketMessageError",
+    "__version__",
+]

finctx/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the Finctx Python SDK version."""
+
+__version__ = "0.3.0"

finctx/client.py

@@ -0,0 +1,400 @@
+"""Synchronous Finctx Data API client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import json as json_module
+from typing import Any, Optional, Union
+from urllib.parse import quote, urlsplit
+
+import requests
+import websocket
+
+from .exceptions import (
+    FinctxResponseError,
+    FinctxTransportError,
+    FinctxWebSocketMessageError,
+    api_error_from_response,
+)
+from .credentials import resolve_api_key, resolve_base_url
+from .discovery import catalog_document, endpoints, fields
+from .generated.api import GeneratedApiMixin
+from .results import arrow_to_table, rows
+
+MAX_BODY_BYTES = 1024 * 1024
+AUTH_HEADER_NAMES = frozenset(
+    {
+        "authorization",
+        "x-meridian-ak",
+        "x-meridian-signature",
+        "x-meridian-timestamp",
+        "x-meridian-nonce",
+    }
+)
+
+QueryValue = Optional[Union[str, bytes, int, float, bool]]
+QueryParams = Union[
+    Mapping[str, Union[QueryValue, Sequence[QueryValue]]],
+    Sequence[tuple[str, QueryValue]],
+]
+RequestData = Union[
+    str,
+    bytes,
+    bytearray,
+    Mapping[str, Any],
+    Sequence[tuple[str, Any]],
+]
+Timeout = Union[float, tuple[float, float]]
+
+
+class FinctxWebSocket:
+    """One connected Finctx WebSocket using the server's JSON text protocol."""
+
+    def __init__(self, connection: websocket.WebSocket) -> None:
+        self._connection = connection
+
+    def send_json(self, payload: Any) -> None:
+        """Send one JSON text message without retrying it."""
+
+        message = json_module.dumps(
+            payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+        )
+        try:
+            self._connection.send(message)
+        except websocket.WebSocketException as error:
+            raise FinctxTransportError(
+                "Finctx WebSocket message could not be sent", cause=error
+            ) from error
+
+    def receive_json(self) -> Any:
+        """Receive and decode one JSON text message without automatic reconnect."""
+
+        try:
+            message = self._connection.recv()
+        except websocket.WebSocketException as error:
+            raise FinctxTransportError(
+                "Finctx WebSocket message could not be received", cause=error
+            ) from error
+        if not isinstance(message, str):
+            raise FinctxWebSocketMessageError(
+                "Finctx WebSocket returned a non-text message",
+                raw_message=message,
+            )
+        try:
+            return json_module.loads(message)
+        except ValueError as error:
+            raise FinctxWebSocketMessageError(
+                "Finctx WebSocket returned invalid JSON",
+                raw_message=message,
+            ) from error
+
+    def close(self) -> None:
+        """Close this WebSocket connection."""
+
+        try:
+            self._connection.close()
+        except websocket.WebSocketException as error:
+            raise FinctxTransportError(
+                "Finctx WebSocket could not be closed cleanly", cause=error
+            ) from error
+
+    def __enter__(self) -> FinctxWebSocket:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class FinctxClient(GeneratedApiMixin):
+    """A synchronous API Key client for Finctx Data API.
+
+    The client owns its :class:`requests.Session`. One client can be reused for
+    multiple calls and should be closed when it is no longer needed.
+    """
+
+    rows = staticmethod(rows)
+    arrow_to_table = staticmethod(arrow_to_table)
+    catalog_document = staticmethod(catalog_document)
+    endpoints = staticmethod(endpoints)
+    fields = staticmethod(fields)
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: Timeout = 30.0,
+        websocket_base_url: Optional[str] = None,
+        websocket_timeout: float = 30.0,
+    ) -> None:
+        self.base_url = _normalize_origin(resolve_base_url(base_url))
+        self.websocket_base_url = (
+            None
+            if websocket_base_url is None
+            else _normalize_websocket_origin(websocket_base_url)
+        )
+        self.auth_scheme = "api_key"
+        self._api_key = resolve_api_key(api_key)
+        self.timeout = timeout
+        if not isinstance(websocket_timeout, (int, float)) or websocket_timeout <= 0:
+            raise ValueError("websocket_timeout must be a positive number")
+        self.websocket_timeout = float(websocket_timeout)
+        self._session = requests.Session()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[QueryParams] = None,
+        data: Optional[RequestData] = None,
+        json: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[Timeout] = None,
+    ) -> requests.Response:
+        """Prepare, authenticate, and send one request without automatic retries.
+
+        ``path`` is relative to the configured origin but must begin with
+        ``/``. Redirects are intentionally not followed: a redirect could disclose
+        credential headers to another origin.
+        """
+
+        method = _normalize_method(method)
+        _validate_request_path(path)
+        _reject_protected_headers(headers)
+        if data is not None and json is not None:
+            raise ValueError("data and json cannot be used together")
+
+        request = requests.Request(
+            method=method,
+            url=f"{self.base_url}{path}",
+            params=params,
+            data=data,
+            json=json,
+            headers=headers,
+        )
+        prepared = self._session.prepare_request(request)
+        _reject_protected_headers(prepared.headers)
+
+        body = _finalize_body(prepared)
+        if len(body) > MAX_BODY_BYTES:
+            raise ValueError(
+                f"request body exceeds the {MAX_BODY_BYTES}-byte Finctx limit"
+            )
+
+        prepared.headers["Authorization"] = f"Bearer {self._api_key}"
+
+        settings = self._session.merge_environment_settings(
+            prepared.url or "", {}, None, None, None
+        )
+        try:
+            response = self._session.send(
+                prepared,
+                timeout=self.timeout if timeout is None else timeout,
+                allow_redirects=False,
+                **settings,
+            )
+        except requests.RequestException as error:
+            raise FinctxTransportError(
+                "Finctx API request could not be completed", cause=error
+            ) from error
+
+        if not 200 <= response.status_code < 300:
+            raise api_error_from_response(response)
+        return response
+
+    def _call_api(self, path: str, payload: Mapping[str, Any]) -> Any:
+        """Decode JSON responses; preserve Arrow streams as bytes without conversion."""
+
+        response = self.request("POST", path, json=payload)
+        return self._decode_api_response(response)
+
+    def _call_get_api(self, path: str, values: Mapping[str, Any], parameters: list[dict[str, Any]]) -> Any:
+        """按公开契约编码主题查询；GET 不带 JSON 请求体，布尔值为小写。"""
+        return self._call_parameter_api("GET", path, values, parameters, False)
+
+    def _call_parameter_api(self, method: str, path: str, values: Mapping[str, Any],
+                            parameters: list[dict[str, Any]], has_body: bool) -> Any:
+        """按契约分离路径、查询和 JSON 参数；主题标识作为单个路径段编码。"""
+        query = {}
+        body = dict(values)
+        for parameter in parameters:
+            name = parameter["name"]
+            if name not in values:
+                continue
+            value = values[name]
+            body.pop(name)
+            if parameter["in"] == "path":
+                if parameter["schema"]["type"] == "integer" and (isinstance(value, bool) or not isinstance(value, int) or value < 1):
+                    raise ValueError(f"{name} must be a positive integer")
+                if parameter["schema"]["type"] == "string" and (not isinstance(value, str) or not value):
+                    raise ValueError(f"{name} must be a non-empty string")
+                path = path.replace("{" + name + "}", quote(str(value), safe=""))
+            else:
+                if value is None:
+                    raise ValueError(f"{name} cannot be null in a query")
+                query[name] = str(value).lower() if isinstance(value, bool) else value
+        settings = {"params": query}
+        if has_body:
+            settings["json"] = body
+        return self._decode_api_response(self.request(method, path, **settings))
+
+    @staticmethod
+    def _decode_api_response(response: requests.Response) -> Any:
+        """保留 Arrow 字节与 JSON 错误的原始响应，供两种 HTTP 方法共用。"""
+        content_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        if content_type == "application/vnd.apache.arrow.stream":
+            return response.content
+        try:
+            return response.json()
+        except ValueError as error:
+            raise FinctxResponseError(
+                "Finctx API returned a successful response with invalid JSON",
+                response=response,
+            ) from error
+
+    def connect_websocket(
+        self,
+        path: str,
+        *,
+        base_url: str,
+        subscription: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> FinctxWebSocket:
+        """Connect to one WebSocket and optionally send its JSON subscription."""
+
+        _validate_request_path(path)
+        origin = _normalize_websocket_origin(base_url)
+        effective_timeout = self.websocket_timeout if timeout is None else timeout
+        if not isinstance(effective_timeout, (int, float)) or effective_timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+        try:
+            connection = websocket.create_connection(
+                f"{origin}{path}",
+                timeout=float(effective_timeout),
+                header={"Authorization": f"Bearer {self._api_key}"},
+            )
+        except websocket.WebSocketException as error:
+            raise FinctxTransportError(
+                "Finctx WebSocket connection could not be established", cause=error
+            ) from error
+        stream = FinctxWebSocket(connection)
+        if subscription is not None:
+            try:
+                stream.send_json(subscription)
+            except Exception:
+                try:
+                    connection.close()
+                except websocket.WebSocketException:
+                    pass
+                raise
+        return stream
+
+    def _connect_websocket(
+        self, origin: str, path: str, subscription: Mapping[str, Any]
+    ) -> FinctxWebSocket:
+        return self.connect_websocket(
+            path,
+            base_url=self.websocket_base_url or origin,
+            subscription=subscription,
+        )
+
+    def close(self) -> None:
+        """Release pooled HTTP connections."""
+
+        self._session.close()
+
+    def __enter__(self) -> FinctxClient:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def _normalize_origin(base_url: str) -> str:
+    if not isinstance(base_url, str) or not base_url:
+        raise ValueError("base_url must be a non-empty HTTP(S) origin")
+
+    parsed = urlsplit(base_url)
+    try:
+        parsed.port
+    except ValueError as error:
+        raise ValueError("base_url contains an invalid port") from error
+
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "base_url must be an HTTP(S) origin without path, query, fragment, or userinfo"
+        )
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
+def _normalize_websocket_origin(base_url: str) -> str:
+    if not isinstance(base_url, str) or not base_url:
+        raise ValueError("base_url must be a non-empty WebSocket origin")
+    parsed = urlsplit(base_url)
+    try:
+        parsed.port
+    except ValueError as error:
+        raise ValueError("base_url contains an invalid port") from error
+    if (
+        parsed.scheme not in {"ws", "wss"}
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.path not in {"", "/"}
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(
+            "base_url must be a WS(S) origin without path, query, fragment, or userinfo"
+        )
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
+def _normalize_method(method: str) -> str:
+    if not isinstance(method, str) or not method.strip():
+        raise ValueError("method must be a non-empty string")
+    return method.strip().upper()
+
+
+def _validate_request_path(path: str) -> None:
+    if not isinstance(path, str) or not path.startswith("/") or path.startswith("//"):
+        raise ValueError("path must begin with one '/' and be relative to base_url")
+    parsed = urlsplit(path)
+    if parsed.scheme or parsed.netloc or parsed.fragment:
+        raise ValueError("path must be a relative API path without a fragment")
+
+
+def _reject_protected_headers(headers: Optional[Mapping[str, str]]) -> None:
+    if not headers:
+        return
+    overridden = AUTH_HEADER_NAMES.intersection(str(name).lower() for name in headers)
+    if overridden:
+        names = ", ".join(sorted(overridden))
+        raise ValueError(f"Finctx authentication headers are managed by the SDK: {names}")
+
+
+def _finalize_body(prepared: requests.PreparedRequest) -> bytes:
+    raw_body = prepared.body
+    if raw_body is None:
+        return b""
+    if isinstance(raw_body, str):
+        body = raw_body.encode("utf-8")
+    elif isinstance(raw_body, (bytes, bytearray)):
+        body = bytes(raw_body)
+    else:
+        raise TypeError("streaming and file-like request bodies are not supported")
+
+    # Pin the final UTF-8 payload and its byte length for urllib3.
+    prepared.body = body
+    prepared.headers["Content-Length"] = str(len(body))
+    prepared.headers.pop("Transfer-Encoding", None)
+    return body

finctx/credentials.py

@@ -0,0 +1,153 @@
+"""Resolve local API credentials without executing shell syntax."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import stat
+import subprocess
+from typing import Optional
+
+
+ENV_KEY = "FINCTX_API_KEY"
+ENV_BASE_URL = "FINCTX_BASE_URL"
+DEFAULT_BASE_URL = "https://api.ultrastiching.com"
+_MAX_CREDENTIALS_BYTES = 64 * 1024
+
+
+def resolve_api_key(explicit: Optional[str]) -> str:
+    """Use an explicit key, then the environment, then the user's private file."""
+
+    if explicit is not None:
+        return _require_value("api_key", explicit)
+    if ENV_KEY in os.environ:
+        return _require_value(ENV_KEY, os.environ[ENV_KEY])
+    key = _read_credentials_file()
+    if key is None:
+        raise ValueError(
+            "api_key is required: pass api_key, set FINCTX_API_KEY, "
+            "or create ~/.finctx/credentials.env"
+        )
+    return _require_value(ENV_KEY, key)
+
+
+def resolve_base_url(explicit: Optional[str]) -> str:
+    """Use an explicit origin, then the environment, then production."""
+
+    if explicit is not None:
+        return explicit
+    if ENV_BASE_URL in os.environ:
+        return os.environ[ENV_BASE_URL]
+    return DEFAULT_BASE_URL
+
+
+def _require_value(name: str, value: str) -> str:
+    if not isinstance(value, str) or not value.strip() or "\n" in value or "\r" in value:
+        raise ValueError(f"{name} must be a non-empty single-line string")
+    if value != value.strip():
+        raise ValueError(f"{name} must not contain surrounding whitespace")
+    if '"' in value or "'" in value:
+        raise ValueError(
+            f"{name} must not contain quotes; quotes in credentials.env are file syntax, "
+            "not part of the Key. Set FINCTX_API_KEY to the unquoted value or remove it to use ~/.finctx/credentials.env."
+        )
+    return value
+
+
+def _current_uid() -> Optional[int]:
+    getuid = getattr(os, "getuid", None)
+    return getuid() if getuid is not None else None
+
+
+def _read_credentials_file() -> Optional[str]:
+    directory = Path.home() / ".finctx"
+    try:
+        directory_info = directory.lstat()
+    except FileNotFoundError:
+        return None
+    uid = _current_uid()
+    if not stat.S_ISDIR(directory_info.st_mode):
+        raise ValueError("~/.finctx must be a directory, not a link or file")
+    if uid is None:
+        _check_windows_acl(directory)
+    elif directory_info.st_uid != uid or directory_info.st_mode & 0o022:
+        raise ValueError("~/.finctx must be owned by the current user and not writable by others")
+
+    path = directory / "credentials.env"
+    flags = os.O_RDONLY
+    flags |= getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NONBLOCK", 0)
+    nofollow = getattr(os, "O_NOFOLLOW", None)
+    if nofollow is None and os.name != "nt":
+        raise OSError("credentials.env requires no-follow file access on this platform")
+    flags |= nofollow or 0
+    try:
+        before = path.lstat()
+    except FileNotFoundError:
+        return None
+    if not stat.S_ISREG(before.st_mode):
+        raise OSError("credentials.env must be a regular file, not a link")
+    if uid is None:
+        _check_windows_acl(path)
+    try:
+        fd = os.open(path, flags)
+    except FileNotFoundError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if (not stat.S_ISREG(info.st_mode) or info.st_dev != before.st_dev or info.st_ino != before.st_ino
+                or uid is not None and (info.st_uid != uid or info.st_mode & 0o077)):
+            raise ValueError(
+                "~/.finctx/credentials.env must be a regular file owned by "
+                "the current user with mode 0600 or stricter"
+            )
+        with os.fdopen(fd, encoding="utf-8") as handle:
+            fd = -1
+            content = handle.read(_MAX_CREDENTIALS_BYTES + 1)
+    finally:
+        if fd >= 0:
+            os.close(fd)
+    if len(content.encode("utf-8")) > _MAX_CREDENTIALS_BYTES:
+        raise ValueError("~/.finctx/credentials.env exceeds 64 KiB")
+
+    found: Optional[str] = None
+    for line in content.splitlines():
+        item = line.strip()
+        if not item or item.startswith("#"):
+            continue
+        if item.startswith("export "):
+            item = item[7:].lstrip()
+        name, separator, value = item.partition("=")
+        if name.strip() != ENV_KEY:
+            continue
+        if not separator:
+            raise ValueError("invalid FINCTX_API_KEY entry in credentials.env")
+        if found is not None:
+            raise ValueError("duplicate FINCTX_API_KEY entries in credentials.env")
+        value = value.strip()
+        if value.startswith(("'", '"')):
+            if len(value) < 2 or value[-1] != value[0]:
+                raise ValueError("invalid quoted FINCTX_API_KEY in credentials.env")
+            value = value[1:-1]
+        found = value
+    return found
+
+
+def _check_windows_acl(path: Path) -> None:
+    """Match the CLI's Windows private-file rules without reading a secret in PowerShell."""
+    if os.name != "nt":
+        raise OSError("cannot verify credential ownership on this platform")
+    literal = "'" + str(path).replace("'", "''") + "'"
+    script = (
+        "$ErrorActionPreference='Stop'; $p=" + literal + ";"
+        "$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User;"
+        "$acl=Get-Acl -LiteralPath $p;"
+        "if($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value)"
+        "{throw 'credentials must be owned by current user'};"
+        "foreach($rule in $acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier]))"
+        "{if($rule.AccessControlType -eq 'Allow' -and $rule.IdentityReference.Value -notin "
+        "@($sid.Value,'S-1-5-18','S-1-5-32-544') -and ([int]$rule.FileSystemRights -band 2032127))"
+        "{throw 'credentials ACL grants access to other users'}}"
+    )
+    subprocess.run(["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script],
+                   check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)