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

file_hub_client/services/file/async_file_service.py

@@ -0,0 +1,257 @@
+"""
+异步文件服务
+"""
+import asyncio
+
+import grpc
+from typing import Optional, Dict, List, Any
+
+from .base_file_service import BaseFileService
+from ...rpc.async_client import AsyncGrpcClient
+from ...schemas import (
+    File,
+    FileListResponse,
+)
+from ...errors import FileNotFoundError
+
+
+class AsyncFileService(BaseFileService):
+    """异步文件服务"""
+
+    def __init__(self, client: AsyncGrpcClient):
+        """
+        初始化文件服务
+        
+        Args:
+            client: 异步gRPC客户端
+        """
+        self.client = client
+
+    async def generate_share_link(
+            self,
+            file_id: str,
+            *,
+            is_public: bool = True,
+            access_scope: str = "view",
+            expire_seconds: int = 86400,
+            max_access: Optional[int] = None,
+            share_password: Optional[str] = None,
+            **metadata
+    ) -> str:
+        """
+        生成分享链接
+        
+        Args:
+            file_id: 文件ID
+            is_public: 是否公开
+            access_scope: 访问范围
+            expire_seconds: 过期时间（秒）
+            max_access: 最大访问次数
+            share_password: 访问密码
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+            
+        Returns:
+            分享ID
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.ShareLinkRequest(
+            file_id=file_id,
+            is_public=is_public,
+            access_scope=access_scope,
+            expire_seconds=expire_seconds
+        )
+
+        if max_access is not None:
+            request.max_access = max_access
+        if share_password:
+            request.share_password = share_password
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        response = await stub.GenerateShareLink(request, metadata=grpc_metadata)
+
+        return response.file_share_id
+
+    async def visit_file(
+            self,
+            file_share_id: str,
+            access_type: str = "view",
+            access_duration: int = 0,
+            metadata: Optional[Dict[str, Any]] = None,
+            **extra_metadata
+    ) -> None:
+        """
+        访问文件（通过分享链接）
+        
+        Args:
+            file_share_id: 分享ID
+            access_type: 访问类型
+            access_duration: 访问时长
+            metadata: 元数据
+            **extra_metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+        from google.protobuf import struct_pb2
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        # 转换metadata为Struct
+        struct_metadata = struct_pb2.Struct()
+        if metadata:
+            for key, value in metadata.items():
+                struct_metadata[key] = value
+
+        request = file_service_pb2.FileVisitRequest(
+            file_share_id=file_share_id,
+            access_type=access_type,
+            access_duration=access_duration,
+            metadata=struct_metadata
+        )
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**extra_metadata)
+
+        await stub.VisitFile(request, metadata=grpc_metadata)
+
+    async def get_file(self, file_id: str, **metadata) -> File:
+        """
+        获取文件信息
+        
+        Args:
+            file_id: 文件ID
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+            
+        Returns:
+            文件信息
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.GetFileRequest(file_id=file_id)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        try:
+            response = await stub.GetFile(request, metadata=grpc_metadata)
+            return self._convert_file_info(response)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.NOT_FOUND:
+                raise FileNotFoundError(file_id)
+            raise
+
+    async def rename_file(self, file_id: str, new_name: str, **metadata) -> File:
+        """
+        重命名文件
+        
+        Args:
+            file_id: 文件ID
+            new_name: 新文件名
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+            
+        Returns:
+            更新后的文件信息
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.RenameFileRequest(
+            file_id=file_id,
+            new_name=new_name
+        )
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        try:
+            response = await stub.RenameFile(request, metadata=grpc_metadata)
+            return self._convert_file_info(response)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.NOT_FOUND:
+                raise FileNotFoundError(file_id)
+            raise
+
+    async def delete_file(self, file_id: str, **metadata) -> None:
+        """
+        删除文件
+        
+        Args:
+            file_id: 文件ID
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.DeleteFileRequest(file_id=file_id)
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        try:
+            await stub.DeleteFile(request, metadata=grpc_metadata)
+        except grpc.RpcError as e:
+            if e.code() == grpc.StatusCode.NOT_FOUND:
+                raise FileNotFoundError(file_id)
+            raise
+
+    async def list_files(
+            self,
+            folder_id: Optional[str] = None,
+            file_name: Optional[str] = None,
+            file_type: Optional[List[str]] = None,
+            created_by_role: Optional[str] = None,
+            created_by: Optional[str] = None,
+            page_size: int = 20,
+            page: int = 1,
+            **metadata
+    ) -> FileListResponse:
+        """
+        列出文件
+        
+        Args:
+            folder_id: 文件夹ID
+            file_name: 文件名过滤
+            file_type: 文件类型过滤
+            created_by_role: 创建者角色过滤
+            created_by: 创建者过滤
+            page_size: 每页大小
+            page: 页码
+            **metadata: 额外的元数据（如 x-org-id, x-user-id 等）
+            
+        Returns:
+            文件列表响应
+        """
+        from ...rpc.gen import file_service_pb2, file_service_pb2_grpc
+
+        stub = await self.client.get_stub(file_service_pb2_grpc.FileServiceStub)
+
+        request = file_service_pb2.ListFilesRequest(
+            folder_id=folder_id,
+            page_size=page_size,
+            page=page
+        )
+
+        if file_name:
+            request.file_name = file_name
+        if file_type:
+            request.file_type.extend(file_type)
+        if created_by_role:
+            request.created_by_role = created_by_role
+        if created_by:
+            request.created_by = created_by
+
+        # 构建元数据
+        grpc_metadata = self.client.build_metadata(**metadata)
+
+        response = await stub.ListFiles(request, metadata=grpc_metadata)
+
+        files = [self._convert_file_info(f) for f in response.files]
+
+        return FileListResponse(files=files)

file_hub_client/services/file/base_file_service.py

@@ -0,0 +1,103 @@
+import hashlib
+from pathlib import Path
+from typing import Optional, Union, BinaryIO, Tuple, Any
+
+from ...schemas import File, UploadFile
+from ...utils.file_utils import get_file_mime_type
+from ...errors import ValidationError, FileNotFoundError
+
+
+class BaseFileService:
+    """
+    文件服务核心逻辑，提供与上传/下载无关的通用工具方法。
+    """
+
+    def _extract_file_info(
+            self,
+            file: Union[str, Path, BinaryIO, bytes]
+    ) -> Tuple[Optional[str], bytes, int, str, str, str]:
+        """
+        提取文件信息并返回统一的 bytes 内容与 SHA256 哈希
+
+        Returns:
+            (文件名, 内容（bytes）, 文件大小, MIME类型, 文件扩展名, 文件hash)
+        """
+
+        def get_file_type_and_mime(file_path: Path) -> Tuple[str, str]:
+            return (
+                file_path.suffix.lstrip('.').lower() if file_path.suffix else '',
+                get_file_mime_type(file_path)
+            )
+
+        def calculate_sha256_and_bytes(f: BinaryIO) -> Tuple[bytes, str]:
+            sha256 = hashlib.sha256()
+            content = bytearray()
+            while chunk := f.read(4 * 1024 * 1024):
+                content.extend(chunk)
+                sha256.update(chunk)
+            f.seek(0)  # 复位以防止外部再用
+            return bytes(content), sha256.hexdigest()
+
+        # Case 1: 文件路径
+        if isinstance(file, (str, Path)):
+            file_path = Path(file)
+            if not file_path.exists():
+                raise FileNotFoundError(f"文件不存在: {file_path}")
+            file_name = file_path.name
+            file_type, mime_type = get_file_type_and_mime(file_path)
+            with file_path.open("rb") as f:
+                content, file_hash = calculate_sha256_and_bytes(f)
+            file_size = len(content)
+            return file_name, content, file_size, mime_type, file_type, file_hash
+
+        # Case 2: 原始字节流
+        elif isinstance(file, bytes):
+            sha256 = hashlib.sha256(file).hexdigest()
+            return None, file, len(file), "application/octet-stream", '', sha256
+
+        # Case 3: 可读文件对象
+        elif hasattr(file, 'read'):
+            file_name = getattr(file, 'name', None)
+            file_type = Path(file_name).suffix.lstrip('.').lower() if file_name else ''
+            mime_type = get_file_mime_type(Path(file_name)) if file_name else "application/octet-stream"
+
+            if hasattr(file, 'seek'):
+                file.seek(0)
+            content, file_hash = calculate_sha256_and_bytes(file)
+            file_size = len(content)
+            return Path(file_name).name if file_name else None, content, file_size, mime_type, file_type, file_hash
+
+        else:
+            raise ValidationError(f"不支持的文件类型: {type(file)}")
+
+    def _convert_file_info(self, proto_file: Any) -> File:
+        """转换Proto文件信息为模型"""
+        from ...utils.converter import timestamp_to_datetime
+
+        return File(
+            id=proto_file.id,
+            folder_id=proto_file.folder_id,
+            file_name=proto_file.file_name,
+            file_type=proto_file.file_type,
+            created_at=timestamp_to_datetime(proto_file.created_at),
+            updated_at=timestamp_to_datetime(proto_file.updated_at)
+        )
+
+    def _convert_upload_file_info(self, proto_upload_file: Any) -> UploadFile:
+        """转换Proto文件信息为模型"""
+        from ...utils.converter import timestamp_to_datetime
+
+        return UploadFile(
+            id=proto_upload_file.id,
+            folder_id=proto_upload_file.folder_id,
+            storage_type=proto_upload_file.storage_type,
+            stored_name=proto_upload_file.stored_name,
+            stored_path=proto_upload_file.stored_path,
+            file_id=proto_upload_file.file_id,
+            file_name=proto_upload_file.file_name,
+            file_size=proto_upload_file.file_size,
+            file_ext=proto_upload_file.file_ext,
+            mime_type=proto_upload_file.mime_type,
+            created_at=timestamp_to_datetime(proto_upload_file.created_at),
+            updated_at=timestamp_to_datetime(proto_upload_file.updated_at)
+        )