py-storebridge 1.0.0__py3-none-any.whl

py_storebridge/__init__.py

@@ -0,0 +1,126 @@
+"""py_storebridge — unified cloud storage SDK for Python."""
+
+from py_storebridge.client import StorageClient
+from py_storebridge.config import (
+    AppwriteCredentials,
+    AzureCredentials,
+    B2Credentials,
+    FirebaseCredentials,
+    GCSCredentials,
+    LogLevel,
+    MinIOCredentials,
+    PROVIDERS,
+    R2Credentials,
+    RetryConfig,
+    S3Credentials,
+    SpacesCredentials,
+    StorageConfig,
+    SupabaseCredentials,
+    Visibility,
+    parse_storage_config,
+)
+from py_storebridge.exceptions import (
+    BucketNotFoundError,
+    FileNotFoundError,
+    MaxRetriesExceededError,
+    MissingConfigError,
+    MissingDependencyError,
+    MultipartUploadError,
+    NetworkError,
+    PermissionError,
+    ProviderError,
+    StoreBridgeError,
+    StorixError,
+    TransferError,
+    UnknownMimeTypeError,
+    ValidationError,
+)
+from py_storebridge.factory import create_storage, create_storage_from_provider
+from py_storebridge.hooks import HOOK_EVENTS, HookSystem
+from py_storebridge.middleware import MiddlewareChain, MiddlewareContext
+from py_storebridge.mime import detect_mime_type
+from py_storebridge.providers.base import BaseProvider
+from py_storebridge.retry import merge_retry_config, with_retry
+from py_storebridge.schemas import (
+    CopyOptions,
+    DeleteOptions,
+    FileListEntry,
+    FileMetadata,
+    ListOptions,
+    ListResult,
+    MultipartPartResult,
+    MultipartUploadSession,
+    SignedUrlOptions,
+    TransferItemResult,
+    TransferItemStatus,
+    TransferOptions,
+    TransferResult,
+    UploadOptions,
+    UploadPartOptions,
+    UploadResult,
+)
+from py_storebridge.transfer import transfer
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AppwriteCredentials",
+    "AzureCredentials",
+    "B2Credentials",
+    "BaseProvider",
+    "BucketNotFoundError",
+    "CopyOptions",
+    "DeleteOptions",
+    "FileListEntry",
+    "FileMetadata",
+    "FileNotFoundError",
+    "FirebaseCredentials",
+    "GCSCredentials",
+    "HOOK_EVENTS",
+    "HookSystem",
+    "ListOptions",
+    "ListResult",
+    "LogLevel",
+    "MaxRetriesExceededError",
+    "MiddlewareChain",
+    "MiddlewareContext",
+    "MinIOCredentials",
+    "MissingConfigError",
+    "MissingDependencyError",
+    "MultipartPartResult",
+    "MultipartUploadError",
+    "MultipartUploadSession",
+    "NetworkError",
+    "PROVIDERS",
+    "PermissionError",
+    "ProviderError",
+    "R2Credentials",
+    "RetryConfig",
+    "S3Credentials",
+    "SignedUrlOptions",
+    "SpacesCredentials",
+    "StorageClient",
+    "StorageConfig",
+    "StoreBridgeError",
+    "StorixError",
+    "SupabaseCredentials",
+    "TransferError",
+    "TransferItemResult",
+    "TransferItemStatus",
+    "TransferOptions",
+    "TransferResult",
+    "UnknownMimeTypeError",
+    "UploadOptions",
+    "UploadPartOptions",
+    "UploadResult",
+    "ValidationError",
+    "Visibility",
+    "__version__",
+    "create_storage",
+    "create_storage_from_provider",
+    "detect_mime_type",
+    "merge_retry_config",
+    "parse_storage_config",
+    "transfer",
+    "with_retry",
+]

py_storebridge/client.py

@@ -0,0 +1,222 @@
+"""Public StorageClient wrapping a provider with hooks and middleware."""
+
+from __future__ import annotations
+
+from typing import Any, BinaryIO, Iterator, List, Optional, Union
+
+from py_storebridge.exceptions import StoreBridgeError
+from py_storebridge.hooks import HookHandler, HookSystem
+from py_storebridge.middleware import Middleware, MiddlewareChain, MiddlewareContext
+from py_storebridge.providers.base import BaseProvider
+from py_storebridge.schemas import (
+    CopyOptions,
+    DeleteOptions,
+    FileListEntry,
+    FileMetadata,
+    ListOptions,
+    ListResult,
+    MultipartPartResult,
+    MultipartUploadSession,
+    SignedUrlOptions,
+    TransferOptions,
+    TransferResult,
+    UploadOptions,
+    UploadPartOptions,
+    UploadResult,
+    parse_model,
+)
+
+
+class StorageClient:
+    """Unified storage surface. Construct via ``create_storage()``."""
+
+    def __init__(self, provider: BaseProvider) -> None:
+        self._provider = provider
+        self._hooks = HookSystem()
+        self._middleware = MiddlewareChain()
+
+    @property
+    def provider_name(self) -> str:
+        return self._provider.provider_name
+
+    @property
+    def provider(self) -> BaseProvider:
+        return self._provider
+
+    def use(self, middleware: Middleware) -> "StorageClient":
+        self._middleware.use(middleware)
+        return self
+
+    def on(self, event: str, handler: HookHandler) -> "StorageClient":
+        self._hooks.on(event, handler)
+        return self
+
+    def off(self, event: str, handler: HookHandler) -> "StorageClient":
+        self._hooks.off(event, handler)
+        return self
+
+    def upload(self, options: Union[UploadOptions, dict, None] = None, **kwargs: Any) -> UploadResult:
+        parsed = parse_model(UploadOptions, options, **kwargs)
+        self._hooks.emit("before:upload", parsed)
+        try:
+            result = self._middleware.execute(
+                MiddlewareContext(options=parsed, provider=self.provider_name),
+                lambda ctx: self._provider.upload(ctx.options),
+            )
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "upload", "error": exc})
+            raise
+        self._hooks.emit("after:upload", result)
+        return result
+
+    def delete(self, options: Union[DeleteOptions, dict, None] = None, **kwargs: Any) -> None:
+        parsed = parse_model(DeleteOptions, options, **kwargs)
+        self._hooks.emit("before:delete", parsed)
+        try:
+            self._provider.delete(parsed)
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "delete", "error": exc})
+            raise
+        self._hooks.emit("after:delete", parsed)
+
+    def exists(self, key: str) -> bool:
+        return self._provider.exists(key)
+
+    def get_metadata(self, key: str) -> FileMetadata:
+        return self._provider.get_metadata(key)
+
+    def list(self, options: Union[ListOptions, dict, None] = None, **kwargs: Any) -> ListResult:
+        parsed = parse_model(ListOptions, options or kwargs or {})
+        self._hooks.emit("before:list", {"prefix": parsed.prefix})
+        try:
+            result = self._provider.list(parsed)
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "list", "error": exc})
+            raise
+        self._hooks.emit("after:list", result)
+        return result
+
+    def iter_files(self, prefix: Optional[str] = None, page_size: int = 1000) -> Iterator[FileListEntry]:
+        return self._provider.iter_files(prefix=prefix, page_size=page_size)
+
+    def get_url(self, key: str) -> str:
+        return self._provider.get_url(key)
+
+    def get_signed_url(
+        self,
+        key: str,
+        options: Union[SignedUrlOptions, dict, None] = None,
+        **kwargs: Any,
+    ) -> str:
+        parsed = parse_model(SignedUrlOptions, options, **kwargs) if options or kwargs else SignedUrlOptions()
+        self._hooks.emit("before:getSignedUrl", {"key": key, "expires_in": parsed.expires_in})
+        try:
+            url = self._provider.get_signed_url(key, parsed)
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "getSignedUrl", "error": exc})
+            raise
+        self._hooks.emit("after:getSignedUrl", {"key": key, "url": url})
+        return url
+
+    def copy(self, options: Union[CopyOptions, dict, None] = None, **kwargs: Any) -> UploadResult:
+        parsed = parse_model(CopyOptions, options, **kwargs)
+        self._hooks.emit(
+            "before:copy",
+            {"source_key": parsed.source_key, "destination_key": parsed.destination_key},
+        )
+        try:
+            result = self._provider.copy(parsed)
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "copy", "error": exc})
+            raise
+        self._hooks.emit("after:copy", result)
+        return result
+
+    def move(self, options: Union[CopyOptions, dict, None] = None, **kwargs: Any) -> UploadResult:
+        parsed = parse_model(CopyOptions, options, **kwargs)
+        self._hooks.emit(
+            "before:move",
+            {"source_key": parsed.source_key, "destination_key": parsed.destination_key},
+        )
+        try:
+            result = self._provider.move(parsed)
+        except StoreBridgeError as exc:
+            self._hooks.emit("error", {"operation": "move", "error": exc})
+            raise
+        self._hooks.emit("after:move", result)
+        return result
+
+    def rename(self, source_key: str, destination_key: str) -> UploadResult:
+        return self.move(source_key=source_key, destination_key=destination_key)
+
+    def get_stream(self, key: str) -> BinaryIO:
+        return self._provider.get_stream(key)
+
+    def get_buffer(self, key: str) -> bytes:
+        return self._provider.get_buffer(key)
+
+    def download_file(self, key: str, destination: Union[str, Any]) -> None:
+        from pathlib import Path
+
+        data = self.get_buffer(key)
+        path = Path(destination)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(data)
+
+    def upload_file(self, path: Union[str, Any], key: Optional[str] = None, **kwargs: Any) -> UploadResult:
+        from pathlib import Path
+
+        file_path = Path(path)
+        object_key = key or file_path.name
+        return self.upload(key=object_key, path=file_path, **kwargs)
+
+    def create_multipart_upload(self, key: str, content_type: Optional[str] = None) -> MultipartUploadSession:
+        return self._provider.create_multipart_upload(key, content_type)
+
+    def upload_part(self, options: Union[UploadPartOptions, dict, None] = None, **kwargs: Any) -> MultipartPartResult:
+        parsed = parse_model(UploadPartOptions, options, **kwargs)
+        return self._provider.upload_part(parsed)
+
+    def complete_multipart_upload(
+        self,
+        session: MultipartUploadSession,
+        parts: List[MultipartPartResult],
+    ) -> UploadResult:
+        return self._provider.complete_multipart_upload(session, parts)
+
+    def abort_multipart_upload(self, session: MultipartUploadSession) -> None:
+        self._provider.abort_multipart_upload(session)
+
+    def list_parts(self, session: MultipartUploadSession) -> List[FileListEntry]:
+        return self._provider.list_parts(session)
+
+    def upload_multipart(
+        self,
+        options: Union[UploadOptions, dict, None] = None,
+        chunk_size: int = 5 * 1024 * 1024,
+        **kwargs: Any,
+    ) -> UploadResult:
+        parsed = parse_model(UploadOptions, options, **kwargs)
+        return self._provider.upload_multipart(parsed, chunk_size=chunk_size)
+
+    def delete_prefix(self, prefix: str, *, continue_on_error: bool = True) -> int:
+        """Delete every object under ``prefix``. Returns the number deleted."""
+        deleted = 0
+        for entry in self.iter_files(prefix=prefix):
+            try:
+                self.delete(key=entry.key)
+                deleted += 1
+            except StoreBridgeError:
+                if not continue_on_error:
+                    raise
+        return deleted
+
+    def transfer_to(
+        self,
+        destination: "StorageClient",
+        options: Union[TransferOptions, dict, None] = None,
+        **kwargs: Any,
+    ) -> TransferResult:
+        from py_storebridge.transfer import transfer
+
+        return transfer(self, destination, options, **kwargs)

py_storebridge/config.py

@@ -0,0 +1,296 @@
+"""Pydantic configuration and credential models."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Dict, List, Literal, Optional, Union
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    TypeAdapter,
+    ValidationError as PydanticValidationError,
+    field_validator,
+    model_validator,
+)
+
+from py_storebridge.exceptions import ValidationError
+
+
+class Visibility(str, Enum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+
+
+class LogLevel(str, Enum):
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    SILENT = "silent"
+
+
+class _Model(BaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+        extra="forbid",
+        str_strip_whitespace=True,
+        use_enum_values=True,
+    )
+
+
+class RetryConfig(_Model):
+    """Retry policy. Delays are milliseconds, matching the Node.js SDK."""
+
+    max_retries: int = Field(default=3, ge=0, le=50, alias="maxRetries")
+    base_delay: int = Field(default=200, ge=0, alias="baseDelay")
+    max_delay: int = Field(default=10_000, ge=0, alias="maxDelay")
+    retryable_status_codes: List[int] = Field(
+        default_factory=lambda: [408, 429, 500, 502, 503, 504],
+        alias="retryableStatusCodes",
+    )
+
+    @model_validator(mode="after")
+    def _delays(self) -> "RetryConfig":
+        if self.max_delay < self.base_delay:
+            raise ValueError("max_delay must be greater than or equal to base_delay")
+        return self
+
+
+class S3Credentials(_Model):
+    access_key_id: str = Field(min_length=1, alias="accessKeyId")
+    secret_access_key: str = Field(min_length=1, alias="secretAccessKey")
+    region: str = Field(min_length=1)
+    bucket: str = Field(min_length=1)
+    endpoint: Optional[str] = None
+    force_path_style: Optional[bool] = Field(default=None, alias="forcePathStyle")
+    session_token: Optional[str] = Field(default=None, alias="sessionToken")
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class R2Credentials(_Model):
+    account_id: str = Field(min_length=1, alias="accountId")
+    access_key_id: str = Field(min_length=1, alias="accessKeyId")
+    secret_access_key: str = Field(min_length=1, alias="secretAccessKey")
+    bucket: str = Field(min_length=1)
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class GCSServiceAccount(_Model):
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    client_email: str = Field(min_length=1)
+    private_key: str = Field(min_length=1)
+
+
+class GCSCredentials(_Model):
+    project_id: str = Field(min_length=1, alias="projectId")
+    bucket: str = Field(min_length=1)
+    key_filename: Optional[str] = Field(default=None, alias="keyFilename")
+    credentials: Optional[GCSServiceAccount] = None
+    service_account: Optional[Dict[str, Any]] = Field(default=None, alias="serviceAccount")
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+    @field_validator("credentials", mode="before")
+    @classmethod
+    def _coerce_credentials(cls, value: Any) -> Any:
+        if isinstance(value, dict) and "client_email" in value:
+            return value
+        return value
+
+
+class AzureCredentials(_Model):
+    account_name: str = Field(min_length=1, alias="accountName")
+    container_name: str = Field(min_length=1, alias="containerName")
+    account_key: Optional[str] = Field(default=None, alias="accountKey")
+    connection_string: Optional[str] = Field(default=None, alias="connectionString")
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+    @model_validator(mode="after")
+    def _auth(self) -> "AzureCredentials":
+        if not self.account_key and not self.connection_string:
+            raise ValueError("Provide account_key or connection_string")
+        return self
+
+
+class SpacesCredentials(_Model):
+    access_key_id: str = Field(min_length=1, alias="accessKeyId")
+    secret_access_key: str = Field(min_length=1, alias="secretAccessKey")
+    region: str = Field(min_length=1)
+    bucket: str = Field(min_length=1)
+    endpoint: Optional[str] = None
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class B2Credentials(_Model):
+    application_key_id: str = Field(min_length=1, alias="applicationKeyId")
+    application_key: str = Field(min_length=1, alias="applicationKey")
+    bucket: str = Field(min_length=1)
+    endpoint: Optional[str] = None
+    region: Optional[str] = "us-west-004"
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class MinIOCredentials(_Model):
+    end_point: str = Field(min_length=1, alias="endPoint")
+    access_key: str = Field(min_length=1, alias="accessKey")
+    secret_key: str = Field(min_length=1, alias="secretKey")
+    bucket: str = Field(min_length=1)
+    port: Optional[int] = Field(default=9000, ge=1, le=65535)
+    use_ssl: bool = Field(default=True, alias="useSSL")
+    region: Optional[str] = "us-east-1"
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class SupabaseCredentials(_Model):
+    url: str = Field(min_length=1)
+    service_role_key: str = Field(min_length=1, alias="serviceRoleKey")
+    bucket: str = Field(min_length=1)
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+    @field_validator("url")
+    @classmethod
+    def _url(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://")):
+            raise ValueError("url must start with http:// or https://")
+        return value.rstrip("/")
+
+
+class FirebaseCredentials(_Model):
+    project_id: str = Field(min_length=1, alias="projectId")
+    bucket: str = Field(min_length=1)
+    service_account: Optional[Dict[str, Any]] = Field(default=None, alias="serviceAccount")
+    key_filename: Optional[str] = Field(default=None, alias="keyFilename")
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+
+class AppwriteCredentials(_Model):
+    endpoint: str = Field(min_length=1)
+    project_id: str = Field(min_length=1, alias="projectId")
+    api_key: str = Field(min_length=1, alias="apiKey")
+    bucket_id: str = Field(min_length=1, alias="bucketId")
+    cdn_url: Optional[str] = Field(default=None, alias="cdnUrl")
+    custom_domain: Optional[str] = Field(default=None, alias="customDomain")
+
+    @field_validator("endpoint")
+    @classmethod
+    def _endpoint(cls, value: str) -> str:
+        if not value.startswith(("http://", "https://")):
+            raise ValueError("endpoint must start with http:// or https://")
+        return value.rstrip("/")
+
+
+class _Shared(_Model):
+    visibility: Visibility = Visibility.PRIVATE
+    retry: RetryConfig = Field(default_factory=RetryConfig)
+    log_level: LogLevel = Field(default=LogLevel.WARN, alias="logLevel")
+
+
+class S3Config(_Shared):
+    provider: Literal["s3"] = "s3"
+    credentials: S3Credentials
+
+
+class R2Config(_Shared):
+    provider: Literal["r2"] = "r2"
+    credentials: R2Credentials
+
+
+class GCSConfig(_Shared):
+    provider: Literal["gcs"] = "gcs"
+    credentials: GCSCredentials
+
+
+class AzureConfig(_Shared):
+    provider: Literal["azure"] = "azure"
+    credentials: AzureCredentials
+
+
+class SpacesConfig(_Shared):
+    provider: Literal["spaces"] = "spaces"
+    credentials: SpacesCredentials
+
+
+class B2Config(_Shared):
+    provider: Literal["b2"] = "b2"
+    credentials: B2Credentials
+
+
+class MinIOConfig(_Shared):
+    provider: Literal["minio"] = "minio"
+    credentials: MinIOCredentials
+
+
+class SupabaseConfig(_Shared):
+    provider: Literal["supabase"] = "supabase"
+    credentials: SupabaseCredentials
+
+
+class FirebaseConfig(_Shared):
+    provider: Literal["firebase"] = "firebase"
+    credentials: FirebaseCredentials
+
+
+class AppwriteConfig(_Shared):
+    provider: Literal["appwrite"] = "appwrite"
+    credentials: AppwriteCredentials
+
+
+StorageConfig = Annotated[
+    Union[
+        S3Config,
+        R2Config,
+        GCSConfig,
+        AzureConfig,
+        SpacesConfig,
+        B2Config,
+        MinIOConfig,
+        SupabaseConfig,
+        FirebaseConfig,
+        AppwriteConfig,
+    ],
+    Field(discriminator="provider"),
+]
+
+_STORAGE_CONFIG_ADAPTER: TypeAdapter[StorageConfig] = TypeAdapter(StorageConfig)
+
+PROVIDERS = (
+    "s3",
+    "r2",
+    "gcs",
+    "azure",
+    "spaces",
+    "b2",
+    "minio",
+    "supabase",
+    "firebase",
+    "appwrite",
+)
+
+
+def parse_storage_config(data: Any) -> StorageConfig:
+    """Validate a dict or model into a discriminated StorageConfig."""
+    if isinstance(data, _Shared) and hasattr(data, "provider"):
+        return data  # type: ignore[return-value]
+    try:
+        return _STORAGE_CONFIG_ADAPTER.validate_python(data)
+    except PydanticValidationError as exc:
+        raise ValidationError(_format_pydantic(exc)) from exc
+
+
+def _format_pydantic(exc: PydanticValidationError) -> str:
+    parts = []
+    for err in exc.errors():
+        loc = ".".join(str(item) for item in err.get("loc", ()))
+        parts.append(f"{loc}: {err.get('msg')}" if loc else str(err.get("msg")))
+    return "Invalid storage configuration: " + "; ".join(parts)