multibucket 0.1.2__cp313-cp313-win_amd64.whl

multibucket/__init__.py

@@ -0,0 +1,4 @@
+from multibucket.ucloud import UCloudFileClient
+
+__version__ = '0.1.2'
+__all__ = ["UCloudFileClient"]

multibucket/ucloud.pyi

@@ -0,0 +1,268 @@
+import requests
+from _typeshed import Incomplete
+from typing import BinaryIO, Callable
+
+class UCloudFileClient:
+    """
+    UCloud UFile 文件管理客户端
+
+    参考文档:
+    - 签名算法: https://docs.ucloud.cn/ufile/api/authorization
+    - 上传文件: https://docs.ucloud.cn/api/ufile-api/put_file
+    - 删除文件: https://docs.ucloud.cn/api/ufile-api/delete_file
+    - 查询文件: https://docs.ucloud.cn/api/ufile-api/head_file
+    - 初始化分片: https://docs.ucloud.cn/api/ufile-api/initiate_multipart_upload
+    - 上传分片: https://docs.ucloud.cn/api/ufile-api/upload_part
+    - 完成分片: https://docs.ucloud.cn/api/ufile-api/finish_multipart_upload
+    - 放弃分片: https://docs.ucloud.cn/api/ufile-api/abort_multipart_upload
+    """
+    public_key: Incomplete
+    private_key: Incomplete
+    bucket: Incomplete
+    region: Incomplete
+    internal: Incomplete
+    external_url: Incomplete
+    intranet_url: Incomplete
+    host: Incomplete
+    domain_url: Incomplete
+    def __init__(self, public_key: str, private_key: str, bucket: str, region: str = 'cn-bj', internal: bool = False, domain_url: str | None = None) -> None:
+        """
+        :param public_key:  UCloud 公钥
+        :param private_key: UCloud 私钥
+        :param bucket:      存储空间名称
+        :param region:      地域标识，如 cn-bj、cn-sh2、cn-wlcb 等
+        :param internal:    是否使用内网访问，默认 False（外网）
+                            内网域名格式: {bucket}.internal-{region}.ufileos.com
+                            外网域名格式: {bucket}.{region}.ufileos.com
+        :param domain_url:  自定义域名 URL，如 CDN 域名。若不指定则使用默认的 host
+        """
+    def key_sort(self, params: dict) -> dict:
+        """
+        对字典按 key 排序
+        """
+    def canonicalized_resource(self, key: str, query_params: dict[str, str] | None = None) -> str:
+        """
+        构造规范化资源路径
+
+        :param key:          文件 key
+        :param query_params: 查询参数字典，会拼接到资源路径后用于签名
+        """
+    def canonicalized_ucloud_headers(self, headers: dict[str, str]) -> str:
+        """
+        只取 X-UCloud 开头的 header
+        """
+    def sign(self, string_to_sign: str) -> str:
+        """
+        HMAC-SHA1 + Base64
+        """
+    def make_authorization(self, key: str, expires: str, method: str = 'GET', content_md5: str = '', content_type: str = '', headers: dict[str, str] | None = None, query_params: dict[str, str] | None = None) -> str:
+        '''
+        生成签名
+
+        StringToSign = HTTP-Verb + "
+" +
+            Content-MD5 + "
+" +
+            Content-Type + "
+" +
+            Date + "
+" +
+            CanonicalizedUCloudHeaders +
+            CanonicalizedResource
+
+        :param key:            文件 key
+        :param expires:        时间戳（秒）
+        :param method:         HTTP 方法
+        :param content_md5:    Content-MD5 值
+        :param content_type:   Content-Type 值
+        :param headers:        请求头字典
+        :param query_params:   查询参数字典，参与签名
+        :return:               Base64 编码的签名字符串
+        '''
+    def get_path_url(self, key: str) -> str:
+        """
+        获取文件的完整访问 URL（使用自定义域名或默认域名）
+
+        :param key: 文件在 UFile 中的 key
+        :return:    完整的文件访问 URL
+        """
+    def get_shared_url(self, key: str, expire_time: int = 1200) -> str:
+        """
+        生成带签名的分享 URL（查询字符串身份验证）
+
+        适用于分享私有空间文件给第三方访问，无需代理请求。
+        默认使用外网地址，除非显式指定了自定义域名。
+        参考文档: https://docs.ucloud.cn/ufile/api/authorization?id=查询字符串请求身份验证替代项
+
+        :param key:          文件在 UFile 中的 key
+        :param expire_time:  过期时间（秒），默认 1200 秒（20 分钟）
+        :return:             带签名的完整访问 URL
+        """
+    def put(self, key: str, data: bytes | str | BinaryIO, content_type: str | None = None, content_md5: str | None = None, headers: dict[str, str] | None = None, timeout: float | tuple | None = None) -> requests.Response:
+        """
+        上传文件 (PutFile)
+
+        PUT /<object_name>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param key:          文件在 UFile 中的 key（object_name）
+        :param data:         文件内容（bytes / str / 文件对象）
+        :param content_type: MIME 类型，如 image/jpg、application/octet-stream
+        :param content_md5:  文件内容的 MD5 摘要，用于完整性校验
+        :param headers:      额外的请求头（如 X-Ufile-Storage-Class、X-Ufile-Meta-* 等）
+        :param timeout:      超时时间（秒），可以是 float 或 (connect_timeout, read_timeout) 元组
+        :return:             requests.Response（成功返回 200，无 body）
+        """
+    def put_with_retry(self, key: str, data: bytes | str | BinaryIO, content_type: str | None = None, content_md5: str | None = None, headers: dict[str, str] | None = None, timeout: float | tuple | None = None, retries: int = 3) -> bool:
+        """
+        带重试机制的上传文件
+
+        通过 put 方法上传，状态码为 200 表示上传成功。
+        如果上传失败会自动重试，直到达到指定重试次数。
+
+        注意: 如果 data 是文件对象，会自动读取到内存以支持重试。
+              对于大文件，建议直接使用 put 方法或分片上传。
+
+        :param key:          文件在 UFile 中的 key（object_name）
+        :param data:         文件内容（bytes / str / 文件对象）
+        :param content_type: MIME 类型，如 image/jpg、application/octet-stream
+        :param content_md5:  文件内容的 MD5 摘要，用于完整性校验
+        :param headers:      额外的请求头（如 X-Ufile-Storage-Class、X-Ufile-Meta-* 等）
+        :param timeout:      超时时间（秒），可以是 float 或 (connect_timeout, read_timeout) 元组
+        :param retries:      最大重试次数，默认 3 次
+        :return:             True 表示上传成功，False 表示上传失败
+        """
+    def get(self, key: str, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        下载文件 (GetFile)
+
+        GET /<object_name>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param key:     文件在 UFile 中的 key
+        :param headers: 额外的请求头
+        :return:        requests.Response（response.content 为文件内容）
+        """
+    def head(self, key: str, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        查询文件基本信息 (HeadFile)
+
+        HEAD /<object_name>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        响应头包含:
+        - Content-Type:       文件类型
+        - Content-Length:     文件长度
+        - ETag:               文件在 US3 的哈希值
+        - Last-Modified:      最后修改日期
+        - X-Ufile-Meta-*:     用户自定义元数据
+        - X-Ufile-Storage-Class: 存储类型
+
+        :param key:     文件在 UFile 中的 key
+        :param headers: 额外的请求头
+        :return:        requests.Response（无 body，信息在 response.headers 中）
+        """
+    def exists(self, key: str) -> bool:
+        """
+        判断文件是否存在
+
+        :param key: 文件在 UFile 中的 key
+        :return:    True 表示文件存在，False 表示不存在
+        """
+    def delete(self, key: str, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        删除文件 (DeleteFile)
+
+        DELETE /<object_name>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param key:     文件在 UFile 中的 key
+        :param headers: 额外的请求头
+        :return:        requests.Response（成功返回 204 No Content）
+        """
+    def list(self, prefix: str = '', marker: str = '', limit: int = 20, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        列出文件 (GetFileList)
+
+        GET /?prefix=<prefix>&marker=<marker>&limit=<limit>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param prefix:  文件名前缀过滤
+        :param marker:  分页标记，首次传空，后续用返回值中的 NextMarker
+        :param limit:   每次返回最大条数，默认 20
+        :param headers: 额外的请求头
+        :return:        requests.Response（JSON 格式，包含 DataSet / NextMarker / TotalCount）
+        """
+    def initiate_multipart_upload(self, key: str, content_type: str | None = None, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        初始化分片上传 (InitiateMultipartUpload)
+
+        POST /<object_name>?uploads
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param key:          文件在 UFile 中的 key
+        :param content_type: MIME 类型
+        :param headers:      额外的请求头（如 X-Ufile-Storage-Class、X-Ufile-Meta-* 等）
+        :return:             requests.Response（JSON 包含 UploadId / BlkSize / Bucket / Key）
+        """
+    def upload_part(self, key: str, upload_id: str, part_number: int, data: bytes, content_type: str = 'application/octet-stream', headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        上传分片 (UploadPart)
+
+        PUT /<object_name>?uploadId=<upload_id>&partNumber=<part_number>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        :param key:          文件在 UFile 中的 key
+        :param upload_id:    初始化分片返回的 UploadId
+        :param part_number:  分片序号（从 0 开始）
+        :param data:         分片数据（bytes）
+        :param content_type: MIME 类型，默认 application/octet-stream
+        :param headers:      额外的请求头
+        :return:             requests.Response（JSON 包含 PartNumber，响应头包含 ETag）
+        """
+    def finish_multipart_upload(self, key: str, upload_id: str, etags: list[str], new_object: str | None = None, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        完成分片上传 (FinishMultipartUpload)
+
+        POST /<object_name>?uploadId=<upload_id>[&newObject=<new_object>]
+        Host: <bucket_name>.<region>.ufileos.com
+
+        请求 body 为所有分片 ETag 用逗号拼接的字符串
+
+        :param key:         文件在 UFile 中的 key
+        :param upload_id:   初始化分片返回的 UploadId
+        :param etags:       各分片 ETag 列表（按 partNumber 顺序）
+        :param new_object:  可选，最终文件名，若不指定则使用原 key
+        :param headers:     额外的请求头
+        :return:            requests.Response（JSON 包含 Bucket / Key / FileSize）
+        """
+    def abort_multipart_upload(self, key: str, upload_id: str, headers: dict[str, str] | None = None) -> requests.Response:
+        """
+        放弃分片上传 (AbortMultipartUpload)
+
+        DELETE /<object_name>?uploadId=<upload_id>
+        Host: <bucket_name>.<region>.ufileos.com
+
+        放弃后不能再使用该 upload_id，已上传的分片数据也会被删除
+
+        :param key:       文件在 UFile 中的 key
+        :param upload_id: 初始化分片返回的 UploadId
+        :param headers:   额外的请求头
+        :return:          requests.Response
+        """
+    def multipart_upload(self, key: str, file_path: str, content_type: str | None = None, part_size: int | None = None, headers: dict[str, str] | None = None, callback: Callable[[int, int, int, int], None] | None = None) -> dict:
+        """
+        分片上传高级封装：自动分片、上传、完成
+
+        流程: 初始化分片 -> 循环上传分片 -> 完成分片
+        如果中途失败会自动调用 abort_multipart_upload 放弃上传
+
+        :param key:          文件在 UFile 中的 key
+        :param file_path:    本地文件路径
+        :param content_type: MIME 类型，默认 application/octet-stream
+        :param part_size:    分片大小（字节），默认 4MB（4 * 1024 * 1024）
+        :param headers:      额外的请求头
+        :param callback:     上传进度回调 callback(part_number, total_parts, uploaded_bytes, total_bytes)
+        :return:             dict，包含 upload_id / etags / result
+        :raises:             Exception 上传失败时抛出异常
+        """

multibucket-0.1.2.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: multibucket
+Version: 0.1.2
+Summary: 多对象存储桶 SDK, 支持 UCloud UFile 等
+Home-page: 
+Author: zhenzi0322
+Author-email: zhenzi0322 <82131529@qq.com>
+License: MIT
+Requires-Python: >=3.8
+description-content-type: text/markdown
+Description:
+ # Multibucket
+ 
+ 多对象存储桶 SDK，支持 UCloud UFile 等云存储服务。
+ 
+ ## 运行条件
+ 
+ - Python >= 3.8
+ - requests
+ 
+ ## 安装
+ 
+ ```bash
+ pip install multibucket
+ ```
+ 
+ ## 快速开始
+ 
+ ```python
+ from multibucket import UCloudFileClient
+ 
+ # 初始化客户端
+ ufile = UCloudFileClient(
+     public_key="your_public_key",
+     private_key="your_private_key",
+     bucket="your-bucket",
+     region="cn-bj"
+ )
+ 
+ # 上传文件
+ with open("image.jpg", "rb") as f:
+     resp = ufile.put("photos/image.jpg", f.read(), content_type="image/jpg")
+ print(resp.status_code)  # 200
+ 
+ # 带重试的上传（默认重试 3 次）
+ success = ufile.put_with_retry("backup/data.zip", data, retries=3)
+ print(success)  # True/False
+ 
+ # 获取文件 URL
+ url = ufile.get_path_url("photos/image.jpg")
+ print(url)  # https://your-bucket.cn-bj.ufileos.com/photos/image.jpg
+ 
+ # 生成分享链接（私有空间，默认 20 分钟有效）
+ share_url = ufile.get_shared_url("photos/image.jpg", expire_time=3600)
+ print(share_url)
+ 
+ # 判断文件是否存在
+ exists = ufile.exists("photos/image.jpg")
+ print(exists)  # True/False
+ 
+ # 下载文件
+ resp = ufile.get("photos/image.jpg")
+ with open("downloaded.jpg", "wb") as f:
+     f.write(resp.content)
+ 
+ # 查询文件信息
+ resp = ufile.head("photos/image.jpg")
+ print(resp.headers["Content-Length"])
+ 
+ # 列出文件
+ resp = ufile.list(prefix="photos/", limit=50)
+ files = resp.json()["DataSet"]
+ 
+ # 删除文件
+ resp = ufile.delete("photos/image.jpg")
+ print(resp.status_code)  # 204
+ ```
+ 
+ ## 高级功能
+ 
+ ### 自定义域名（CDN）
+ 
+ ```python
+ ufile = UCloudFileClient(
+     public_key="your_public_key",
+     private_key="your_private_key",
+     bucket="your-bucket",
+     region="cn-bj",
+     domain_url="https://cdn.example.com"  # 自定义 CDN 域名
+ )
+ ```
+ 
+ ### 内网访问
+ 
+ ```python
+ ufile = UCloudFileClient(
+     public_key="your_public_key",
+     private_key="your_private_key",
+     bucket="your-bucket",
+     region="cn-wlcb",
+     internal=True  # 使用内网访问
+ )
+ ```
+ 
+ ### 分片上传（大文件）
+ 
+ ```python
+ # 自动分片上传，支持进度回调
+ def progress_callback(part_number, total_parts, uploaded, total):
+     print(f"进度: {part_number + 1}/{total_parts}")
+ 
+ result = ufile.multipart_upload(
+     key="videos/large.mp4",
+     file_path="/path/to/large.mp4",
+     content_type="video/mp4",
+     callback=progress_callback
+ )
+ ```
+ 
+ 
+Requires-Dist: requests

multibucket-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+multibucket/ucloud.cp313-win_amd64.pyd,sha256=ypDDATdT8wBFqU-N-WFxz6iqzUCHQvJxkkDSKvIw4vQ,154624
+multibucket/ucloud.pyi,sha256=acmnIq7iEuLjAv16faLdAGtzyI8xl4QpSvsV_mIdDRM,12954
+multibucket/__init__.py,sha256=lfMf-Ui4-n7AUqLQc0scjrnPBO-6HhbGe2ysrlKjQfo,106
+multibucket-0.1.2.dist-info/METADATA,sha256=r86kVm05U-ydwlekGbE5uL_IGBoYlP3KtiRMrRsZUEc,2888
+multibucket-0.1.2.dist-info/WHEEL,sha256=dn77BUfjMOPRkZt-Pyb_fdAFpXI4sKyN3v0I_j_INQ0,114
+multibucket-0.1.2.dist-info/RECORD,,

multibucket-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: multibucket-protected-builder
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64