tamar-file-hub-client 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

file_hub_client/__init__.py

@@ -45,6 +45,26 @@ from .schemas import (
     UserContext,
     RequestContext,
     FullContext,
+    # Taple 相关模型
+    Table,
+    Sheet,
+    Column,
+    Row,
+    Cell,
+    MergedCell,
+    TableView,
+    CellUpdate,
+    TableViewResponse,
+    BatchCreateTableViewResult,
+    BatchCreateTableViewsResponse,
+    ListTableViewsResponse,
+)
+
+# 幂等性工具
+from .utils.idempotency import (
+    IdempotencyKeyGenerator,
+    IdempotencyManager,
+    generate_idempotency_key,
 )
 
 __all__ = [
@@ -68,6 +88,20 @@ __all__ = [
     "FolderInfo",
     "FolderListResponse",
 
+    # Taple 相关模型
+    "Table",
+    "Sheet",
+    "Column",
+    "Row",
+    "Cell",
+    "MergedCell",
+    "TableView",
+    "CellUpdate",
+    "TableViewResponse",
+    "BatchCreateTableViewResult",
+    "BatchCreateTableViewsResponse",
+    "ListTableViewsResponse",
+
     # 枚举
     "Role",
     "UploadMode",
@@ -85,4 +119,9 @@ __all__ = [
     "ConnectionError",
     "TimeoutError",
     "PermissionError",
+    
+    # 幂等性工具
+    "IdempotencyKeyGenerator",
+    "IdempotencyManager",
+    "generate_idempotency_key",
 ]

file_hub_client/client.py

@@ -15,9 +15,11 @@ from .services import (
     AsyncBlobService,
     AsyncFileService,
     AsyncFolderService,
+    AsyncTapleService,
     SyncBlobService,
     SyncFileService,
     SyncFolderService,
+    SyncTapleService,
 )
 from .schemas.context import UserContext, RequestContext
 
@@ -37,13 +39,15 @@ class AsyncTamarFileHubClient:
             default_metadata: Optional[Dict[str, str]] = None,
             user_context: Optional[UserContext] = None,
             request_context: Optional[RequestContext] = None,
+            enable_logging: bool = True,
+            log_level: str = "INFO",
     ):
         """
         初始化客户端
         
         Args:
-            host: 服务器地址（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
-            port: 服务器端口（默认从环境变量 FILE_HUB_PORT 读取，否则使用 50051）
+            host: 服务器地址，可以是域名或IP（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
+            port: 服务器端口，可选参数，不指定时直接使用host作为完整地址（默认从环境变量 FILE_HUB_PORT 读取）
             secure: 是否使用TLS（默认从环境变量 FILE_HUB_SECURE 读取，否则使用 False）
             credentials: 认证凭据
             auto_connect: 是否自动连接（默认 True）
@@ -63,7 +67,12 @@ class AsyncTamarFileHubClient:
         """
         # 从环境变量或参数获取配置
         self._host = host or os.getenv('FILE_HUB_HOST', 'localhost')
-        self._port = port or int(os.getenv('FILE_HUB_PORT', '50051'))
+        # 端口处理：如果有环境变量且不为空，则使用；否则使用参数值（可能为None）
+        env_port = os.getenv('FILE_HUB_PORT')
+        if env_port:
+            self._port = int(env_port)
+        else:
+            self._port = port
         self._secure = secure if secure is not None else os.getenv('FILE_HUB_SECURE', 'false').lower() == 'true'
         self._retry_count = retry_count or int(os.getenv('FILE_HUB_RETRY_COUNT', '3'))
         self._retry_delay = retry_delay or float(os.getenv('FILE_HUB_RETRY_DELAY', '1.0'))
@@ -87,10 +96,13 @@ class AsyncTamarFileHubClient:
             default_metadata=default_metadata,
             user_context=user_context,
             request_context=request_context,
+            enable_logging=enable_logging,
+            log_level=log_level,
         )
         self._blob_service = None
         self._file_service = None
         self._folder_service = None
+        self._taple_service = None
         self._auto_connect = auto_connect
         self._connected = False
 
@@ -120,6 +132,13 @@ class AsyncTamarFileHubClient:
             self._folder_service = AsyncFolderService(self._client)
         return self._folder_service
 
+    @property
+    def taples(self) -> AsyncTapleService:
+        """获取 Taple 服务"""
+        if self._taple_service is None:
+            self._taple_service = AsyncTapleService(self._client)
+        return self._taple_service
+
     def set_user_context(self, org_id: str, user_id: str, role: Role = Role.ACCOUNT, actor_id: Optional[str] = None):
         """
         设置用户上下文信息
@@ -207,13 +226,15 @@ class TamarFileHubClient:
             default_metadata: Optional[Dict[str, str]] = None,
             user_context: Optional[UserContext] = None,
             request_context: Optional[RequestContext] = None,
+            enable_logging: bool = True,
+            log_level: str = "INFO",
     ):
         """
         初始化客户端
         
         Args:
-            host: 服务器地址（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
-            port: 服务器端口（默认从环境变量 FILE_HUB_PORT 读取，否则使用 50051）
+            host: 服务器地址，可以是域名或IP（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
+            port: 服务器端口，可选参数，不指定时直接使用host作为完整地址（默认从环境变量 FILE_HUB_PORT 读取）
             secure: 是否使用TLS（默认从环境变量 FILE_HUB_SECURE 读取，否则使用 False）
             credentials: 认证凭据
             auto_connect: 是否自动连接（默认 True）
@@ -233,7 +254,12 @@ class TamarFileHubClient:
         """
         # 从环境变量或参数获取配置
         self._host = host or os.getenv('FILE_HUB_HOST', 'localhost')
-        self._port = port or int(os.getenv('FILE_HUB_PORT', '50051'))
+        # 端口处理：如果有环境变量且不为空，则使用；否则使用参数值（可能为None）
+        env_port = os.getenv('FILE_HUB_PORT')
+        if env_port:
+            self._port = int(env_port)
+        else:
+            self._port = port
         self._secure = secure if secure is not None else os.getenv('FILE_HUB_SECURE', 'false').lower() == 'true'
         self._retry_count = retry_count or int(os.getenv('FILE_HUB_RETRY_COUNT', '3'))
         self._retry_delay = retry_delay or float(os.getenv('FILE_HUB_RETRY_DELAY', '1.0'))
@@ -257,10 +283,13 @@ class TamarFileHubClient:
             default_metadata=default_metadata,
             user_context=user_context,
             request_context=request_context,
+            enable_logging=enable_logging,
+            log_level=log_level,
         )
         self._blob_service = None
         self._file_service = None
         self._folder_service = None
+        self._taple_service = None
         self._auto_connect = auto_connect
         self._connected = False
 
@@ -293,6 +322,14 @@ class TamarFileHubClient:
             self._folder_service = SyncFolderService(self._client)
         return self._folder_service
 
+    @property
+    def taples(self) -> SyncTapleService:
+        """获取 Taple 服务"""
+        self._ensure_connected()
+        if self._taple_service is None:
+            self._taple_service = SyncTapleService(self._client)
+        return self._taple_service
+
     def set_user_context(self, org_id: str, user_id: str, role: Role = Role.ACCOUNT, actor_id: Optional[str] = None):
         """
         设置用户上下文信息

file_hub_client/rpc/async_client.py

@@ -13,6 +13,9 @@ from typing import Optional, Dict, List, Tuple
 from ..enums import Role
 from ..errors import ConnectionError
 from ..schemas.context import UserContext, RequestContext, FullContext
+from ..utils.logging import get_logger, setup_logging
+from .interceptors import create_async_interceptors
+import logging
 
 
 class AsyncGrpcClient:
@@ -21,7 +24,7 @@ class AsyncGrpcClient:
     def __init__(
             self,
             host: str = "localhost",
-            port: int = 50051,
+            port: Optional[int] = None,
             secure: bool = False,
             credentials: Optional[dict] = None,
             options: Optional[list] = None,
@@ -30,13 +33,15 @@ class AsyncGrpcClient:
             default_metadata: Optional[Dict[str, str]] = None,
             user_context: Optional[UserContext] = None,
             request_context: Optional[RequestContext] = None,
+            enable_logging: bool = True,
+            log_level: str = "INFO",
     ):
         """
         初始化异步gRPC客户端
         
         Args:
-            host: 服务器地址
-            port: 服务器端口
+            host: 服务器地址（可以是域名或IP）
+            port: 服务器端口（可选，如果不指定则根据secure自动选择）
             secure: 是否使用安全连接（TLS）
             credentials: 认证凭据字典（如 {'api_key': 'xxx'}）
             options: gRPC通道选项
@@ -45,10 +50,19 @@ class AsyncGrpcClient:
             default_metadata: 默认的元数据（如 org_id, user_id 等）
             user_context: 用户上下文
             request_context: 请求上下文
+            enable_logging: 是否启用日志记录
+            log_level: 日志级别
         """
         self.host = host
         self.port = port
-        self.address = f"{host}:{port}"
+        
+        # 构建地址：如果没有指定端口，则使用域名作为地址
+        if port is not None:
+            self.address = f"{host}:{port}"
+        else:
+            # 如果没有指定端口，直接使用host
+            # gRPC会自动根据secure选择默认端口（80/443）
+            self.address = host
         self.secure = secure
         self.credentials = credentials
         self.options = options or []
@@ -58,6 +72,20 @@ class AsyncGrpcClient:
         self._channel: Optional[grpc.aio.Channel] = None
         self._stubs = {}
         self._stub_lock = asyncio.Lock()
+        
+        # 日志配置
+        self.enable_logging = enable_logging
+        self.log_level = log_level
+        
+        # 只有在明确启用日志时才设置SDK日志
+        # 默认不设置，让用户自己控制
+        if enable_logging:
+            # 检查是否已经有处理器，避免重复设置
+            sdk_logger = get_logger()
+            if not sdk_logger.handlers:
+                setup_logging(level=log_level, enable_grpc_logging=True, use_json_format=True)
+        
+        self.logger = get_logger()
 
         # 上下文管理
         self._user_context = user_context
@@ -85,7 +113,7 @@ class AsyncGrpcClient:
         return RequestContext(
             client_ip=client_ip,
             client_type="python-sdk",
-            client_version="1.0.0",  # TODO: 从包版本获取
+            client_version="1.0.0",
             user_agent=f"FileHubClient/1.0.0 Python/{platform.python_version()} {platform.system()}/{platform.release()}"
         )
 
@@ -125,16 +153,21 @@ class AsyncGrpcClient:
 
                 channel_credentials = self._create_channel_credentials()
 
+                # 创建拦截器
+                interceptors = create_async_interceptors() if self.enable_logging else []
+
                 if channel_credentials:
                     self._channel = grpc.aio.secure_channel(
                         self.address,
                         channel_credentials,
-                        options=self.options
+                        options=self.options,
+                        interceptors=interceptors
                     )
                 else:
                     self._channel = grpc.aio.insecure_channel(
                         self.address,
-                        options=self.options
+                        options=self.options,
+                        interceptors=interceptors
                     )
 
                 # 连接
@@ -144,12 +177,41 @@ class AsyncGrpcClient:
                     raise ConnectionError(f"连接超时：{self.address}")
 
                 # 连接成功
+                if self.enable_logging:
+                    log_record = logging.LogRecord(
+                        name=self.logger.name,
+                        level=logging.INFO,
+                        pathname="",
+                        lineno=0,
+                        msg=f"🔗 已连接到 gRPC 服务器",
+                        args=(),
+                        exc_info=None
+                    )
+                    log_record.log_type = "info"
+                    log_record.data = {"server": self.address}
+                    self.logger.handle(log_record)
                 return
 
             except Exception as e:
                 last_error = e
                 if attempt < self.retry_count - 1:
-                    print(f"连接失败 (尝试 {attempt + 1}/{self.retry_count}): {str(e)}")
+                    if self.enable_logging:
+                        log_record = logging.LogRecord(
+                            name=self.logger.name,
+                            level=logging.WARNING,
+                            pathname="",
+                            lineno=0,
+                            msg=f"⚠️ 连接失败，正在重试",
+                            args=(),
+                            exc_info=None
+                        )
+                        log_record.log_type = "info"
+                        log_record.data = {
+                            "attempt": attempt + 1,
+                            "max_attempts": self.retry_count,
+                            "error": str(e)
+                        }
+                        self.logger.handle(log_record)
                     if self._channel:
                         await self._channel.close()
                         self._channel = None
@@ -167,6 +229,19 @@ class AsyncGrpcClient:
     async def close(self):
         """关闭连接"""
         if self._channel:
+            if self.enable_logging:
+                log_record = logging.LogRecord(
+                    name=self.logger.name,
+                    level=logging.INFO,
+                    pathname="",
+                    lineno=0,
+                    msg=f"👋 正在关闭 gRPC 连接",
+                    args=(),
+                    exc_info=None
+                )
+                log_record.log_type = "info"
+                log_record.data = {"server": self.address}
+                self.logger.handle(log_record)
             await self._channel.close()
             self._channel = None
             self._stubs.clear()
@@ -190,11 +265,12 @@ class AsyncGrpcClient:
                 self._stubs[stub_name] = stub_class(self._channel)
             return self._stubs[stub_name]
 
-    def build_metadata(self, **kwargs) -> List[Tuple[str, str]]:
+    def build_metadata(self, *, request_id: Optional[str] = None, **kwargs) -> List[Tuple[str, str]]:
         """
         构建请求元数据
         
         Args:
+            request_id: 显式指定的请求ID，如果提供则优先使用
             **kwargs: 要覆盖或添加的元数据
             
         Returns:
@@ -208,8 +284,12 @@ class AsyncGrpcClient:
         # 添加/覆盖传入的元数据
         metadata.update(kwargs)
 
-        # 如果没有 request_id，自动生成一个
-        if 'x-request-id' not in metadata:
+        # 处理 request_id（优先级：显式传入 > metadata中的x-request-id > RequestContext > 自动生成）
+        if request_id is not None:
+            # 优先使用显式传入的 request_id
+            metadata['x-request-id'] = request_id
+        elif 'x-request-id' not in metadata:
+            # 如果没有显式传入且metadata中也没有，则尝试从RequestContext获取或自动生成
             metadata['x-request-id'] = (
                     self._request_context.extra.get("request_id") or str(uuid.uuid4())
             )