stellarmesh-objectstorage 0.1.0__tar.gz

stellarmesh_objectstorage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L1ndenbaum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stellarmesh_objectstorage-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: stellarmesh-objectstorage
+Version: 0.1.0
+Summary: 基于 Boto3 与 aioboto3 的进程内对象存储客户端
+License-Expression: MIT
+Project-URL: Repository, https://github.com/L1ndenbaum/stellarmesh-sdk
+Project-URL: Documentation, https://github.com/L1ndenbaum/stellarmesh-sdk/blob/dev/docs/sdk/python/objectstorage.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aioboto3==15.5.0
+Requires-Dist: boto3<1.40.62,>=1.40.46
+Dynamic: license-file
+
+# Stellarmesh Python 对象存储 SDK
+
+直接访问 AWS S3／MinIO 的小型进程内客户端，同步使用 Boto3，异步使用 aioboto3。
+不需要 Storage 服务。要求 Python 3.11+，Bucket 和项目凭据由业务部署准备。
+
+```sh
+pip install stellarmesh-objectstorage==0.1.0
+```
+
+```python
+from stellarmesh_objectstorage import Client, ClientConfig, StorageError
+
+config = ClientConfig(bucket="example-documents", region="us-east-1")
+try:
+    with Client(config) as storage:
+        result = storage.upload_bytes("hello.txt", b"hello", content_type="text/plain")
+        print(result.etag)
+except StorageError:
+    raise
+```
+
+凭据默认使用标准 AWS 凭据链，也可以注入 Session；不要将项目长期凭据交给浏览器。
+异步客户端使用 `async with AsyncClient(config) as storage`，对象流也必须使用上下文关闭。
+单次上传限制 5 GiB，较大对象使用显式 Multipart；SDK 不管理业务上传会话或自动创建 Bucket。
+写入超时或取消不代表服务端没有完成；ETag 是不透明值，不保证为 MD5。
+
+完整接入、生命周期与验证边界见[中文指南](https://github.com/L1ndenbaum/stellarmesh-sdk/blob/dev/docs/sdk/python/objectstorage.md)。

stellarmesh_objectstorage-0.1.0/README.md

@@ -0,0 +1,27 @@
+# Stellarmesh Python 对象存储 SDK
+
+直接访问 AWS S3／MinIO 的小型进程内客户端，同步使用 Boto3，异步使用 aioboto3。
+不需要 Storage 服务。要求 Python 3.11+，Bucket 和项目凭据由业务部署准备。
+
+```sh
+pip install stellarmesh-objectstorage==0.1.0
+```
+
+```python
+from stellarmesh_objectstorage import Client, ClientConfig, StorageError
+
+config = ClientConfig(bucket="example-documents", region="us-east-1")
+try:
+    with Client(config) as storage:
+        result = storage.upload_bytes("hello.txt", b"hello", content_type="text/plain")
+        print(result.etag)
+except StorageError:
+    raise
+```
+
+凭据默认使用标准 AWS 凭据链，也可以注入 Session；不要将项目长期凭据交给浏览器。
+异步客户端使用 `async with AsyncClient(config) as storage`，对象流也必须使用上下文关闭。
+单次上传限制 5 GiB，较大对象使用显式 Multipart；SDK 不管理业务上传会话或自动创建 Bucket。
+写入超时或取消不代表服务端没有完成；ETag 是不透明值，不保证为 MD5。
+
+完整接入、生命周期与验证边界见[中文指南](https://github.com/L1ndenbaum/stellarmesh-sdk/blob/dev/docs/sdk/python/objectstorage.md)。

stellarmesh_objectstorage-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stellarmesh-objectstorage"
+version = "0.1.0"
+description = "基于 Boto3 与 aioboto3 的进程内对象存储客户端"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["aioboto3==15.5.0", "boto3>=1.40.46,<1.40.62"]
+
+[project.urls]
+Repository = "https://github.com/L1ndenbaum/stellarmesh-sdk"
+Documentation = "https://github.com/L1ndenbaum/stellarmesh-sdk/blob/dev/docs/sdk/python/objectstorage.md"
+
+[dependency-groups]
+dev = ["build>=1,<2", "mypy>=1.10,<2", "pytest>=8,<9", "pytest-asyncio>=0.23,<2", "ruff>=0.6,<1", "twine>=6,<7", "httpx>=0.27,<1"]
+
+[tool.setuptools.package-data]
+stellarmesh_objectstorage = ["py.typed"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["boto3.*", "botocore.*", "aioboto3.*", "aiobotocore.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "strict"
+testpaths = ["tests"]

stellarmesh_objectstorage-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stellarmesh_objectstorage-0.1.0/src/stellarmesh_objectstorage/__init__.py

@@ -0,0 +1,39 @@
+"""Python 进程内 S3／MinIO 客户端；业务配置、权限与资源部署由调用方负责。"""
+
+from .async_client import AsyncClient
+from .client import Client
+from .config import ClientConfig
+from .errors import (
+    ClientClosedError,
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    PreconditionFailedError,
+    StorageError,
+    UnavailableError,
+)
+from .multipart import CompletedPart, MultipartUpload
+from .objects import AsyncObjectStream, ObjectInfo, ObjectStream, WriteResult
+from .presign import PresignedRequest
+
+__all__ = [
+    "AsyncClient",
+    "AsyncObjectStream",
+    "Client",
+    "ClientClosedError",
+    "ClientConfig",
+    "CompletedPart",
+    "ConflictError",
+    "ForbiddenError",
+    "InvalidRequestError",
+    "MultipartUpload",
+    "NotFoundError",
+    "ObjectInfo",
+    "ObjectStream",
+    "PreconditionFailedError",
+    "PresignedRequest",
+    "StorageError",
+    "UnavailableError",
+    "WriteResult",
+]

stellarmesh_objectstorage-0.1.0/src/stellarmesh_objectstorage/_files.py

@@ -0,0 +1,44 @@
+"""文件传输的原子提交与取消隔离，不改变网络取消语义。"""
+
+import asyncio
+import tempfile
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import BinaryIO, TypeVar, cast
+
+T = TypeVar("T")
+
+
+@contextmanager
+def atomic_destination(destination: str | Path) -> Iterator[tuple[BinaryIO, Path]]:
+    path = Path(destination)
+    # 同目录 rename 保持原子性；失败和 BaseException（包括取消）都清理暂存。
+    with tempfile.NamedTemporaryFile(
+        dir=path.parent, prefix=f".{path.name}.", delete=False
+    ) as output:
+        temporary = Path(output.name)
+        try:
+            yield cast(BinaryIO, output), temporary
+            output.close()
+            temporary.replace(path)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+
+async def file_io(operation: Callable[[], T]) -> T:
+    # 线程中的文件读写不可强制取消，先等其结束再释放文件；不用于网络请求。
+    task = asyncio.create_task(asyncio.to_thread(operation))
+    canceled: asyncio.CancelledError | None = None
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError as error:
+            canceled = error
+        except Exception:
+            break
+    if canceled is not None:
+        if not task.cancelled():
+            task.exception()
+        raise canceled
+    return task.result()

stellarmesh_objectstorage-0.1.0/src/stellarmesh_objectstorage/_requests.py

@@ -0,0 +1,145 @@
+"""同步与异步客户端共享纯参数准备；不持有网络或刷新状态。"""
+
+import base64
+import binascii
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .config import ClientConfig, text
+from .errors import InvalidRequestError
+from .multipart import CompletedPart
+from .objects import MAX_SINGLE_PUT_BYTES
+
+
+def connection_options(config: ClientConfig) -> dict[str, Any]:
+    return {
+        "region_name": config.region,
+        "endpoint_url": config.endpoint,
+    }
+
+
+def transport_options(config: ClientConfig) -> dict[str, Any]:
+    return {
+        "signature_version": "s3v4",
+        "connect_timeout": config.connect_timeout,
+        "read_timeout": config.read_timeout,
+        "retries": {"mode": "standard", "total_max_attempts": config.max_attempts},
+        "s3": {"addressing_style": "path" if config.use_path_style else "virtual"},
+        # 使用各厂商都支持的必要校验；不隐式为普通上传启用 aws-chunked。
+        "request_checksum_calculation": "when_required",
+        "response_checksum_validation": "when_required",
+    }
+
+
+def object_request(
+    config: ClientConfig, key: str, version_id: str | None = None
+) -> dict[str, Any]:
+    result: dict[str, Any] = {"Bucket": config.bucket, "Key": config.physical_key(key)}
+    if version_id is not None:
+        result["VersionId"] = text(version_id, "version_id")
+    return result
+
+
+def upload_fields(
+    content_type: str | None, metadata: Mapping[str, str] | None
+) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    if content_type is not None:
+        result["ContentType"] = text(content_type, "content_type")
+    if metadata is not None:
+        copied = {}
+        for key, value in metadata.items():
+            text(key, "metadata key")
+            text(value, "metadata value", empty=True)
+            # HTTP 头字段名大小写不敏感，避免签名与实际传输出现两个来源。
+            lowered = key.lower()
+            if lowered in copied:
+                raise InvalidRequestError("metadata 字段名不能大小写重复")
+            try:
+                key.encode("ascii")
+                value.encode("ascii")
+            except UnicodeError as error:
+                raise InvalidRequestError("S3 metadata 必须使用 ASCII") from error
+            if any(
+                char not in "!#$%&'*+-.^_`|~0123456789abcdefghijklmnopqrstuvwxyz"
+                for char in lowered
+            ):
+                raise InvalidRequestError("metadata 字段名不是合法 HTTP token")
+            copied[lowered] = value
+        result["Metadata"] = copied
+    return result
+
+
+def size_value(size: int) -> int:
+    if type(size) is not int or not 0 <= size <= MAX_SINGLE_PUT_BYTES:
+        raise InvalidRequestError("单次上传大小须在 0～5 GiB；较大对象请使用 Multipart")
+    return size
+
+
+def upload_request(
+    config: ClientConfig,
+    key: str,
+    size: int,
+    content_type: str | None,
+    metadata: Mapping[str, str] | None,
+    checksum_sha256: str | None = None,
+) -> dict[str, Any]:
+    checksum = {}
+    if checksum_sha256 is not None:
+        try:
+            digest = base64.b64decode(checksum_sha256, validate=True)
+        except (ValueError, TypeError, binascii.Error) as error:
+            raise InvalidRequestError(
+                "checksum_sha256 必须是 base64 SHA-256"
+            ) from error
+        if len(digest) != 32:
+            raise InvalidRequestError("checksum_sha256 必须是 32 字节摘要")
+        checksum["ChecksumSHA256"] = checksum_sha256
+    return {
+        **checksum,
+        **object_request(config, key),
+        "ContentLength": size_value(size),
+        **upload_fields(content_type, metadata),
+    }
+
+
+def multipart_request(config: ClientConfig, key: str, upload_id: str) -> dict[str, Any]:
+    return {**object_request(config, key), "UploadId": text(upload_id, "upload_id")}
+
+
+def part_number(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 10000:
+        raise InvalidRequestError("分片编号必须在 1～10000 之间")
+    return value
+
+
+def completed_parts(parts: Sequence[CompletedPart]) -> dict[str, Any]:
+    if not parts:
+        raise InvalidRequestError("完成分片列表不能为空")
+    seen: set[int] = set()
+    result = []
+    for part in parts:
+        number = part_number(part.part_number)
+        if number in seen:
+            raise InvalidRequestError("分片编号不能重复")
+        seen.add(number)
+        etag = text(part.etag, "etag")
+        if not etag.strip():
+            raise InvalidRequestError("etag 不能为空白")
+        result.append({"PartNumber": number, "ETag": etag})
+    return {"Parts": sorted(result, key=lambda part: part["PartNumber"])}
+
+
+def signed_headers(params: dict[str, Any]) -> dict[str, str]:
+    headers = (
+        {"Content-Length": str(params["ContentLength"])}
+        if "ContentLength" in params
+        else {}
+    )
+    if "ChecksumSHA256" in params:
+        headers["x-amz-checksum-sha256"] = params["ChecksumSHA256"]
+    if "ContentType" in params:
+        headers["Content-Type"] = params["ContentType"]
+    for key, value in params.get("Metadata", {}).items():
+        headers["x-amz-meta-" + key] = value
+    return headers

stellarmesh_objectstorage-0.1.0/src/stellarmesh_objectstorage/async_client.py

@@ -0,0 +1,312 @@
+"""复用连接的 aioboto3 异步客户端。"""
+
+import asyncio
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import AsyncExitStack, asynccontextmanager
+from datetime import UTC, datetime, timedelta
+from functools import partial
+from pathlib import Path
+from types import TracebackType
+from typing import Any, cast
+
+import aioboto3
+from aiobotocore.config import AioConfig as Config
+from botocore.exceptions import BotoCoreError, ClientError
+
+from . import _requests as requests
+from ._files import atomic_destination, file_io
+from .config import ClientConfig
+from .errors import ClientClosedError, InvalidRequestError, provider_error
+from .multipart import CompletedPart, MultipartUpload
+from .objects import (
+    AsyncObjectStream,
+    ObjectInfo,
+    WriteResult,
+    object_info,
+    write_result,
+)
+from .presign import PresignedRequest
+
+
+class AsyncClient:
+    """通过 async with 打开的 aioboto3 客户端；在同一事件循环内复用。
+
+    只关闭自己创建的底层连接，不关闭注入的 Session。必须在生命周期入口打开，
+    不在业务调用中懒初始化；关闭前由调用方停止在途请求和对象流。
+    """
+
+    def __init__(
+        self, config: ClientConfig, *, session: aioboto3.Session | None = None
+    ) -> None:
+        self._config = config
+        self._session = session
+        self._stack = AsyncExitStack()
+        self._client: Any = None
+        self._signer: Any = None
+        self._entered = False
+        self._closed = False
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._close_task: asyncio.Task[None] | None = None
+
+    @property
+    def config(self) -> ClientConfig:
+        """客户端固定绑定的只读配置。"""
+        return self._config
+
+    async def __aenter__(self) -> "AsyncClient":
+        if self._entered or self._closed:
+            raise ClientClosedError("异步客户端不能重复打开")
+        self._entered = True
+        self._loop = asyncio.get_running_loop()
+        session = self._session or aioboto3.Session()
+        options = requests.connection_options(self.config)
+        options["config"] = Config(**requests.transport_options(self.config))
+        try:
+            self._client = await self._stack.enter_async_context(
+                session.client("s3", **options)
+            )
+            self._signer = self._client
+            if (
+                self.config.presign_endpoint
+                and self.config.presign_endpoint != self.config.endpoint
+            ):
+                options["endpoint_url"] = self.config.presign_endpoint
+                self._signer = await self._stack.enter_async_context(
+                    session.client("s3", **options)
+                )
+        except BaseException:
+            await self.aclose()
+            raise
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """关闭底层连接；重复取消也等待清理完成，再传播 CancelledError。"""
+        if self._loop is not None and self._loop is not asyncio.get_running_loop():
+            raise InvalidRequestError("异步客户端不能跨事件循环关闭")
+        self._closed = True
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._stack.aclose())
+        canceled: asyncio.CancelledError | None = None
+        while not self._close_task.done():
+            try:
+                await asyncio.shield(self._close_task)
+            except asyncio.CancelledError as error:
+                canceled = error
+            except Exception:
+                break
+        if canceled is not None:
+            if not self._close_task.cancelled():
+                self._close_task.exception()
+            raise canceled
+        self._close_task.result()
+
+    def _ensure_open(self) -> None:
+        if self._closed or self._client is None:
+            raise ClientClosedError("异步对象存储客户端未打开或已关闭")
+        if self._loop is not asyncio.get_running_loop():
+            raise InvalidRequestError("异步客户端不能跨事件循环共享")
+
+    async def _call(self, operation: str, params: dict[str, Any]) -> dict[str, Any]:
+        self._ensure_open()
+        try:
+            return cast(
+                dict[str, Any], await getattr(self._client, operation)(**params)
+            )
+        except (BotoCoreError, ClientError) as error:
+            raise provider_error(error) from error
+
+    async def check(self) -> None:
+        """执行 HeadBucket 检查；不创建 Bucket，也不证明具有全部对象权限。"""
+        await self._call("head_bucket", {"Bucket": self.config.bucket})
+
+    async def stat(self, key: str, *, version_id: str | None = None) -> ObjectInfo:
+        """读取元数据；version_id 省略时查询当前对象。"""
+        return object_info(
+            key,
+            await self._call(
+                "head_object", requests.object_request(self.config, key, version_id)
+            ),
+        )
+
+    async def delete(self, key: str, *, version_id: str | None = None) -> None:
+        """删除对象或指定版本；删除标记行为由 Bucket 版本策略决定。"""
+        await self._call(
+            "delete_object", requests.object_request(self.config, key, version_id)
+        )
+
+    async def upload_bytes(
+        self,
+        key: str,
+        data: bytes,
+        *,
+        content_type: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        checksum_sha256: str | None = None,
+    ) -> WriteResult:
+        """单次上传最多 5 GiB，直接返回写入 ETag，不额外 Stat。"""
+        if not isinstance(data, bytes):
+            raise InvalidRequestError("data 必须是 bytes")
+        params = requests.upload_request(
+            self.config, key, len(data), content_type, metadata, checksum_sha256
+        )
+        return write_result(await self._call("put_object", {**params, "Body": data}))
+
+    async def upload_file(
+        self,
+        key: str,
+        source: str | Path,
+        *,
+        content_type: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        checksum_sha256: str | None = None,
+    ) -> WriteResult:
+        """单次文件上传，不自动分片；上传及重试期间调用方不得修改源文件。"""
+        self._ensure_open()
+        with Path(source).open("rb") as body:
+            params = requests.upload_request(
+                self.config,
+                key,
+                Path(source).stat().st_size,
+                content_type,
+                metadata,
+                checksum_sha256,
+            )
+            return write_result(
+                await self._call("put_object", {**params, "Body": body})
+            )
+
+    @asynccontextmanager
+    async def open_object(
+        self, key: str, *, version_id: str | None = None
+    ) -> AsyncIterator[AsyncObjectStream]:
+        """在 async with 中读取对象；异常或提前退出都会关闭响应体，读流失败不重放。"""
+        response = await self._call(
+            "get_object", requests.object_request(self.config, key, version_id)
+        )
+        body = response["Body"]
+        try:
+            stream = AsyncObjectStream(object_info(key, response), body)
+        except BaseException:
+            body.close()
+            raise
+        try:
+            yield stream
+        finally:
+            await stream.aclose()
+
+    async def download_file(
+        self, key: str, destination: str | Path, *, version_id: str | None = None
+    ) -> ObjectInfo:
+        """下载成功后原子替换目标；失败清理临时文件，父目录须由调用方准备。"""
+        async with self.open_object(key, version_id=version_id) as stream:
+            with atomic_destination(destination) as (output, _):
+                async for chunk in stream.iter_chunks():
+                    await file_io(partial(output.write, chunk))
+            return stream.info
+
+    async def _presign(
+        self,
+        operation: str,
+        method: str,
+        params: dict[str, Any],
+        expires_in: int | None,
+    ) -> PresignedRequest:
+        self._ensure_open()
+        ttl = self.config.ttl(expires_in)
+        expires_at = datetime.now(UTC) + timedelta(seconds=ttl)
+        try:
+            url = await self._signer.generate_presigned_url(
+                operation, Params=params, ExpiresIn=ttl, HttpMethod=method
+            )
+        except (BotoCoreError, ClientError) as error:
+            raise provider_error(error) from error
+        return PresignedRequest(
+            url, method, requests.signed_headers(params), expires_at
+        )
+
+    async def presign_get(
+        self, key: str, *, version_id: str | None = None, expires_in: int | None = None
+    ) -> PresignedRequest:
+        """签发下载请求；不检查对象存在性，默认有效期 900 秒。"""
+        return await self._presign(
+            "get_object",
+            "GET",
+            requests.object_request(self.config, key, version_id),
+            expires_in,
+        )
+
+    async def presign_put(
+        self,
+        key: str,
+        *,
+        size: int,
+        content_type: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+        checksum_sha256: str | None = None,
+        expires_in: int | None = None,
+    ) -> PresignedRequest:
+        """签发单次上传；执行时须保留声明的大小、媒体类型及元数据头。"""
+        return await self._presign(
+            "put_object",
+            "PUT",
+            requests.upload_request(
+                self.config, key, size, content_type, metadata, checksum_sha256
+            ),
+            expires_in,
+        )
+
+    async def create_multipart(
+        self,
+        key: str,
+        *,
+        content_type: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+    ) -> MultipartUpload:
+        """创建分片会话；调用方负责保存 upload_id 并完成或中止。"""
+        params = {
+            **requests.object_request(self.config, key),
+            **requests.upload_fields(content_type, metadata),
+        }
+        return MultipartUpload(
+            key, (await self._call("create_multipart_upload", params))["UploadId"]
+        )
+
+    async def presign_part(
+        self,
+        key: str,
+        upload_id: str,
+        part_number: int,
+        *,
+        expires_in: int | None = None,
+    ) -> PresignedRequest:
+        """为 1～10000 号分片签发 PUT 请求；签名不证明会话存在。"""
+        params = {
+            **requests.multipart_request(self.config, key, upload_id),
+            "PartNumber": requests.part_number(part_number),
+        }
+        return await self._presign("upload_part", "PUT", params, expires_in)
+
+    async def complete_multipart(
+        self, key: str, upload_id: str, parts: Sequence[CompletedPart]
+    ) -> WriteResult:
+        """按编号排序后完成上传；拒绝空列表与重复编号，不修改调用方列表。"""
+        params = {
+            **requests.multipart_request(self.config, key, upload_id),
+            "MultipartUpload": requests.completed_parts(parts),
+        }
+        return write_result(await self._call("complete_multipart_upload", params))
+
+    async def abort_multipart(self, key: str, upload_id: str) -> None:
+        """中止分片会话；NoSuchUpload 保持 NotFoundError，不伪装成功。"""
+        await self._call(
+            "abort_multipart_upload",
+            requests.multipart_request(self.config, key, upload_id),
+        )