ronds-datastore-client 0.0.1__tar.gz

ronds_datastore_client-0.0.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.1
+Name: ronds-datastore-client
+Version: 0.0.1
+Summary: Unified DataStore SDK client
+Requires-Python: >=3.8
+Requires-Dist: requests
+Requires-Dist: jsonschema

ronds_datastore_client-0.0.1/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ronds-datastore-client"
+version = "0.0.1"
+description = "Unified DataStore SDK client"
+requires-python = ">=3.8"
+dependencies = ["requests", "jsonschema"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"

ronds_datastore_client-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ronds_datastore_client-0.0.1/src/datastore_client/__init__.py

@@ -0,0 +1,37 @@
+"""
+Unified DataStore SDK client for Python 3.8+
+"""
+
+from datastore_client.client import DataStoreClient
+from datastore_client.exceptions import (
+    DataStoreException,
+    NoResultException,
+    NonUniqueResultException,
+)
+from datastore_client.adapter.default_client import DefaultDataStoreClient
+from datastore_client.adapter.driver_registry import DriverRegistry
+from datastore_client.adapter.direct_url_resolver import DirectUrlResourceResolver
+from datastore_client.model.request import ReadRequest, WriteRequest, DeleteRequest, ExistsRequest
+from datastore_client.model.response import ReadResponse, WriteResponse
+from datastore_client.model.resource import ResourceInfo, ResourceCategory, ResourceType
+from datastore_client.model.message import DataMessage
+
+__all__ = [
+    "DataStoreClient",
+    "DefaultDataStoreClient",
+    "DriverRegistry",
+    "DirectUrlResourceResolver",
+    "DataStoreException",
+    "NoResultException",
+    "NonUniqueResultException",
+    "ReadRequest",
+    "WriteRequest",
+    "DeleteRequest",
+    "ExistsRequest",
+    "ReadResponse",
+    "WriteResponse",
+    "ResourceInfo",
+    "ResourceCategory",
+    "ResourceType",
+    "DataMessage",
+]

ronds_datastore_client-0.0.1/src/datastore_client/adapter/__init__.py

@@ -0,0 +1,11 @@
+"""Adapter implementations for DataStore SDK."""
+
+from .default_client import DefaultDataStoreClient
+from .driver_registry import DriverRegistry
+from .direct_url_resolver import DirectUrlResourceResolver
+
+__all__ = [
+    "DefaultDataStoreClient",
+    "DriverRegistry",
+    "DirectUrlResourceResolver",
+]

ronds_datastore_client-0.0.1/src/datastore_client/adapter/default_client.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""
+默认 DataStore 客户端实现
+支持多连接，connect 返回 DataStoreConnection 供调用方持有
+"""
+from typing import Optional, List
+import threading
+import atexit
+
+from datastore_client.exceptions import DataStoreException
+from datastore_client.model.resource import ResourceInfo
+from datastore_client.spi.connection import DataStoreConnection
+from datastore_client.spi.driver import DataStoreDriver
+from datastore_client.spi.resolver import ResourceResolver
+from datastore_client.common.url_parser import UrlParser
+from datastore_client.adapter.driver_registry import DriverRegistry
+from datastore_client.adapter.direct_url_resolver import DirectUrlResourceResolver
+
+
+class ConnectionEntry:
+    def __init__(self, urn: str, resource: ResourceInfo, connection: DataStoreConnection):
+        self.urn = urn
+        self.resource = resource
+        self.connection = connection
+
+
+class DefaultDataStoreClient:
+    """默认 DataStore 客户端"""
+
+    def __init__(
+        self,
+        resource_resolver: Optional[ResourceResolver] = None,
+        driver_registry: Optional[DriverRegistry] = None,
+        url_parser: Optional[UrlParser] = None,
+    ):
+        self._resource_resolver = resource_resolver
+        self._driver_registry = driver_registry or DriverRegistry()
+        self._url_parser = url_parser or UrlParser()
+        self._connections: List[ConnectionEntry] = []
+        self._lock = threading.Lock()
+        atexit.register(self._shutdown)
+
+    @classmethod
+    def builder(cls) -> "DefaultDataStoreClientBuilder":
+        return DefaultDataStoreClientBuilder()
+
+    def connect(self, urn: str) -> DataStoreConnection:
+        """建立与指定数据资源的连接；每次调用均新增连接，同一 URN 可存在多个连接。"""
+        info = self._resource_resolver.resolve(urn)
+        if info.driver_name:
+            self._driver_registry.ensure_driver_loaded(info.driver_name)
+        config = self._url_parser.parse(info.url)
+        scheme = info.driver_scheme or (config.scheme.lower() if config.scheme else None)
+        if not scheme:
+            raise DataStoreException("Cannot determine driver scheme")
+        driver = self._driver_registry.find_driver(scheme)
+        if not driver:
+            raise DataStoreException(f"No driver found for scheme: {scheme}")
+        conn = driver.connect(config, info.data_schema)
+        with self._lock:
+            self._connections.append(ConnectionEntry(urn, info, conn))
+        return conn
+
+    def disconnect(self, urn: Optional[str] = None) -> None:
+        """断开指定 URN 的全部连接，或关闭所有连接"""
+        with self._lock:
+            if urn:
+                remaining: List[ConnectionEntry] = []
+                for entry in self._connections:
+                    if entry.urn == urn:
+                        try:
+                            entry.connection.close()
+                        except Exception:
+                            pass
+                    else:
+                        remaining.append(entry)
+                self._connections = remaining
+            else:
+                for entry in self._connections:
+                    try:
+                        entry.connection.close()
+                    except Exception:
+                        pass
+                self._connections.clear()
+
+    def is_connected(self, urn: str) -> bool:
+        """是否已为指定 URN 建立过至少一条仍被本 client 追踪的连接"""
+        with self._lock:
+            return any(e.urn == urn for e in self._connections)
+
+    def get_resource(self, urn: str) -> Optional[ResourceInfo]:
+        """获取指定 URN 的资源信息（与 Java 一致：返回最近一次 connect 对应条目）"""
+        with self._lock:
+            for entry in reversed(self._connections):
+                if entry.urn == urn:
+                    return entry.resource
+            return None
+
+    def get_connection(self, urn: str) -> Optional[DataStoreConnection]:
+        """获取指定 URN 的连接（与 Java 一致：返回最近一次 connect 的实例）"""
+        with self._lock:
+            for entry in reversed(self._connections):
+                if entry.urn == urn:
+                    return entry.connection
+            return None
+
+    def close(self) -> None:
+        """关闭所有连接"""
+        atexit.unregister(self._shutdown)
+        self.disconnect()
+
+    def _shutdown(self) -> None:
+        self.disconnect()
+
+    def __enter__(self) -> "DefaultDataStoreClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+
+class DefaultDataStoreClientBuilder:
+    def __init__(self):
+        self._resource_resolver = None
+        self._driver_registry = None
+        self._url_parser = None
+        self._os_url = None
+        self._resolve_path = None
+
+    def os_url(self, os_url: str) -> "DefaultDataStoreClientBuilder":
+        self._os_url = os_url
+        return self
+
+    def resolve_path(self, path: str) -> "DefaultDataStoreClientBuilder":
+        self._resolve_path = path
+        return self
+
+    def resource_resolver(self, r: ResourceResolver) -> "DefaultDataStoreClientBuilder":
+        self._resource_resolver = r
+        return self
+
+    def driver_registry(self, r: DriverRegistry) -> "DefaultDataStoreClientBuilder":
+        self._driver_registry = r
+        return self
+
+    def url_parser(self, u: UrlParser) -> "DefaultDataStoreClientBuilder":
+        self._url_parser = u
+        return self
+
+    def build(self) -> DefaultDataStoreClient:
+        if self._resource_resolver is None:
+            if not self._os_url or not self._os_url.strip():
+                raise ValueError("osUrl is required when resource_resolver is not set")
+            self._resource_resolver = DirectUrlResourceResolver(
+                os_url=self._os_url,
+                resolve_path=self._resolve_path,
+            )
+        return DefaultDataStoreClient(
+            resource_resolver=self._resource_resolver,
+            driver_registry=self._driver_registry,
+            url_parser=self._url_parser,
+        )

ronds_datastore_client-0.0.1/src/datastore_client/adapter/direct_url_resolver.py

@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+"""
+资源解析器
+- URN：通过 osUrl 调用 HTTP 接口获取资源对象
+- 直接 URL：解析 URL 得到连接信息
+"""
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from datastore_client.exceptions import DataStoreException
+from datastore_client.common.json_codec import JsonCodec
+from datastore_client.common.url_parser import UrlParser
+from datastore_client.model.resource import ResourceInfo, ResourceCategory, ResourceType
+
+
+def _get_string(m: Optional[Dict], key: str) -> Optional[str]:
+    if m is None:
+        return None
+    v = m.get(key)
+    return str(v) if v is not None else None
+
+
+def _map_driver_to_type(driver: Optional[str]) -> ResourceType:
+    if not driver:
+        return ResourceType.PGSQL
+    d = driver.lower()
+    mapping = {
+        "kafka": ResourceType.KAFKA,
+        "mqtt": ResourceType.MQTT,
+        "s3": ResourceType.S3,
+        "minio": ResourceType.MINIO,
+        "cassandra": ResourceType.CASSANDRA,
+        "redis": ResourceType.REDIS,
+        "pgsql": ResourceType.POSTGRESQL,
+        "postgresql": ResourceType.POSTGRESQL,
+    }
+    return mapping.get(d, ResourceType.POSTGRESQL)
+
+
+def _map_type_to_category(rt: ResourceType) -> ResourceCategory:
+    mapping = {
+        ResourceType.KAFKA: ResourceCategory.QUEUE,
+        ResourceType.MQTT: ResourceCategory.QUEUE,
+        ResourceType.S3: ResourceCategory.OBJECT,
+        ResourceType.MINIO: ResourceCategory.OBJECT,
+        ResourceType.CASSANDRA: ResourceCategory.DATABASE,
+        ResourceType.REDIS: ResourceCategory.CACHE,
+        ResourceType.PGSQL: ResourceCategory.DATABASE,
+        ResourceType.POSTGRESQL: ResourceCategory.DATABASE,
+    }
+    return mapping.get(rt, ResourceCategory.DATABASE)
+
+
+class DirectUrlResourceResolver:
+    """资源解析器"""
+
+    DEFAULT_RESOLVE_PATH = "/ui/system/datastore/urn/detail"
+
+    def __init__(
+        self,
+        os_url: Optional[str] = None,
+        resolve_path: Optional[str] = None,
+        url_parser: Optional[UrlParser] = None,
+        json_codec: Optional[JsonCodec] = None,
+    ):
+        self._os_url = os_url
+        self._resolve_path = resolve_path or self.DEFAULT_RESOLVE_PATH
+        self._url_parser = url_parser or UrlParser()
+        self._json_codec = json_codec or JsonCodec()
+
+    def resolve(self, urn: str) -> ResourceInfo:
+        if not urn or not urn.strip():
+            raise DataStoreException("URN or URL cannot be null or empty")
+        if urn.startswith("urn:"):
+            return self._resolve_by_urn(urn)
+        return self._resolve_by_direct_url(urn)
+
+    def _resolve_by_urn(self, urn: str) -> ResourceInfo:
+        if not self._os_url or not self._os_url.strip():
+            raise DataStoreException("URN resolution requires osUrl. Set osUrl when building DataStoreClient.")
+        try:
+            import requests
+            encoded_urn = quote(urn, safe="")
+            base = self._os_url.rstrip("/")
+            path = "/" + self._resolve_path.lstrip("/").rstrip("/")
+            if not path.endswith("/"):
+                path += "/"
+            url = base + path + encoded_urn
+            resp = requests.get(url, timeout=10)
+            if resp.status_code != 200:
+                raise DataStoreException(f"Failed to resolve URN: HTTP {resp.status_code}, {resp.text}")
+            return self._parse_get_with_details_response(urn, resp.text)
+        except DataStoreException:
+            raise
+        except Exception as e:
+            raise DataStoreException(f"Failed to resolve URN: {urn}", cause=e)
+
+    def _parse_get_with_details_response(self, urn: str, json_body: str) -> ResourceInfo:
+        root = self._json_codec.deserialize(json_body)
+        if root is None:
+            raise DataStoreException("Empty response from getWithDetails API")
+        data = root.get("data") if isinstance(root, dict) else None
+        if data is None or not isinstance(data, dict):
+            raise DataStoreException("API response missing data field")
+        data_store = data.get("dataStore")
+        if data_store is None:
+            raise DataStoreException("API response missing dataStore")
+        spec = data_store.get("spec") if isinstance(data_store, dict) else None
+        identify = data_store.get("identify") if isinstance(data_store, dict) else None
+        url = _get_string(data, "resolvedUrl")
+        if not url:
+            url = _get_string(spec, "url") if isinstance(spec, dict) else None
+        data_schema = _get_string(spec, "dataSchema") if isinstance(spec, dict) else None
+        display_name = urn
+        if isinstance(identify, dict):
+            display_name = _get_string(identify, "displayName") or _get_string(identify, "name") or urn
+        driver_type = None
+        driver_name = None
+        drivers = data.get("drivers")
+        if isinstance(drivers, list) and drivers:
+            first = drivers[0]
+            if isinstance(first, dict):
+                driver_spec = first.get("spec")
+                if isinstance(driver_spec, dict):
+                    driver_type = _get_string(driver_spec, "type")
+                    driver_name = _get_string(driver_spec, "driverName")
+        if not url or not url.strip():
+            raise DataStoreException("API response missing url in dataStore.spec")
+        if not driver_type or not driver_type.strip():
+            config = self._url_parser.parse(url)
+            driver_type = config.scheme
+        rt = _map_driver_to_type(driver_type)
+        category = _map_type_to_category(rt)
+        return ResourceInfo.builder() \
+            .urn(urn) \
+            .url(url) \
+            .data_schema(data_schema) \
+            .display_name(display_name or urn) \
+            .category(category) \
+            .type_(rt) \
+            .driver_scheme(driver_type.lower() if driver_type else None) \
+            .driver_name(driver_name) \
+            .build()
+
+    def _resolve_by_direct_url(self, url: str) -> ResourceInfo:
+        config = self._url_parser.parse(url)
+        rt = _map_driver_to_type(config.scheme)
+        category = _map_type_to_category(rt)
+        scheme_lower = config.scheme.lower() if config.scheme else None
+        return ResourceInfo.builder() \
+            .urn(url) \
+            .url(url) \
+            .data_schema(None) \
+            .display_name(config.entity or config.namespace or "") \
+            .category(category) \
+            .type_(rt) \
+            .driver_scheme(scheme_lower) \
+            .build()

ronds_datastore_client-0.0.1/src/datastore_client/adapter/driver_registry.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+"""
+驱动注册表
+使用 entry_points (datastore.drivers) 发现驱动，类似 Java ServiceLoader
+"""
+from typing import Optional
+import sys
+
+from datastore_client.exceptions import DataStoreException
+from datastore_client.spi.driver import DataStoreDriver
+
+
+def _iter_entry_points(group: str):
+    """Python 3.8 兼容：使用 pkg_resources"""
+    try:
+        import pkg_resources
+        return pkg_resources.iter_entry_points(group=group)
+    except ImportError:
+        pass
+    if sys.version_info >= (3, 10):
+        from importlib.metadata import entry_points
+        eps = entry_points()
+        if hasattr(eps, "get"):
+            return eps.get(group, [])
+        return getattr(eps, "select", lambda **k: [])(group=group) if hasattr(eps, "select") else []
+    return []
+
+
+class DriverRegistry:
+    """驱动注册表"""
+
+    def __init__(self):
+        self._drivers: list = []
+        self._reload()
+
+    def _reload(self) -> None:
+        self._drivers = []
+        seen_types = set()  # 按驱动类型去重，避免同一类被多个 entry_point 重复加载
+        for ep in _iter_entry_points("datastore.drivers"):
+            try:
+                loaded = ep.load()
+                if isinstance(loaded, DataStoreDriver):
+                    driver = loaded
+                elif isinstance(loaded, type) and issubclass(loaded, DataStoreDriver):
+                    driver = loaded()
+                else:
+                    continue
+                driver_type = type(driver)
+                if driver_type not in seen_types:
+                    seen_types.add(driver_type)
+                    self._drivers.append(driver)
+            except Exception as e:
+                raise DataStoreException(f"Failed to load driver {ep.name}: {e}", cause=e)
+
+    def find_driver(self, scheme: str) -> Optional[DataStoreDriver]:
+        """根据 scheme 查找驱动"""
+        scheme_lower = (scheme or "").lower()
+        for d in self._drivers:
+            if d.accepts(scheme_lower):
+                return d
+        return None
+
+    def ensure_driver_loaded(self, driver_name: str) -> None:
+        """按需加载驱动（Python 无 JAR，可尝试 import 扩展包）"""
+        try:
+            __import__(driver_name.replace("-", "_"))
+            self._reload()
+        except ImportError:
+            pass
+
+    def reload(self) -> None:
+        """重新加载所有驱动"""
+        self._reload()

ronds_datastore_client-0.0.1/src/datastore_client/client.py

@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""
+DataStoreClient 统一接口
+仅负责连接管理，CRUD 操作通过 connect 返回的 DataStoreConnection 进行
+"""
+from abc import ABC, abstractmethod
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datastore_client.model.resource import ResourceInfo
+    from datastore_client.spi.connection import DataStoreConnection
+
+
+class DataStoreClient(ABC):
+    """统一数据存储客户端接口"""
+
+    @abstractmethod
+    def connect(self, urn: str) -> "DataStoreConnection":
+        """建立与指定数据资源的连接"""
+        pass
+
+    @abstractmethod
+    def disconnect(self, urn: Optional[str] = None) -> None:
+        """断开指定 URN 或所有连接"""
+        pass
+
+    @abstractmethod
+    def is_connected(self, urn: str) -> bool:
+        """是否已连接指定 URN"""
+        pass
+
+    @abstractmethod
+    def get_resource(self, urn: str) -> Optional["ResourceInfo"]:
+        """获取指定 URN 的资源信息"""
+        pass
+
+    @abstractmethod
+    def get_connection(self, urn: str) -> Optional["DataStoreConnection"]:
+        """获取指定 URN 的连接"""
+        pass
+
+    def close(self) -> None:
+        """关闭所有连接"""
+        self.disconnect()
+
+    def __enter__(self) -> "DataStoreClient":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()

ronds_datastore_client-0.0.1/src/datastore_client/common/__init__.py

@@ -0,0 +1,11 @@
+"""Common utilities for DataStore SDK."""
+
+from .url_parser import UrlParser
+from .json_codec import JsonCodec
+from .schema_validator import SchemaValidator
+
+__all__ = [
+    "UrlParser",
+    "JsonCodec",
+    "SchemaValidator",
+]

ronds_datastore_client-0.0.1/src/datastore_client/common/json_codec.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""
+JSON 编解码器
+"""
+import json
+from typing import Any, Type, TypeVar, Optional
+
+from datastore_client.exceptions import DataStoreException
+
+T = TypeVar("T")
+
+
+class JsonCodec:
+    def __init__(self, default=None):
+        self._default = default
+
+    def serialize(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            return json.dumps(value, default=self._default, ensure_ascii=False)
+        except Exception as e:
+            raise DataStoreException("JSON serialize failed", cause=e)
+
+    def serialize_to_bytes(self, value: Any) -> Optional[bytes]:
+        s = self.serialize(value)
+        return s.encode("utf-8") if s else None
+
+    def deserialize(self, json_str: Optional[str], type_ref: Type[T] = None) -> Optional[T]:
+        if not json_str or not json_str.strip():
+            return None
+        try:
+            data = json.loads(json_str)
+            if type_ref and type_ref != dict and type_ref != list:
+                return data
+            return data
+        except Exception as e:
+            raise DataStoreException("JSON deserialize failed", cause=e)
+
+    def deserialize_bytes(self, data: Optional[bytes], type_ref: Type[T] = None) -> Optional[T]:
+        if not data:
+            return None
+        return self.deserialize(data.decode("utf-8"), type_ref)