stellarmesh-objectstorage 0.1.0__py3-none-any.whl

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/_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/_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/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),
+        )

stellarmesh_objectstorage/client.py

@@ -0,0 +1,270 @@
+"""复用连接的 Boto3 同步客户端。"""
+
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import ExitStack, contextmanager
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from types import TracebackType
+from typing import Any, cast
+
+import boto3
+from botocore.config import Config
+from botocore.exceptions import BotoCoreError, ClientError
+
+from . import _requests as requests
+from ._files import atomic_destination
+from .config import ClientConfig
+from .errors import ClientClosedError, InvalidRequestError, provider_error
+from .multipart import CompletedPart, MultipartUpload
+from .objects import ObjectInfo, ObjectStream, WriteResult, object_info, write_result
+from .presign import PresignedRequest
+
+
+class Client:
+    """固定绑定 Bucket／Prefix 的同步对象存储客户端。
+
+    Session 可注入，否则使用标准 AWS 凭据链。客户端拥有其创建的连接，
+    调用方使用 with 或 close 关闭；不要跨进程共享或在请求中途并发关闭。
+    不创建 Bucket，不执行隐式健康检查，不管理业务上传会话。
+    """
+
+    def __init__(
+        self, config: ClientConfig, *, session: boto3.Session | None = None
+    ) -> None:
+        self._config = config
+        self._stack = ExitStack()
+        self._closed = False
+        session = session or boto3.Session()
+        options = requests.connection_options(config)
+        options["config"] = Config(**requests.transport_options(config))
+        try:
+            self._client = session.client("s3", **options)
+            self._stack.callback(self._client.close)
+            self._signer = self._client
+            if config.presign_endpoint and config.presign_endpoint != config.endpoint:
+                options["endpoint_url"] = config.presign_endpoint
+                self._signer = session.client("s3", **options)
+                self._stack.callback(self._signer.close)
+        except BaseException:
+            self._stack.close()
+            raise
+
+    @property
+    def config(self) -> ClientConfig:
+        """客户端固定绑定的只读配置。"""
+        return self._config
+
+    def __enter__(self) -> "Client":
+        self._ensure_open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """幂等关闭创建的底层客户端；不关闭业务注入的 Session。"""
+        if not self._closed:
+            self._closed = True
+            self._stack.close()
+
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise ClientClosedError("对象存储客户端已关闭")
+
+    def _call(self, operation: str, params: dict[str, Any]) -> dict[str, Any]:
+        self._ensure_open()
+        try:
+            return cast(dict[str, Any], getattr(self._client, operation)(**params))
+        except (BotoCoreError, ClientError) as error:
+            raise provider_error(error) from error
+
+    def check(self) -> None:
+        """执行 HeadBucket 检查；不创建 Bucket，也不证明具有全部对象权限。"""
+        self._call("head_bucket", {"Bucket": self.config.bucket})
+
+    def stat(self, key: str, *, version_id: str | None = None) -> ObjectInfo:
+        """读取元数据；version_id 省略时查询当前对象。"""
+        return object_info(
+            key,
+            self._call(
+                "head_object", requests.object_request(self.config, key, version_id)
+            ),
+        )
+
+    def delete(self, key: str, *, version_id: str | None = None) -> None:
+        """删除对象或指定版本；删除标记行为由 Bucket 版本策略决定。"""
+        self._call(
+            "delete_object", requests.object_request(self.config, key, version_id)
+        )
+
+    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(self._call("put_object", {**params, "Body": data}))
+
+    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(self._call("put_object", {**params, "Body": body}))
+
+    @contextmanager
+    def open_object(
+        self, key: str, *, version_id: str | None = None
+    ) -> Iterator[ObjectStream]:
+        """在 with 中读取对象；异常或提前退出都会关闭响应体，读流失败不重放。"""
+        response = self._call(
+            "get_object", requests.object_request(self.config, key, version_id)
+        )
+        body = response["Body"]
+        try:
+            stream = ObjectStream(object_info(key, response), body)
+        except BaseException:
+            body.close()
+            raise
+        try:
+            yield stream
+        finally:
+            stream.close()
+
+    def download_file(
+        self, key: str, destination: str | Path, *, version_id: str | None = None
+    ) -> ObjectInfo:
+        """下载成功后原子替换目标；失败清理临时文件，父目录须由调用方准备。"""
+        with self.open_object(key, version_id=version_id) as stream:
+            with atomic_destination(destination) as (output, _):
+                for chunk in stream.iter_chunks():
+                    output.write(chunk)
+            return stream.info
+
+    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 = 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
+        )
+
+    def presign_get(
+        self, key: str, *, version_id: str | None = None, expires_in: int | None = None
+    ) -> PresignedRequest:
+        """签发下载请求；不检查对象存在性，默认有效期 900 秒。"""
+        return self._presign(
+            "get_object",
+            "GET",
+            requests.object_request(self.config, key, version_id),
+            expires_in,
+        )
+
+    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 self._presign(
+            "put_object",
+            "PUT",
+            requests.upload_request(
+                self.config, key, size, content_type, metadata, checksum_sha256
+            ),
+            expires_in,
+        )
+
+    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, self._call("create_multipart_upload", params)["UploadId"]
+        )
+
+    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 self._presign("upload_part", "PUT", params, expires_in)
+
+    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(self._call("complete_multipart_upload", params))
+
+    def abort_multipart(self, key: str, upload_id: str) -> None:
+        """中止分片会话；NoSuchUpload 保持 NotFoundError，不伪装成功。"""
+        self._call(
+            "abort_multipart_upload",
+            requests.multipart_request(self.config, key, upload_id),
+        )

stellarmesh_objectstorage/config.py

@@ -0,0 +1,119 @@
+"""单个 Bucket／Prefix 的不可变连接配置。"""
+
+import math
+import unicodedata
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from .errors import InvalidRequestError
+
+
+def text(value: str, name: str, *, empty: bool = False) -> str:
+    if not isinstance(value, str) or (not empty and not value):
+        raise InvalidRequestError(f"{name} 必须是非空字符串")
+    try:
+        value.encode("utf-8")
+    except UnicodeError as error:
+        raise InvalidRequestError(f"{name} 必须是有效 UTF-8") from error
+    if any(unicodedata.category(char) == "Cc" for char in value):
+        raise InvalidRequestError(f"{name} 不能包含控制字符")
+    return value
+
+
+@dataclass(frozen=True, kw_only=True)
+class ClientConfig:
+    """绑定存储位置和传输策略，不持有凭据。
+
+    Args:
+        bucket: 已由部署创建的 Bucket。
+        region: 显式签名 Region。
+        prefix: 可选物理前缀；非空时规范为一个结尾斜杠。
+        endpoint: 内部 S3 根地址；None 使用 AWS 标准端点。
+        presign_endpoint: 面向签名消费者的根地址，省略沿用 endpoint。
+        use_path_style: MinIO 常设为 True，默认 False。
+        connect_timeout: 连接超时秒数，默认 5。
+        read_timeout: 单次读取超时秒数，默认 5，不是整次传输期限。
+        max_attempts: standard 模式总尝试次数，包含首次，默认 3。
+        default_presign_ttl: 预签名默认秒数，默认 900，范围 60～3600。
+    """
+
+    bucket: str
+    region: str
+    prefix: str = ""
+    endpoint: str | None = None
+    presign_endpoint: str | None = None
+    use_path_style: bool = False
+    connect_timeout: float = 5.0
+    read_timeout: float = 5.0
+    max_attempts: int = 3
+    default_presign_ttl: int = 900
+
+    def __post_init__(self) -> None:
+        for name in ("bucket", "region"):
+            value = text(getattr(self, name), name)
+            if value != value.strip():
+                raise InvalidRequestError(f"{name} 不能包含首尾空白")
+        prefix = text(self.prefix, "prefix", empty=True)
+        if prefix.startswith("/"):
+            raise InvalidRequestError("prefix 不能以 / 开头")
+        prefix = prefix.rstrip("/")
+        object.__setattr__(self, "prefix", prefix + "/" if prefix else "")
+        if len(self.prefix.encode()) > 1024:
+            raise InvalidRequestError("prefix 超过对象键字节限制")
+        for name in ("endpoint", "presign_endpoint"):
+            value = getattr(self, name)
+            if value is not None:
+                self._validate_endpoint(value)
+        if self.presign_endpoint is not None and self.endpoint is None:
+            raise InvalidRequestError("配置 presign_endpoint 时必须设置 endpoint")
+        if type(self.use_path_style) is not bool:
+            raise InvalidRequestError("use_path_style 必须是布尔值")
+        for timeout in (self.connect_timeout, self.read_timeout):
+            if (
+                type(timeout) not in (int, float)
+                or not math.isfinite(timeout)
+                or timeout <= 0
+            ):
+                raise InvalidRequestError("超时必须是有限正数")
+        if type(self.max_attempts) is not int or not 1 <= self.max_attempts <= 10:
+            raise InvalidRequestError("max_attempts 必须在 1～10 之间")
+        self.ttl(self.default_presign_ttl)
+
+    @staticmethod
+    def _validate_endpoint(value: str) -> None:
+        text(value, "endpoint")
+        try:
+            parsed = urlsplit(value)
+            _ = parsed.port
+        except ValueError as error:
+            raise InvalidRequestError("endpoint 非法") from error
+        if (
+            value != value.strip()
+            or parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path not in {"", "/"}
+            or parsed.query
+            or parsed.fragment
+        ):
+            raise InvalidRequestError(
+                "endpoint 必须是无凭据、路径或查询参数的 HTTP(S) 根地址"
+            )
+
+    def physical_key(self, key: str) -> str:
+        """组合 Prefix 与逻辑 key，不裁剪或规范化对象键内容。"""
+        text(key, "key")
+        if key != key.strip() or key.startswith("/"):
+            raise InvalidRequestError("key 不能以 / 开头或包含首尾空白")
+        result = self.prefix + key
+        if len(result.encode()) > 1024:
+            raise InvalidRequestError("物理对象键超过 1024 字节")
+        return result
+
+    def ttl(self, value: int | None) -> int:
+        """解析预签名秒数；None 使用客户端默认值。"""
+        result = self.default_presign_ttl if value is None else value
+        if type(result) is not int or not 60 <= result <= 3600:
+            raise InvalidRequestError("预签名有效期必须在 60～3600 秒之间")
+        return result

stellarmesh_objectstorage/errors.py

@@ -0,0 +1,71 @@
+"""稳定错误类别；底层诊断仅通过 cause 保留，不拼接凭据或签名 URL。"""
+
+from typing import Any
+
+from botocore.exceptions import BotoCoreError, ClientError
+
+
+class StorageError(Exception):
+    """对象存储失败；__cause__ 保留原始异常，日志不应直接展开敏感诊断。"""
+
+
+class InvalidRequestError(StorageError, ValueError):
+    """配置、逻辑 key 或操作参数非法。"""
+
+
+class NotFoundError(StorageError):
+    """对象、版本、Bucket 或分片会话不存在。"""
+
+
+class ForbiddenError(StorageError):
+    """凭据无效或存储端拒绝访问。"""
+
+
+class ConflictError(StorageError):
+    """存储端报告操作冲突。"""
+
+
+class PreconditionFailedError(StorageError):
+    """存储端拒绝条件请求。"""
+
+
+class UnavailableError(StorageError):
+    """连接、超时、服务或无法归类的存储故障。"""
+
+
+class ClientClosedError(StorageError):
+    """客户端未打开或已关闭。"""
+
+
+def provider_error(error: BotoCoreError | ClientError) -> StorageError:
+    kind: type[StorageError] = UnavailableError
+    if isinstance(error, ClientError):
+        response: dict[str, Any] = error.response
+        code = str(response.get("Error", {}).get("Code", ""))
+        status = response.get("ResponseMetadata", {}).get("HTTPStatusCode")
+        if (
+            code
+            in {
+                "NoSuchKey",
+                "NoSuchBucket",
+                "NoSuchVersion",
+                "NoSuchUpload",
+                "NotFound",
+            }
+            or status == 404
+        ):
+            kind = NotFoundError
+        elif code in {
+            "AccessDenied",
+            "InvalidAccessKeyId",
+            "SignatureDoesNotMatch",
+            "ExpiredToken",
+        } or status in {401, 403}:
+            kind = ForbiddenError
+        elif code == "PreconditionFailed" or status == 412:
+            kind = PreconditionFailedError
+        elif code == "ConditionalRequestConflict" or status == 409:
+            kind = ConflictError
+        elif status == 400:
+            kind = InvalidRequestError
+    return kind("对象存储请求失败")

stellarmesh_objectstorage/multipart.py

@@ -0,0 +1,19 @@
+"""显式分片上传标识与完成参数，业务方负责会话保存和放弃清理。"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MultipartUpload:
+    """创建结果；key 为逻辑键，upload_id 原样交回后续操作。"""
+
+    key: str
+    upload_id: str
+
+
+@dataclass(frozen=True)
+class CompletedPart:
+    """上传成功的分片编号和存储端 ETag；不能用本地摘要替代 ETag。"""
+
+    part_number: int
+    etag: str

stellarmesh_objectstorage/objects.py

@@ -0,0 +1,116 @@
+"""对象操作结果及由上下文持有的读取流。"""
+
+from collections.abc import AsyncIterator, Iterator, Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, cast
+
+from botocore.exceptions import BotoCoreError, ClientError
+
+from .errors import ClientClosedError, InvalidRequestError, provider_error
+
+CHUNK_SIZE = 1024 * 1024
+MAX_SINGLE_PUT_BYTES = 5 * 1024**3
+
+
+@dataclass(frozen=True)
+class WriteResult:
+    """存储端写入结果；ETag 为不透明值，可能缺失，不代表内容 MD5。"""
+
+    etag: str | None
+    version_id: str | None = None
+
+
+@dataclass(frozen=True)
+class ObjectInfo:
+    """逻辑对象元数据；key 不包含客户端绑定的物理 Prefix。"""
+
+    key: str
+    size: int
+    etag: str | None = None
+    version_id: str | None = None
+    content_type: str | None = None
+    last_modified: datetime | None = None
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+def object_info(key: str, response: dict[str, Any]) -> ObjectInfo:
+    return ObjectInfo(
+        key=key,
+        size=response["ContentLength"],
+        etag=response.get("ETag"),
+        version_id=response.get("VersionId"),
+        content_type=response.get("ContentType"),
+        last_modified=response.get("LastModified"),
+        metadata=dict(response.get("Metadata", {})),
+    )
+
+
+def write_result(response: dict[str, Any]) -> WriteResult:
+    return WriteResult(response.get("ETag"), response.get("VersionId"))
+
+
+class ObjectStream:
+    """仅在 open_object 上下文内使用的同步流；退出时关闭底层响应。"""
+
+    def __init__(self, info: ObjectInfo, body: Any) -> None:
+        self.info = info
+        self._body = body
+        self._closed = False
+
+    def read(self, size: int = -1) -> bytes:
+        """读取至多 size 字节；-1 读取剩余全部，调用方承担内存预算。"""
+        if self._closed:
+            raise ClientClosedError("对象读取流已关闭")
+        if type(size) is not int or size < -1:
+            raise InvalidRequestError("读取大小必须是 -1 或非负整数")
+        try:
+            return cast(bytes, self._body.read(None if size == -1 else size))
+        except (BotoCoreError, ClientError) as error:
+            raise provider_error(error) from error
+
+    def iter_chunks(self, chunk_size: int = CHUNK_SIZE) -> Iterator[bytes]:
+        """按消费进度读取，不预先缓存整个对象。"""
+        if type(chunk_size) is not int or chunk_size <= 0:
+            raise InvalidRequestError("分块大小必须是正整数")
+        while chunk := self.read(chunk_size):
+            yield chunk
+
+    def close(self) -> None:
+        """幂等关闭响应体；通常由 open_object 上下文自动执行。"""
+        if not self._closed:
+            self._closed = True
+            self._body.close()
+
+
+class AsyncObjectStream:
+    """仅在 open_object 异步上下文内使用的流，不跨事件循环共享。"""
+
+    def __init__(self, info: ObjectInfo, body: Any) -> None:
+        self.info = info
+        self._body = body
+        self._closed = False
+
+    async def read(self, size: int = -1) -> bytes:
+        """异步读取；取消保持 CancelledError，不重启已经开始的响应流。"""
+        if self._closed:
+            raise ClientClosedError("对象读取流已关闭")
+        if type(size) is not int or size < -1:
+            raise InvalidRequestError("读取大小必须是 -1 或非负整数")
+        try:
+            return cast(bytes, await self._body.read(None if size == -1 else size))
+        except (BotoCoreError, ClientError) as error:
+            raise provider_error(error) from error
+
+    async def iter_chunks(self, chunk_size: int = CHUNK_SIZE) -> AsyncIterator[bytes]:
+        """按需读取有界分块，消费者控制下一次读取。"""
+        if type(chunk_size) is not int or chunk_size <= 0:
+            raise InvalidRequestError("分块大小必须是正整数")
+        while chunk := await self.read(chunk_size):
+            yield chunk
+
+    async def aclose(self) -> None:
+        """幂等关闭底层 HTTP 响应；不消费剩余内容。"""
+        if not self._closed:
+            self._closed = True
+            self._body.close()

stellarmesh_objectstorage/presign.py

@@ -0,0 +1,18 @@
+"""完整预签名请求描述，不包含长期认证凭据。"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True, repr=False)
+class PresignedRequest:
+    """临时访问能力；URL 不可改写，method 与 headers 必须原样执行。
+
+    签名可能因临时凭据先到期而提前失效。不要在日志中输出 URL。
+    """
+
+    url: str
+    method: str
+    headers: Mapping[str, str]
+    expires_at: datetime

stellarmesh_objectstorage-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+stellarmesh_objectstorage/__init__.py,sha256=oRtwQhKuvBUvakpuH8njYKnrCSYBEWq-tyMrV3Ta67o,981
+stellarmesh_objectstorage/_files.py,sha256=CLOD0HaNHhNE14W-pF8O-doafdD7az5OiQ-zdVKfgWw,1478
+stellarmesh_objectstorage/_requests.py,sha256=a4YXVqWTdr-OYBAqOC_Q2ltM_HNzAbRlB3NGQBvFeT4,5269
+stellarmesh_objectstorage/async_client.py,sha256=p-7Fp0Fqpkp8Vt42EkVNbpql_04YjGgJi6GktY9_3jo,11799
+stellarmesh_objectstorage/client.py,sha256=c_eb9ydlSjryMxy0nmRjuM2bynvQhy0aMnIw2b37ESU,9947
+stellarmesh_objectstorage/config.py,sha256=IC6EUBb5dEqYoFZzfnxaoCSiOjoI9fpvsTv3WVdKB8M,5021
+stellarmesh_objectstorage/errors.py,sha256=BiKEIFhw0kSjtATolsypc3AU1cgyn_rPQoKpPAuvE1k,2143
+stellarmesh_objectstorage/multipart.py,sha256=8Y-IJxzaIHW3-lGfS1jGr3dOew80F1Rl0BzhBTekLEU,469
+stellarmesh_objectstorage/objects.py,sha256=nTFid8HkLhNYUuKGtYuigsjjKyIG-LNhKAOr0brOawo,4261
+stellarmesh_objectstorage/presign.py,sha256=6lS73IdWq3p8Wn9zvOppRcO8hM-L6aXGbFgOV9QWc_8,503
+stellarmesh_objectstorage/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stellarmesh_objectstorage-0.1.0.dist-info/licenses/LICENSE,sha256=p7EA72H4dJWApvo8NRCLcegqYr9BjEc9-rU3whYXOI0,1067
+stellarmesh_objectstorage-0.1.0.dist-info/METADATA,sha256=56D1jkulbUp0_tjVXTQRJrHPxBiqexN5MNRgaFgd2DY,1766
+stellarmesh_objectstorage-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+stellarmesh_objectstorage-0.1.0.dist-info/top_level.txt,sha256=dE2YhdFUFQMQaBF-rOyxoU_1bCkSlNc8GZadJfaAD_E,26
+stellarmesh_objectstorage-0.1.0.dist-info/RECORD,,

stellarmesh_objectstorage-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stellarmesh_objectstorage-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+stellarmesh_objectstorage