tamar-file-hub-client 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

{tamar_file_hub_client-0.1.3.dist-info → tamar_file_hub_client-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tamar-file-hub-client
-Version: 0.1.3
+Version: 0.1.5
 Summary: A Python SDK for gRPC-based file management system
 Home-page: https://github.com/Tamar-Edge-AI/file-hub-client
 Author: Oscar Ou
@@ -60,6 +60,7 @@ Dynamic: summary
 - 🔁 **自动重试**：连接失败时自动重试，提高可靠性
 - 📝 **类型注解**：完整的类型提示支持
 - 🧩 **模块化设计**：清晰的代码结构，易于扩展
+- 🎨 **图片和视频压缩**：支持多种规格的媒体文件压缩变体生成和管理
 - 🏗️ **分层服务架构**：文件服务分为传统文件（blob）和自定义类型（结构化数据），每种类型独立服务，语义清晰
 - 🔧 **环境变量配置**：支持通过环境变量配置所有参数
 - 👤 **用户上下文管理**：支持区分资源所有权（ownership）和操作者（operator）
@@ -209,6 +210,8 @@ File Hub Client 采用分层服务架构，将文件服务按类型和语义进
         - 智能选择上传模式（根据文件大小）
         - 生成上传/下载 URL
         - 支持临时文件上传
+        - **媒体文件压缩**：支持图片和视频的多规格压缩变体生成
+        - **压缩管理**：获取压缩状态、管理变体、触发重新压缩
         - 适用类型：PDF、图片、视频、音频、压缩包等
     - **file_service**: 处理文件元数据操作（所有类型通用）
         - 获取、重命名、删除文件
@@ -243,6 +246,11 @@ File Hub Client 采用分层服务架构，将文件服务按类型和语义进
     - `UploadUrlResponse`: URL上传响应
     - `ShareLinkRequest`: 分享链接请求
     - `FileListResponse`: 文件列表响应
+    - `CompressedVariant`: 压缩变体信息
+    - `CompressionStatusResponse`: 压缩状态响应
+    - `GetVariantsResponse`: 获取变体响应
+    - `RecompressionResponse`: 重新压缩响应
+    - `VariantDownloadUrlResponse`: 变体下载URL响应
 
 - **folder.py**: 文件夹相关的数据模型
     - `FolderInfo`: 文件夹信息
@@ -735,7 +743,14 @@ async with AsyncTamarFileHubClient() as client:
         if url_info.error:
             print(f"文件 {url_info.file_id} 生成URL失败: {url_info.error}")
         else:
-            print(f"文件 {url_info.file_id} 的下载URL: {url_info.url}")
+            print(f"文件 {url_info.file_id}:")
+            print(f"  下载URL: {url_info.url}")
+            print(f"  MIME类型: {url_info.mime_type}")
+            # 根据MIME类型处理文件
+            if url_info.mime_type.startswith('image/'):
+                print(f"  这是一个图片文件")
+            elif url_info.mime_type == 'application/pdf':
+                print(f"  这是一个PDF文件")
 ```
 
 同步客户端示例：
@@ -752,6 +767,12 @@ with TamarFileHubClient() as client:
     )
 ```
 
+**注意**：`batch_generate_download_url` 方法返回一个 `BatchDownloadUrlResponse` 对象，其中 `download_urls` 字段包含 `DownloadUrlInfo` 对象列表，每个对象包含：
+- `file_id`: 文件ID
+- `url`: 下载URL（如果成功生成）
+- `mime_type`: 文件的MIME类型，便于正确处理文件内容
+- `error`: 错误信息（如果生成失败）
+
 ##### 获取GCS URL
 
 对于需要直接访问Google Cloud Storage的场景，可以获取文件的GCS URL和MIME类型信息：
@@ -837,6 +858,149 @@ with TamarFileHubClient() as client:
    - 错误信息通过 `error` 字段返回
    - 建议在批量操作时做好错误处理和重试逻辑
 
+### 媒体文件压缩服务
+
+File Hub Client 支持图片和视频文件的自动压缩处理，提供多种规格的压缩变体以满足不同使用场景的需求。
+
+#### 获取文件压缩状态
+
+```python
+from file_hub_client import AsyncTamarFileHubClient
+
+async with AsyncTamarFileHubClient() as client:
+    client.set_user_context(org_id="123", user_id="456")
+    
+    # 获取文件压缩状态
+    status = await client.blobs.get_compression_status(file_id="file-001")
+    
+    print(f"压缩状态: {status.status}")  # pending, processing, completed, failed
+    if status.error_message:
+        print(f"错误信息: {status.error_message}")
+    
+    # 查看可用的压缩变体
+    for variant in status.variants:
+        print(f"变体: {variant.variant_name}")
+        print(f"  类型: {variant.variant_type}")  # image, video, thumbnail
+        print(f"  尺寸: {variant.width}x{variant.height}")
+        print(f"  大小: {variant.file_size} bytes")
+        print(f"  格式: {variant.format}")
+        print(f"  压缩比: {variant.compression_ratio:.2f}")
+```
+
+#### 获取压缩变体列表
+
+```python
+# 获取所有压缩变体
+variants = await client.blobs.get_compressed_variants(file_id="file-001")
+
+# 按类型过滤变体
+image_variants = await client.blobs.get_compressed_variants(
+    file_id="file-001",
+    variant_type="image"  # image, video, thumbnail
+)
+
+# 处理变体信息
+for variant in variants.variants:
+    print(f"变体名称: {variant.variant_name}")  # large, medium, small, thumbnail
+    print(f"媒体类型: {variant.media_type}")
+    print(f"文件格式: {variant.format}")
+    if variant.quality:
+        print(f"质量: {variant.quality}")
+    if variant.duration:
+        print(f"时长: {variant.duration}秒")
+    if variant.bitrate:
+        print(f"比特率: {variant.bitrate}")
+```
+
+#### 下载压缩变体
+
+```python
+# 生成压缩变体的下载URL
+variant_url = await client.blobs.generate_variant_download_url(
+    file_id="file-001",
+    variant_name="medium",  # large, medium, small, thumbnail
+    expire_seconds=3600,    # URL有效期
+    is_cdn=True            # 是否使用CDN
+)
+
+print(f"下载URL: {variant_url.url}")
+if variant_url.error:
+    print(f"生成URL错误: {variant_url.error}")
+
+# 查看变体详细信息
+if variant_url.variant_info:
+    info = variant_url.variant_info
+    print(f"变体信息:")
+    print(f"  尺寸: {info.width}x{info.height}")
+    print(f"  格式: {info.format}")
+    print(f"  文件大小: {info.file_size} bytes")
+```
+
+#### 触发重新压缩
+
+```python
+# 触发文件重新压缩（当需要更新压缩设置时）
+recompression = await client.blobs.trigger_recompression(
+    file_id="file-001",
+    force_reprocess=False  # 是否强制重新处理
+)
+
+print(f"任务ID: {recompression.task_id}")
+print(f"状态: {recompression.status}")
+
+# 监控压缩进度
+import asyncio
+while True:
+    status = await client.blobs.get_compression_status(file_id="file-001")
+    print(f"当前状态: {status.status}")
+    
+    if status.status in ["completed", "failed"]:
+        break
+    
+    await asyncio.sleep(5)  # 等待5秒后再次检查
+```
+
+#### 同步客户端压缩服务
+
+```python
+from file_hub_client import TamarFileHubClient
+
+with TamarFileHubClient() as client:
+    client.set_user_context(org_id="123", user_id="456")
+    
+    # 所有压缩服务方法都有对应的同步版本
+    status = client.blobs.get_compression_status(file_id="file-001")
+    variants = client.blobs.get_compressed_variants(file_id="file-001")
+    recompression = client.blobs.trigger_recompression(file_id="file-001")
+    variant_url = client.blobs.generate_variant_download_url(
+        file_id="file-001",
+        variant_name="thumbnail"
+    )
+```
+
+#### 压缩服务使用场景
+
+1. **多设备适配**：
+   - `large` - 高分辨率显示设备
+   - `medium` - 标准桌面和平板
+   - `small` - 手机端显示
+   - `thumbnail` - 缩略图预览
+
+2. **带宽优化**：
+   - 根据网络状况选择合适的变体
+   - 移动端使用压缩变体节省流量
+   - 预览场景使用缩略图快速加载
+
+3. **存储优化**：
+   - 自动生成多种规格，无需手动处理
+   - 智能压缩算法平衡质量和大小
+   - 支持视频和图片的不同压缩策略
+
+4. **性能优化**：
+   - 异步压缩处理，不阻塞上传流程
+   - 支持重新压缩以应用新的压缩设置
+   - 批量状态查询减少网络请求
+
 ### 文件管理操作
 
 File Hub Client 提供了完整的文件管理功能，通过 `files` 服务访问：
@@ -2174,9 +2338,21 @@ MIT License
 
 ## 更新日志
 
+### v0.0.6 (2025-08)
+- 新增媒体文件压缩服务功能
+- 支持获取文件压缩状态 (get_compression_status)
+- 支持获取压缩变体列表 (get_compressed_variants)
+- 支持触发文件重新压缩 (trigger_recompression)
+- 支持生成变体下载URL (generate_variant_download_url)
+- 添加压缩相关数据模型 (CompressedVariant 等)
+- 在所有文件服务类中实现压缩功能支持
+- 更新文档包含压缩服务使用示例
+
 ### v0.0.5 (2025-01)
 - 新增批量下载URL生成接口 (batch_generate_download_url)
 - 新增GCS URL获取接口 (get_gcs_url, batch_get_gcs_url)
+- **重要更新**: 批量下载URL接口 (BatchGenerateDownloadUrl) 现在返回MIME类型信息
+- **重要更新**: DownloadUrlInfo 结构新增 mime_type 字段，便于文件类型识别
 - GCS URL接口返回MIME类型信息，便于文件类型识别
 - 新增 keep_original_filename 参数支持保留原始文件名
 - 更新相关文档和测试用例

{tamar_file_hub_client-0.1.3.dist-info → tamar_file_hub_client-0.1.5.dist-info}/RECORD

@@ -1,5 +1,5 @@
 file_hub_client/__init__.py,sha256=5pOOgw8YLzsQ49o81j5xCFtiH7VHFObNlbAYZwsU7ts,2918
-file_hub_client/client.py,sha256=kOis7hw0WAi-YAmEM_1PEzp0hsOD9JSxLbJi2cvTd_o,17338
+file_hub_client/client.py,sha256=n1HYk08B6jH_2k8pewqt_fThDZGLPJsq5DWxnQG6WSA,18120
 file_hub_client/py.typed,sha256=Nqnn8clbgv-5l0PgxcTOldg8mkMKrFn4TvPL-rYUUGg,1
 file_hub_client/enums/__init__.py,sha256=e3Io6-IC9Nezbdc8H4TzuWqiDw0T1fsdbSi-fsgSQM4,203
 file_hub_client/enums/export_format.py,sha256=C9P0q8v5eTszUBqKBmERxoA9UrTgLuX3a_bZeUxkdlQ,296
@@ -8,32 +8,32 @@ file_hub_client/enums/upload_mode.py,sha256=_7caGZks1AI1RBGlZliruQIFGfAtwh9NWL8X
 file_hub_client/errors/__init__.py,sha256=_Ud6yaBPuFB-luxeFIVhbG_0xIy05vONUkMuG8pX2xo,561
 file_hub_client/errors/exceptions.py,sha256=0RDkAv4t2GeVefm1H5eaXGxd6Od-drXzPIVJZ-8sRGc,2648
 file_hub_client/rpc/__init__.py,sha256=dhRt0D_US3j2Dam47nhd23RowVZ-nvVowhPsNFf4GZo,204
-file_hub_client/rpc/async_client.py,sha256=vMi4Aqc_Ajg2sdOgXHiLjP_4FkPtg5tDpSDPK6hg-cM,14038
+file_hub_client/rpc/async_client.py,sha256=qWrqRA3UhsKgCjM5G-jncnN2Xgu8-XqMFI2i5nBRSSs,15348
 file_hub_client/rpc/generate_grpc.py,sha256=opzstxWdW7vqR9OxrgUCSUkZe8IqgcOdruqWGIzCneI,2158
-file_hub_client/rpc/interceptors.py,sha256=UeQ8u-olMiYwScXJrlzqPS-odGomH-h3xJqOwPznRUo,22071
-file_hub_client/rpc/sync_client.py,sha256=ZWBmP-TU8eeAfl2lV8sLu9nsxo_aOPAVmt9ww_T8Hwg,14054
+file_hub_client/rpc/interceptors.py,sha256=cFLKziOZMO5oKZfElLXctLKo08BJCFHFiuCrvtYSGaw,21627
+file_hub_client/rpc/sync_client.py,sha256=iaow1Lpi0moq9kwlUVNP0p4ucgHKCP8y5cvmP32dkQU,15364
 file_hub_client/rpc/gen/__init__.py,sha256=NJLqr9ezUXeOyy1J0sMPn3Kl_8IyGw7GAzzzewO3MIw,45
-file_hub_client/rpc/gen/file_service_pb2.py,sha256=KphiN6KuksPPDP-PKuTo1COKTAO0M1XsCm0as2BC2Qc,11211
-file_hub_client/rpc/gen/file_service_pb2_grpc.py,sha256=F7u-n6doSz1HxmaYAL0y_nNB1NVR8CRlZVKAMe63P4A,26083
+file_hub_client/rpc/gen/file_service_pb2.py,sha256=WQzve9AfDRJy0xJ-hIUX3A0xyL5h9fpyRVemLkP4SPA,14807
+file_hub_client/rpc/gen/file_service_pb2_grpc.py,sha256=a5tjnCqO_ZVBBQK5COUgZ_Eb7hlv81yseg-8goOROls,33372
 file_hub_client/rpc/gen/folder_service_pb2.py,sha256=OPNYHThmL1k2KH1ll2L_Gj76oWBWqcymXKHu8mk1Zvk,4126
 file_hub_client/rpc/gen/folder_service_pb2_grpc.py,sha256=pOHFsVThdAu5DAKd8QK3_zQvUmFgGlh4KBqIYnYDZ_U,10411
 file_hub_client/rpc/gen/taple_service_pb2.py,sha256=8BJCFRFJ_khl_Uaw-5jWCabljWJo6zaqOYWe1368xEw,48254
 file_hub_client/rpc/gen/taple_service_pb2_grpc.py,sha256=DCL-45PlEZ0guLz1u2fFH_sDIT_awuSvp9Ak6fa2GO8,64773
-file_hub_client/rpc/protos/file_service.proto,sha256=fekeTjDP_qaWL8EPVblH2EV_7xnWVTZgoIX7sAUNZ8Y,4995
+file_hub_client/rpc/protos/file_service.proto,sha256=KuayH0TNEJENI77LG6VUyUHPpFZuKJ1I5ljvoJyRIHo,6924
 file_hub_client/rpc/protos/folder_service.proto,sha256=cgIbJT2slXMMRGrtrzN3kjae9-4CB1zXCmceiUgE6fI,1542
 file_hub_client/rpc/protos/taple_service.proto,sha256=0mwhyBwD3yvFhMiiSA6J3Ni6pyHc369iD4oDXXl7DIU,29765
-file_hub_client/schemas/__init__.py,sha256=9BvyqWBkeEav47vUBZ6eDyCt_iKATCOwakcrmOTdVWA,2396
-file_hub_client/schemas/context.py,sha256=bs-KXGBBo_9i1KbvozY8KjYzV5ZtMbjqpPW_ssN7qMs,5516
-file_hub_client/schemas/file.py,sha256=s4_gYriOn_UP9gcDRqB2YNvNN-FqEZEbfJCOVE5JUTQ,4899
+file_hub_client/schemas/__init__.py,sha256=oaXrODfBI-Oe-MyAyL6bKDZ1mPRC_IyMmxzGic4BbEU,2692
+file_hub_client/schemas/context.py,sha256=E4TKqUJBaq9s31cGIRsztS-mQBUYAKyyLK8knVgWNb8,5805
+file_hub_client/schemas/file.py,sha256=KaF7XaZLkIlomEPaC1G9Qsbzen6VfChwVrXFRydWowA,6709
 file_hub_client/schemas/folder.py,sha256=D7UFsLCou-7CCXCQvuRObaBQEGmETsm1cgGOG1ceSrk,1026
 file_hub_client/schemas/taple.py,sha256=LYsECsDbcioPXcvjRBcCEbh083iEB-eFCapJrGMJ8w0,17790
 file_hub_client/services/__init__.py,sha256=yh5mir0dKB_LtJMk2hTpQI9WSlguaxtVD2KomMnzxdM,514
 file_hub_client/services/file/__init__.py,sha256=aJygo_AzYk5NN-ezp-a9YlugJ82wVIP9e5e54fl0UsI,342
-file_hub_client/services/file/async_blob_service.py,sha256=qOUFvkNyjDsFHNpLpjqIB0z5xF2KkFlgpa3HblEPXYg,25962
-file_hub_client/services/file/async_file_service.py,sha256=wJuoy-3CiIow5Xef_4JNJRKEOoMTKfs9nxqbkaYI4Ig,9110
+file_hub_client/services/file/async_blob_service.py,sha256=AmiPstmjW3L42Qfsx_5Pp4zM8WCTCRqV-oTHlecTDb8,35428
+file_hub_client/services/file/async_file_service.py,sha256=lFMfnHKsbTIOpMAdFvER4B2JqVGz9SNzgxlmA1kY3Js,17197
 file_hub_client/services/file/base_file_service.py,sha256=wTxplrTk9klfwIHOPfTL0TQd6gX4nEmkYtIhpiZ3GVo,4791
-file_hub_client/services/file/sync_blob_service.py,sha256=IcbXzyoZHNHzE3aDZ69M5AOqJk4-mR0w0TKyohjEGHQ,25689
-file_hub_client/services/file/sync_file_service.py,sha256=fMTq91dXwZzuMsPTZ1whaQBxzpyHfSP-A4W15pWSNfs,8964
+file_hub_client/services/file/sync_blob_service.py,sha256=qkVB9itCzpyCSDP-2uZ6TBI-ugDhhrWni2n3UR39q8M,35075
+file_hub_client/services/file/sync_file_service.py,sha256=3VEgFiWYfoWD4iZObJ8uylUtNmK08snXWUaVEosUPDo,16979
 file_hub_client/services/folder/__init__.py,sha256=vGbMOlNiEBdnWZB1xE74RJtoroI28hKHCWfQV1GqKQc,210
 file_hub_client/services/folder/async_folder_service.py,sha256=uFEmtW8EXYvaKYT2JCitWbdTGR1EtHlx_eBN5P3JUZg,7293
 file_hub_client/services/folder/sync_folder_service.py,sha256=T00k1nD0txjOFQXxeIbF_ZOkNUhsBF45sDxyaDk8rf8,7167
@@ -42,16 +42,17 @@ file_hub_client/services/taple/async_taple_service.py,sha256=XZqMBN69FSJ8-n0nyIf
 file_hub_client/services/taple/base_taple_service.py,sha256=m_RZjvlXD8CzsB4gtZWDKiL7TNYYtRuSeY4yrFDnGIs,15842
 file_hub_client/services/taple/idempotent_taple_mixin.py,sha256=lZeMF59dU-KVnc2p7epGrclidCv0nYg8TP_qVUezJ48,4295
 file_hub_client/services/taple/sync_taple_service.py,sha256=LIfpJjZjUPpee5zidrmiRD-tTXPouSlU4RpScy5kNZY,87392
-file_hub_client/utils/__init__.py,sha256=0WS1R9VEPEqIN6_ksHEbO6Eu0G1Ps6oNTuOtoDMdDMM,1832
+file_hub_client/utils/__init__.py,sha256=Chz4dEBbI2LyatrLLorWBx_kkNsg4LeFa-veUczlrPQ,2152
 file_hub_client/utils/converter.py,sha256=TX69Bqk-PwNdv2hYQ07_tW6HQnQycHcJkGeRnskeF3A,3734
 file_hub_client/utils/download_helper.py,sha256=Mc8TQSWjHxIglJMkKlGy9r3LZe8e_Mwe6D3sfn6IOnY,13338
-file_hub_client/utils/file_utils.py,sha256=Ly8R5KJS_3lbgJxNZkc4sSBKuGgn-fYeh17GEY4pyy8,4359
+file_hub_client/utils/file_utils.py,sha256=x4Oky_ZpmZ3TuLB7SjmCuzYiSqOyCuAMLe_2A6OjdFg,5537
 file_hub_client/utils/idempotency.py,sha256=zuXDlpAc9VTkTsarlnkO0VuJ77yON6j1TX0GvL9Xd9k,6029
-file_hub_client/utils/logging.py,sha256=IxcvWkA0G9s9BMiXIeFAdJX5G-Lc5-JFlS2yxOX1Swo,11741
+file_hub_client/utils/ip_detector.py,sha256=S1pHn5CSdLLOrIeIxU_qI7zA7bRW6pUOXVIbRuGHunc,6184
+file_hub_client/utils/logging.py,sha256=CZi-YUxQS5ss79pTdqMO_QFZCU3PxGEB6LKoJu21a0Q,12457
 file_hub_client/utils/retry.py,sha256=A2MBdJCEY-Ks0guq8dd5wXX22sD27N30Qy3nQIW1B_s,18019
 file_hub_client/utils/smart_retry.py,sha256=RjBhyG6SNDfMXxNxKU_qayWDD6Ihp7ow6_BPjhgflM0,16465
 file_hub_client/utils/upload_helper.py,sha256=gEtn9OXVJiGUpVev_fqrDnRQ6AFiiP9goLzFrVpqXmU,22569
-tamar_file_hub_client-0.1.3.dist-info/METADATA,sha256=t8Ohoetv3OYCeon2R4G8WivDCQloG_kXLCTntdszx2o,71188
-tamar_file_hub_client-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-tamar_file_hub_client-0.1.3.dist-info/top_level.txt,sha256=9wcR7hyAJQdJg_kuH6WR3nmpJ8O-j8aJNK8f_kcFy6U,16
-tamar_file_hub_client-0.1.3.dist-info/RECORD,,
+tamar_file_hub_client-0.1.5.dist-info/METADATA,sha256=BEVTxshG7pnF1fzW7aBLt-cm-7szvrjI302TXKF9xkA,77692
+tamar_file_hub_client-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tamar_file_hub_client-0.1.5.dist-info/top_level.txt,sha256=9wcR7hyAJQdJg_kuH6WR3nmpJ8O-j8aJNK8f_kcFy6U,16
+tamar_file_hub_client-0.1.5.dist-info/RECORD,,