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

file_hub_client/__init__.py

@@ -0,0 +1,88 @@
+"""
+文件管理系统客户端SDK
+
+一个基于gRPC的文件管理系统Python客户端SDK，支持：
+- 文件和文件夹的增删改查
+- 多种上传模式（普通上传、断点续传、流式上传、客户端直传）
+- 传统文件类型和自定义文件类型
+- 文件导出（将自定义文件类型导出为传统格式）
+- 直接操作对象存储
+- 同时支持同步和异步API
+"""
+
+from .client import (
+    AsyncTamarFileHubClient,
+    TamarFileHubClient,
+    tamar_client,  # 默认的同步客户端单例
+    async_tamar_client,  # 默认的异步客户端单例
+    get_client,  # 获取同步客户端单例的函数
+    get_async_client,  # 获取异步客户端单例的函数
+)
+
+from .enums import Role, UploadMode, ExportFormat
+from .errors import (
+    FileHubError,
+    FileNotFoundError,
+    FolderNotFoundError,
+    UploadError,
+    DownloadError,
+    ExportError,
+    StorageError,
+    ValidationError,
+    ConnectionError,
+    TimeoutError,
+    PermissionError,
+)
+from .schemas import (
+    File,
+    UploadUrlResponse,
+    ShareLinkRequest,
+    FileVisitRequest,
+    FileListRequest,
+    FileListResponse,
+    FolderInfo,
+    FolderListResponse,
+    UserContext,
+    RequestContext,
+    FullContext,
+)
+
+__all__ = [
+    # 客户端
+    "AsyncTamarFileHubClient",
+    "TamarFileHubClient",
+    "tamar_client",  # 默认同步客户端单例
+    "async_tamar_client",  # 默认异步客户端单例
+    "get_client",
+    "get_async_client",
+
+    # 文件相关模型
+    "File",
+    "UploadUrlResponse",
+    "ShareLinkRequest",
+    "FileVisitRequest",
+    "FileListRequest",
+    "FileListResponse",
+
+    # 文件夹相关模型
+    "FolderInfo",
+    "FolderListResponse",
+
+    # 枚举
+    "Role",
+    "UploadMode",
+    "ExportFormat",
+
+    # 异常
+    "FileHubError",
+    "FileNotFoundError",
+    "FolderNotFoundError",
+    "UploadError",
+    "DownloadError",
+    "ExportError",
+    "StorageError",
+    "ValidationError",
+    "ConnectionError",
+    "TimeoutError",
+    "PermissionError",
+]

file_hub_client/client.py

@@ -0,0 +1,414 @@
+"""
+文件管理系统客户端
+
+提供与文件管理系统交互的客户端接口
+"""
+import os
+import threading
+from asyncio import Lock
+from typing import Optional, Dict
+
+from .enums import Role
+from .rpc.async_client import AsyncGrpcClient
+from .rpc.sync_client import SyncGrpcClient
+from .services import (
+    AsyncBlobService,
+    AsyncFileService,
+    AsyncFolderService,
+    SyncBlobService,
+    SyncFileService,
+    SyncFolderService,
+)
+from .schemas.context import UserContext, RequestContext
+
+
+class AsyncTamarFileHubClient:
+    """异步文件管理系统客户端"""
+
+    def __init__(
+            self,
+            host: Optional[str] = None,
+            port: Optional[int] = None,
+            secure: Optional[bool] = None,
+            credentials: Optional[dict] = None,
+            auto_connect: bool = True,
+            retry_count: Optional[int] = None,
+            retry_delay: Optional[float] = None,
+            default_metadata: Optional[Dict[str, str]] = None,
+            user_context: Optional[UserContext] = None,
+            request_context: Optional[RequestContext] = None,
+    ):
+        """
+        初始化客户端
+        
+        Args:
+            host: 服务器地址（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
+            port: 服务器端口（默认从环境变量 FILE_HUB_PORT 读取，否则使用 50051）
+            secure: 是否使用TLS（默认从环境变量 FILE_HUB_SECURE 读取，否则使用 False）
+            credentials: 认证凭据
+            auto_connect: 是否自动连接（默认 True）
+            retry_count: 连接重试次数（默认从环境变量 FILE_HUB_RETRY_COUNT 读取，否则使用 3）
+            retry_delay: 重试延迟秒数（默认从环境变量 FILE_HUB_RETRY_DELAY 读取，否则使用 1.0）
+            default_metadata: 默认的元数据（如 org_id, user_id 等）
+            user_context: 用户上下文
+            request_context: 请求上下文
+            
+        环境变量：
+            FILE_HUB_HOST: gRPC 服务器地址
+            FILE_HUB_PORT: gRPC 服务器端口
+            FILE_HUB_SECURE: 是否启用 TLS（true/false）
+            FILE_HUB_API_KEY: API 密钥（如果需要）
+            FILE_HUB_RETRY_COUNT: 连接重试次数
+            FILE_HUB_RETRY_DELAY: 重试延迟（秒）
+        """
+        # 从环境变量或参数获取配置
+        self._host = host or os.getenv('FILE_HUB_HOST', 'localhost')
+        self._port = port or int(os.getenv('FILE_HUB_PORT', '50051'))
+        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'))
+        self._connect_lock = Lock()
+
+        # 处理认证凭据
+        if credentials is None and os.getenv('FILE_HUB_API_KEY'):
+            credentials = {'api_key': os.getenv('FILE_HUB_API_KEY')}
+
+        # 处理默认元数据
+        if default_metadata is None:
+            default_metadata = {}
+
+        self._client = AsyncGrpcClient(
+            self._host,
+            self._port,
+            self._secure,
+            credentials,
+            retry_count=self._retry_count,
+            retry_delay=self._retry_delay,
+            default_metadata=default_metadata,
+            user_context=user_context,
+            request_context=request_context,
+        )
+        self._blob_service = None
+        self._file_service = None
+        self._folder_service = None
+        self._auto_connect = auto_connect
+        self._connected = False
+
+    async def _ensure_connected(self):
+        """确保客户端已连接"""
+        if not self._connected and self._auto_connect:
+            await self.connect()
+
+    @property
+    def blobs(self) -> AsyncBlobService:
+        """获取文件服务"""
+        if self._blob_service is None:
+            self._blob_service = AsyncBlobService(self._client)
+        return self._blob_service
+
+    @property
+    def files(self) -> AsyncFileService:
+        """获取文件服务"""
+        if self._file_service is None:
+            self._file_service = AsyncFileService(self._client)
+        return self._file_service
+
+    @property
+    def folders(self) -> AsyncFolderService:
+        """获取文件夹服务"""
+        if self._folder_service is None:
+            self._folder_service = AsyncFolderService(self._client)
+        return self._folder_service
+
+    def set_user_context(self, org_id: str, user_id: str, role: Role = Role.ACCOUNT, actor_id: Optional[str] = None):
+        """
+        设置用户上下文信息
+        
+        Args:
+            org_id: 组织ID
+            user_id: 用户ID
+            role: 用户角色（默认为 ACCOUNT）
+            actor_id: 操作者ID（如果不同于 user_id）
+        """
+        self._client.set_user_context(org_id, user_id, role, actor_id)
+
+    def get_user_context(self) -> Optional[UserContext]:
+        """获取当前用户上下文"""
+        return self._client.get_user_context()
+
+    def clear_user_context(self):
+        """清除用户上下文信息"""
+        self._client.clear_user_context()
+
+    def set_request_context(self, request_context: RequestContext):
+        """设置请求上下文"""
+        self._client.set_request_context(request_context)
+
+    def get_request_context(self) -> RequestContext:
+        """获取当前请求上下文"""
+        return self._client.get_request_context()
+
+    def update_request_context(self, **kwargs):
+        """
+        更新请求上下文的部分字段
+        
+        Args:
+            client_ip: 客户端IP地址
+            client_version: 客户端版本
+            client_type: 客户端类型
+            user_agent: User-Agent信息
+            extra: 额外的元数据字典
+        """
+        self._client.update_request_context(**kwargs)
+
+    def update_metadata(self, **kwargs):
+        """
+        更新默认元数据
+        
+        Args:
+            **kwargs: 要更新的元数据键值对
+        """
+        self._client.update_default_metadata(**kwargs)
+
+    async def connect(self):
+        """连接到服务器"""
+        if not self._connected:
+            async with self._connect_lock:
+                if not self._connected:
+                    await self._client.connect()
+                    self._connected = True
+
+    async def close(self):
+        """关闭连接"""
+        if self._connected:
+            await self._client.close()
+            self._connected = False
+
+    async def __aenter__(self) -> "AsyncTamarFileHubClient":
+        await self._ensure_connected()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+
+class TamarFileHubClient:
+    """同步文件管理系统客户端"""
+
+    def __init__(
+            self,
+            host: Optional[str] = None,
+            port: Optional[int] = None,
+            secure: Optional[bool] = None,
+            credentials: Optional[dict] = None,
+            auto_connect: bool = True,
+            retry_count: Optional[int] = None,
+            retry_delay: Optional[float] = None,
+            default_metadata: Optional[Dict[str, str]] = None,
+            user_context: Optional[UserContext] = None,
+            request_context: Optional[RequestContext] = None,
+    ):
+        """
+        初始化客户端
+        
+        Args:
+            host: 服务器地址（默认从环境变量 FILE_HUB_HOST 读取，否则使用 localhost）
+            port: 服务器端口（默认从环境变量 FILE_HUB_PORT 读取，否则使用 50051）
+            secure: 是否使用TLS（默认从环境变量 FILE_HUB_SECURE 读取，否则使用 False）
+            credentials: 认证凭据
+            auto_connect: 是否自动连接（默认 True）
+            retry_count: 连接重试次数（默认从环境变量 FILE_HUB_RETRY_COUNT 读取，否则使用 3）
+            retry_delay: 重试延迟秒数（默认从环境变量 FILE_HUB_RETRY_DELAY 读取，否则使用 1.0）
+            default_metadata: 默认的元数据（如 org_id, user_id 等）
+            user_context: 用户上下文
+            request_context: 请求上下文
+            
+        环境变量：
+            FILE_HUB_HOST: gRPC 服务器地址
+            FILE_HUB_PORT: gRPC 服务器端口
+            FILE_HUB_SECURE: 是否启用 TLS（true/false）
+            FILE_HUB_API_KEY: API 密钥（如果需要）
+            FILE_HUB_RETRY_COUNT: 连接重试次数
+            FILE_HUB_RETRY_DELAY: 重试延迟（秒）
+        """
+        # 从环境变量或参数获取配置
+        self._host = host or os.getenv('FILE_HUB_HOST', 'localhost')
+        self._port = port or int(os.getenv('FILE_HUB_PORT', '50051'))
+        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'))
+        self._connect_lock = threading.Lock()
+
+        # 处理认证凭据
+        if credentials is None and os.getenv('FILE_HUB_API_KEY'):
+            credentials = {'api_key': os.getenv('FILE_HUB_API_KEY')}
+
+        # 处理默认元数据
+        if default_metadata is None:
+            default_metadata = {}
+
+        self._client = SyncGrpcClient(
+            self._host,
+            self._port,
+            self._secure,
+            credentials,
+            retry_count=self._retry_count,
+            retry_delay=self._retry_delay,
+            default_metadata=default_metadata,
+            user_context=user_context,
+            request_context=request_context,
+        )
+        self._blob_service = None
+        self._file_service = None
+        self._folder_service = None
+        self._auto_connect = auto_connect
+        self._connected = False
+
+    def _ensure_connected(self):
+        """确保客户端已连接"""
+        if not self._connected and self._auto_connect:
+            self.connect()
+
+    @property
+    def blobs(self) -> SyncBlobService:
+        """获取文件服务"""
+        self._ensure_connected()
+        if self._blob_service is None:
+            self._blob_service = SyncBlobService(self._client)
+        return self._blob_service
+
+    @property
+    def files(self) -> SyncFileService:
+        """获取文件服务"""
+        self._ensure_connected()
+        if self._file_service is None:
+            self._file_service = SyncFileService(self._client)
+        return self._file_service
+
+    @property
+    def folders(self) -> SyncFolderService:
+        """获取文件夹服务"""
+        self._ensure_connected()
+        if self._folder_service is None:
+            self._folder_service = SyncFolderService(self._client)
+        return self._folder_service
+
+    def set_user_context(self, org_id: str, user_id: str, role: Role = Role.ACCOUNT, actor_id: Optional[str] = None):
+        """
+        设置用户上下文信息
+
+        Args:
+            org_id: 组织ID
+            user_id: 用户ID
+            role: 用户角色（默认为 ACCOUNT）
+            actor_id: 操作者ID（如果不同于 user_id）
+        """
+        self._client.set_user_context(org_id, user_id, role, actor_id)
+
+    def get_user_context(self) -> Optional[UserContext]:
+        """获取当前用户上下文"""
+        return self._client.get_user_context()
+
+    def clear_user_context(self):
+        """清除用户上下文信息"""
+        self._client.clear_user_context()
+
+    def set_request_context(self, request_context: RequestContext):
+        """设置请求上下文"""
+        self._client.set_request_context(request_context)
+
+    def get_request_context(self) -> RequestContext:
+        """获取当前请求上下文"""
+        return self._client.get_request_context()
+
+    def update_request_context(self, **kwargs):
+        """
+        更新请求上下文的部分字段
+        
+        Args:
+            client_ip: 客户端IP地址
+            client_version: 客户端版本
+            client_type: 客户端类型
+            user_agent: User-Agent信息
+            extra: 额外的元数据字典
+        """
+        self._client.update_request_context(**kwargs)
+
+    def update_metadata(self, **kwargs):
+        """
+        更新默认元数据
+        
+        Args:
+            **kwargs: 要更新的元数据键值对
+        """
+        self._client.update_default_metadata(**kwargs)
+
+    def connect(self):
+        """连接到服务器"""
+        if not self._connected:
+            with self._connect_lock:
+                if not self._connected:
+                    self._client.connect()
+                    self._connected = True
+
+    def close(self):
+        """关闭连接"""
+        if self._connected:
+            self._client.close()
+            self._connected = False
+
+    def __enter__(self) -> "TamarFileHubClient":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def __del__(self):
+        """析构函数，确保连接被关闭"""
+        try:
+            self.close()
+        except:
+            pass
+
+
+# 创建默认的单例客户端实例
+_default_client = None
+_default_async_client = None
+
+
+def get_client(**kwargs) -> TamarFileHubClient:
+    """
+    获取默认的同步客户端实例（单例）
+    
+    Args:
+        **kwargs: 客户端初始化参数，仅在第一次调用时生效
+        
+    Returns:
+        TamarFileHubClient: 同步客户端实例
+    """
+    global _default_client
+    if _default_client is None:
+        _default_client = TamarFileHubClient(**kwargs)
+    return _default_client
+
+
+def get_async_client(**kwargs) -> AsyncTamarFileHubClient:
+    """
+    获取默认的异步客户端实例（单例）
+    
+    Args:
+        **kwargs: 客户端初始化参数，仅在第一次调用时生效
+        
+    Returns:
+        AsyncTamarFileHubClient: 异步客户端实例
+    """
+    global _default_async_client
+    if _default_async_client is None:
+        _default_async_client = AsyncTamarFileHubClient(**kwargs)
+    return _default_async_client
+
+
+# 默认客户端实例（自动从环境变量读取配置）
+tamar_client = get_client()
+async_tamar_client = get_async_client()

file_hub_client/enums/__init__.py

@@ -0,0 +1,12 @@
+"""
+枚举类型定义
+"""
+from .role import Role
+from .upload_mode import UploadMode
+from .export_format import ExportFormat
+
+__all__ = [
+    "UploadMode",
+    "ExportFormat",
+    "Role",
+]

file_hub_client/enums/export_format.py

@@ -0,0 +1,16 @@
+"""
+导出格式枚举
+"""
+from enum import Enum
+
+
+class ExportFormat(Enum):
+    """导出格式（用于自定义文件类型）"""
+    PDF = "pdf"
+    DOCX = "docx"
+    XLSX = "xlsx"
+    PPTX = "pptx"
+    HTML = "html"
+    MARKDOWN = "markdown"
+    JSON = "json"
+    CSV = "csv" 

file_hub_client/enums/role.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Role(str, Enum):
+    ACCOUNT = "account"
+    AGENT = "agent"
+    SYSTEM = "system"

file_hub_client/enums/upload_mode.py

@@ -0,0 +1,11 @@
+"""
+上传模式枚举
+"""
+from enum import Enum
+
+
+class UploadMode(str, Enum):
+    """上传模式"""
+    NORMAL = "normal"  # 普通上传
+    STREAM = "stream"  # 流式上传
+    RESUMABLE = "resumable"  # 断点续传

file_hub_client/errors/__init__.py

@@ -0,0 +1,30 @@
+"""
+错误和异常定义
+"""
+from .exceptions import (
+    FileHubError,
+    FileNotFoundError,
+    FolderNotFoundError,
+    PermissionError,
+    StorageError,
+    UploadError,
+    DownloadError,
+    ExportError,
+    ValidationError,
+    ConnectionError,
+    TimeoutError,
+)
+
+__all__ = [
+    "FileHubError",
+    "FileNotFoundError",
+    "FolderNotFoundError",
+    "PermissionError",
+    "StorageError",
+    "UploadError",
+    "DownloadError",
+    "ExportError",
+    "ValidationError",
+    "ConnectionError",
+    "TimeoutError",
+]

file_hub_client/errors/exceptions.py

@@ -0,0 +1,93 @@
+"""
+异常类定义
+"""
+from typing import Optional, Any
+
+
+class FileHubError(Exception):
+    """文件管理系统基础异常"""
+    
+    def __init__(self, message: str, code: Optional[str] = None, details: Optional[Any] = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.details = details
+
+
+class FileNotFoundError(FileHubError):
+    """文件不存在异常"""
+    
+    def __init__(self, file_id: str):
+        super().__init__(f"文件不存在: {file_id}", code="FILE_NOT_FOUND")
+        self.file_id = file_id
+
+
+class FolderNotFoundError(FileHubError):
+    """文件夹不存在异常"""
+    
+    def __init__(self, folder_id: str):
+        super().__init__(f"文件夹不存在: {folder_id}", code="FOLDER_NOT_FOUND")
+        self.folder_id = folder_id
+
+
+class PermissionError(FileHubError):
+    """权限不足异常"""
+    
+    def __init__(self, message: str):
+        super().__init__(message, code="PERMISSION_DENIED")
+
+
+class StorageError(FileHubError):
+    """存储操作异常"""
+    
+    def __init__(self, message: str, operation: Optional[str] = None):
+        super().__init__(message, code="STORAGE_ERROR")
+        self.operation = operation
+
+
+class UploadError(FileHubError):
+    """上传异常"""
+    
+    def __init__(self, message: str, upload_id: Optional[str] = None):
+        super().__init__(message, code="UPLOAD_ERROR")
+        self.upload_id = upload_id
+
+
+class DownloadError(FileHubError):
+    """下载异常"""
+    
+    def __init__(self, message: str, file_id: Optional[str] = None):
+        super().__init__(message, code="DOWNLOAD_ERROR")
+        self.file_id = file_id
+
+
+class ExportError(FileHubError):
+    """导出异常"""
+    
+    def __init__(self, message: str, file_id: Optional[str] = None, format: Optional[str] = None):
+        super().__init__(message, code="EXPORT_ERROR")
+        self.file_id = file_id
+        self.format = format
+
+
+class ValidationError(FileHubError):
+    """验证异常"""
+    
+    def __init__(self, message: str, field: Optional[str] = None):
+        super().__init__(message, code="VALIDATION_ERROR")
+        self.field = field
+
+
+class ConnectionError(FileHubError):
+    """连接异常"""
+    
+    def __init__(self, message: str):
+        super().__init__(message, code="CONNECTION_ERROR")
+
+
+class TimeoutError(FileHubError):
+    """超时异常"""
+    
+    def __init__(self, message: str, timeout: Optional[float] = None):
+        super().__init__(message, code="TIMEOUT_ERROR")
+        self.timeout = timeout 

file_hub_client/py.typed

@@ -0,0 +1 @@
+ 

file_hub_client/rpc/__init__.py

@@ -0,0 +1,10 @@
+"""
+RPC 模块 - 提供 gRPC 客户端基础类
+"""
+from .async_client import AsyncGrpcClient
+from .sync_client import SyncGrpcClient
+
+__all__ = [
+    "AsyncGrpcClient",
+    "SyncGrpcClient",
+]