10x-cloud-storage-manager 0.2.0__py3-none-any.whl

10x_cloud_storage_manager-0.2.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: 10x-cloud-storage-manager
+Version: 0.2.0
+Summary: A unified async interface for AWS S3, Google Cloud Storage and Azure Blob Storage
+Author-email: MUTHARASU A <mutharasu39@gmail.com>
+License: MIT License  
+        
+        Copyright (c) 2024 MUTHARASU  a
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/10xHub/cloud-storage-manager
+Project-URL: Bug Tracker, https://github.com/10xHub/cloud-storage-manager/issues
+Keywords: aws,s3,gcp,azure,blob,cloud storage,file upload,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aioboto3>=11.0.0
+Requires-Dist: google-cloud-storage>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: aws
+Requires-Dist: aioboto3>=11.0.0; extra == "aws"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-storage>=2.0.0; extra == "gcp"
+Provides-Extra: azure
+Requires-Dist: azure-storage-blob>=12.19.0; extra == "azure"
+Requires-Dist: aiohttp>=3.8.0; extra == "azure"
+Provides-Extra: all
+Requires-Dist: 10x-cloud-storage-manager[aws,azure,gcp]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: 10x-cloud-storage-manager[all]; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: packaging>=23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# Cloud Storage Manager
+
+One async interface over AWS S3, Google Cloud Storage and Azure Blob Storage. Application code
+calls the same methods everywhere; switching cloud is a configuration change.
+
+## Features
+
+- One interface for AWS S3, Google Cloud Storage and Azure Blob Storage
+- Async operations
+- Upload from a file or from bytes, download, list, delete, signed read URLs
+- `upload_bytes` stores a content type, so a signed video URL plays in a browser
+- Type-safe configuration using Pydantic
+- A drop-in upgrade from 0.1.x (see below)
+
+## Installation
+
+The base install covers AWS S3 and Google Cloud Storage, as 0.1.x did. Azure is an extra:
+
+```bash
+pip install 10x-cloud-storage-manager           # AWS S3 + Google Cloud Storage
+pip install "10x-cloud-storage-manager[azure]"  # adds Azure Blob Storage
+pip install "10x-cloud-storage-manager[all]"    # all three
+```
+
+The import name is still `cloud_storage_manager`. From 0.2.0 the package is published as
+`10x-cloud-storage-manager`; `cloud-storage-manager` on PyPI stops at 0.1.2.
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+import asyncio
+from cloud_storage_manager import CloudStorageFactory, StorageConfig
+
+
+async def main(config: StorageConfig):
+    storage = CloudStorageFactory.from_config(config)
+
+    await storage.upload("local/clip.mp4", "recordings/clip.mp4")
+    await storage.upload_bytes(b"# Notes", "notes/a.md", content_type="text/markdown")
+
+    data = await storage.download_bytes("notes/a.md")
+    names = await storage.list_objects("recordings/")
+    sizes = await storage.list_object_sizes("recordings/")  # {name: bytes}
+
+    url = await storage.get_public_url("recordings/clip.mp4", expiration=3600)
+
+    deleted = await storage.delete_if_exists("notes/a.md")  # False if it was already gone
+```
+
+`CloudStorageFactory.from_config` picks the provider from the config.
+`CloudStorageFactory.get_storage(StorageProvider.GCP, config)` still works.
+
+## Configuration
+
+`CloudStorageFactory.get_storage(provider, config)` uses the provider you name, so a config may
+hold more than one. `config.provider` and `from_config` infer it, and raise `ValueError` unless
+exactly one is set.
+
+### AWS S3
+
+```python
+from cloud_storage_manager import AwsConfig, StorageConfig
+
+config = StorageConfig(
+    aws=AwsConfig(
+        bucket_name="my-bucket",
+        access_key_id="...",
+        secret_access_key="...",
+        region="us-east-1",  # stored but not used; boto resolves the region, as in 0.1.x
+    )
+)
+```
+
+### Google Cloud Storage
+
+```python
+from cloud_storage_manager import GcpConfig, StorageConfig
+
+config = StorageConfig(
+    gcp=GcpConfig(
+        bucket_name="my-bucket",
+        project_id="my-project",
+        credentials={...},  # service account JSON as a dict
+    )
+)
+```
+
+### Azure Blob Storage
+
+Give exactly one of `account_key` or `connection_string`.
+
+```python
+from cloud_storage_manager import AzureConfig, StorageConfig
+
+config = StorageConfig(
+    azure=AzureConfig(
+        account_name="mystorageaccount",
+        container_name="my-container",
+        account_key="...",
+        # or: connection_string="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;"
+    )
+)
+```
+
+`get_public_url` on Azure returns a read-only blob SAS URL, signed with the account key. A
+connection string that carries a SAS instead of an `AccountKey` can read and write but cannot
+sign URLs.
+
+## Interface
+
+Every provider implements `BaseCloudStorage`:
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `upload(file_path, cloud_path)` | `str` | GCP and Azure type the object from its file name; S3 does not (0.1.x behaviour) |
+| `upload_bytes(data, cloud_path, content_type=None)` | `str` | Content type guessed from `cloud_path` when omitted |
+| `download_bytes(cloud_path)` | `bytes` | `NotFoundError` if missing |
+| `list_objects(prefix)` | `list[str]` | Every page |
+| `list_object_sizes(prefix)` | `dict[str, int]` | Name to size in bytes |
+| `delete(cloud_path)` | `bool` | 0.1.x behaviour: a missing object raises `DeleteError` on GCP and Azure, returns `True` on S3 |
+| `delete_if_exists(cloud_path)` | `bool` | `False` if it did not exist, on every cloud |
+| `get_public_url(cloud_path, expiration=3600)` | `str` | Signed, read-only, expires after `expiration` seconds |
+
+## Error handling
+
+Every error is a `CloudStorageError`: `UploadError`, `DownloadError`, `NotFoundError`,
+`ListError`, `DeleteError`. The SDK's own exception is kept as `__cause__`.
+
+```python
+from cloud_storage_manager import NotFoundError
+
+try:
+    data = await storage.download_bytes("missing.txt")
+except NotFoundError:
+    data = None
+```
+
+## Upgrading from 0.1.x
+
+Change only the requirement: swap `cloud-storage-manager` for `10x-cloud-storage-manager`
+(uninstall the old package first, since both ship the `cloud_storage_manager` module). Your code
+does not change: every 0.1.x call behaves as before.
+
+```bash
+pip uninstall -y cloud-storage-manager
+pip install 10x-cloud-storage-manager
+```
+
+- The base install pulls the same packages as 0.1.x; Azure is the `[azure]` extra.
+- `StorageConfig` accepts every combination 0.1.x accepted.
+- `upload`, `delete` and `get_public_url` behave as in 0.1.x on S3 and GCP; the new
+  `delete_if_exists` is the one to use for the same answer on every cloud.
+- Only those three methods are abstract, so a subclass written for 0.1.x still instantiates.
+- `AWSClientStorage` and `GcpClientStorage` are still importable from
+  `cloud_storage_manager.storage_provider`.
+- Python 3.10+ (0.1.x already used 3.10 syntax and did not import on 3.8 or 3.9).
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest --cov
+ruff check . && ruff format --check .
+```
+
+Tests mock every cloud SDK and never call a real cloud.
+
+### Branches and releases
+
+- `dev` is the default branch. Open feature PRs against it.
+- `prod` is the release branch. **Every merge into `prod` publishes to PyPI** and creates a
+  `v<version>` GitHub release (`.github/workflows/release.yml`).
+- Bump `[project].version` in `pyproject.toml` in the PR to `prod`. CI fails the PR if PyPI
+  already has that version.
+- Publishing uses the `PYPI_API_TOKEN` secret on the `pypi` GitHub environment, which only
+  the `prod` branch can deploy to. Never upload to PyPI by hand.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

10x_cloud_storage_manager-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+10x_cloud_storage_manager-0.2.0.dist-info/licenses/LICENSE,sha256=Xg5xEpG9i8MQHOAPZJ-GDeHZAf3bgHFhmH473ao_HLk,1107
+cloud_storage_manager/__init__.py,sha256=6oe09IdqmjiBJvTtzpl_TTuPdtMuYxDU9il_PlPOI4Q,767
+cloud_storage_manager/_distribution.py,sha256=KfllOA7XManYfmIIbP41lTIppW5k895gDD_eBelWhZg,280
+cloud_storage_manager/aws_s3_storage.py,sha256=ecuhZK1SjmcXWUwg0Nb_lE5P4jF9VZ6HQ2MLfQWC_-U,8045
+cloud_storage_manager/azure_storage.py,sha256=N0FFL70AQm9jLlOqxdSZzUwDLvEfguDeHOYPdfjO7kI,8106
+cloud_storage_manager/base_storage.py,sha256=eGt_bab8CWIwBOiHPc4Y4AG7Hi_kQNqHUvdWV7AskRE,5101
+cloud_storage_manager/exceptions.py,sha256=bm-0yM86SXLFjzXahdgd7hj8G7Ori1SDOoZbycWloH0,597
+cloud_storage_manager/gcp_storage.py,sha256=nPO6IPX9yf4cyDzKtX2b_Tu_tbYRsyN-bS-MXJd5rto,9019
+cloud_storage_manager/storage_provider.py,sha256=g6u5ppbrTqBY5t2o8VNwES3wPkdaVDd-WbmfXoL0vbc,2856
+cloud_storage_manager/storage_schema.py,sha256=--cMVQpYswsSnnBWYxOWGnY_GZ_X5AxFLCatV2oktNE,2859
+10x_cloud_storage_manager-0.2.0.dist-info/METADATA,sha256=q4e4TCuTOW8wBAg20UAK3GUc9mZ9bVspxLG9FTbzIBQ,9520
+10x_cloud_storage_manager-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+10x_cloud_storage_manager-0.2.0.dist-info/top_level.txt,sha256=NulGei6qRmnP61OgHE8wIilOcm2XMPiRJuZ35W_lQd0,22
+10x_cloud_storage_manager-0.2.0.dist-info/RECORD,,

10x_cloud_storage_manager-0.2.0.dist-info/WHEEL

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

10x_cloud_storage_manager-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License  
+
+Copyright (c) 2024 MUTHARASU  a
+
+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.

10x_cloud_storage_manager-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cloud_storage_manager

cloud_storage_manager/__init__.py

@@ -0,0 +1,38 @@
+"""
+Cloud Storage Manager Package
+"""
+
+import logging
+
+from .base_storage import BaseCloudStorage
+from .exceptions import (
+    AuthorizationError,
+    CloudStorageError,
+    DeleteError,
+    DownloadError,
+    ListError,
+    NotFoundError,
+    UploadError,
+)
+from .storage_provider import CloudStorageFactory
+from .storage_schema import AwsConfig, AzureConfig, GcpConfig, StorageConfig, StorageProvider
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "AuthorizationError",
+    "AwsConfig",
+    "AzureConfig",
+    "BaseCloudStorage",
+    "CloudStorageError",
+    "CloudStorageFactory",
+    "DeleteError",
+    "DownloadError",
+    "GcpConfig",
+    "ListError",
+    "NotFoundError",
+    "StorageConfig",
+    "StorageProvider",
+    "UploadError",
+    "logger",
+]

cloud_storage_manager/_distribution.py

@@ -0,0 +1,4 @@
+# The PyPI name differs from the import name: 0.1.x shipped as `cloud-storage-manager` from an
+# account that can no longer publish, so 0.2.0 onwards ships under this name. Keep it in sync
+# with `[project].name` in pyproject.toml.
+DISTRIBUTION_NAME = "10x-cloud-storage-manager"

cloud_storage_manager/aws_s3_storage.py

@@ -0,0 +1,168 @@
+from pathlib import Path
+
+import aioboto3
+from botocore.exceptions import ClientError
+
+from . import logger
+from .base_storage import BaseCloudStorage, guess_content_type
+from .exceptions import DeleteError, DownloadError, ListError, NotFoundError, UploadError
+from .storage_schema import StorageConfig
+
+_MISSING_CODES = {"404", "NoSuchKey", "NotFound"}
+
+
+def _is_missing(error: ClientError) -> bool:
+    return error.response.get("Error", {}).get("Code") in _MISSING_CODES
+
+
+class AWSClientStorage(BaseCloudStorage):
+    """
+    AWSClientStorage is a class for interacting with AWS S3 storage.
+    It implements every BaseCloudStorage operation against one S3 bucket.
+    Attributes:
+        session (aioboto3.Session): The boto3 session for AWS S3 interactions.
+        bucket (str): The name of the S3 bucket.
+    """
+
+    def __init__(self, config: StorageConfig):
+        """Initialize AWS S3 storage client.
+
+        Args:
+            config (StorageConfig): Configuration containing AWS credentials and settings
+                Must include aws.access_key_id, aws.secret_access_key, and aws.bucket_name
+
+        Raises:
+            ValueError: If AWS configuration is missing
+        """
+        if not config.aws:
+            raise ValueError("AWS configuration is required")
+        super().__init__(config)
+        # `region` is deliberately not passed: 0.1.x let boto resolve the region from the
+        # environment, and forcing the field's us-east-1 default would re-sign callers' URLs.
+        self.session = aioboto3.Session(
+            aws_access_key_id=config.aws.access_key_id,
+            aws_secret_access_key=config.aws.secret_access_key,
+        )
+        self.bucket = config.aws.bucket_name
+        logger.info(f"AWSClientStorage initialized with bucket: {self.bucket}")
+
+    async def upload(self, file_path: Path | str, cloud_path: str) -> str:
+        """Upload a local file to the S3 bucket; returns the S3 object path."""
+        logger.info(f"Starting upload of {file_path} to s3://{self.bucket}/{cloud_path}")
+        return await self.upload_file(file_path, cloud_path)
+
+    async def upload_bytes(
+        self, data: bytes, cloud_path: str, content_type: str | None = None
+    ) -> str:
+        """Upload in-memory bytes to the S3 bucket; returns the S3 object path."""
+        logger.info(f"Uploading {len(data)} bytes to s3://{self.bucket}/{cloud_path}")
+        content_type = content_type or guess_content_type(cloud_path)
+        extra = {"ContentType": content_type} if content_type else {}
+        async with self.session.client("s3") as s3:
+            try:
+                await s3.put_object(Bucket=self.bucket, Key=cloud_path, Body=data, **extra)
+                return cloud_path
+            except Exception as e:
+                logger.error(f"Upload failed: {e}")
+                raise UploadError(f"Failed to upload bytes to S3: {e}") from e
+
+    async def download_bytes(self, cloud_path: str) -> bytes:
+        """Download the S3 object's content."""
+        logger.info(f"Downloading s3://{self.bucket}/{cloud_path}")
+        async with self.session.client("s3") as s3:
+            try:
+                response = await s3.get_object(Bucket=self.bucket, Key=cloud_path)
+                async with response["Body"] as body:
+                    return await body.read()
+            except ClientError as e:
+                if _is_missing(e):
+                    raise NotFoundError(f"S3 object not found: {cloud_path}") from e
+                logger.error(f"Download failed: {e}")
+                raise DownloadError(f"Failed to download file from S3: {e}") from e
+            except Exception as e:
+                logger.error(f"Download failed: {e}")
+                raise DownloadError(f"Failed to download file from S3: {e}") from e
+
+    async def list_objects(self, prefix: str) -> list[str]:
+        """List S3 object keys under `prefix`."""
+        return list(await self.list_object_sizes(prefix))
+
+    async def list_object_sizes(self, prefix: str) -> dict[str, int]:
+        """S3 object key -> size in bytes under `prefix`."""
+        logger.info(f"Listing s3://{self.bucket}/{prefix}")
+        async with self.session.client("s3") as s3:
+            try:
+                sizes: dict[str, int] = {}
+                paginator = s3.get_paginator("list_objects_v2")
+                async for page in paginator.paginate(Bucket=self.bucket, Prefix=prefix):
+                    for item in page.get("Contents", []):
+                        sizes[item["Key"]] = item.get("Size", 0)
+                return sizes
+            except Exception as e:
+                logger.error(f"Listing failed: {e}")
+                raise ListError(f"Failed to list objects in S3: {e}") from e
+
+    async def delete(self, cloud_path: str) -> bool:
+        """Delete a file from the S3 bucket; True even for a missing key, as S3 answers."""
+        logger.info(f"Deleting s3://{self.bucket}/{cloud_path}")
+        return await self.delete_file(cloud_path)
+
+    async def delete_if_exists(self, cloud_path: str) -> bool:
+        """Delete an S3 object; False when it did not exist."""
+        logger.info(f"Deleting s3://{self.bucket}/{cloud_path} if it exists")
+        async with self.session.client("s3") as s3:
+            try:
+                # S3 deletes a missing key without complaint, so existence is checked first.
+                await s3.head_object(Bucket=self.bucket, Key=cloud_path)
+            except ClientError as e:
+                if _is_missing(e):
+                    return False
+                logger.error(f"Deletion failed: {e}")
+                raise DeleteError(f"Failed to delete file from S3: {e}") from e
+            except Exception as e:
+                logger.error(f"Deletion failed: {e}")
+                raise DeleteError(f"Failed to delete file from S3: {e}") from e
+        return await self.delete_file(cloud_path)
+
+    async def get_public_url(self, cloud_path: str, expiration: int = 3600) -> str:
+        """Generate a pre-signed GET URL for a private S3 object."""
+        logger.info(f"Generating pre-signed URL for s3://{self.bucket}/{cloud_path}")
+        async with self.session.client("s3") as s3:
+            try:
+                url = await s3.generate_presigned_url(
+                    "get_object",
+                    Params={"Bucket": self.bucket, "Key": cloud_path},
+                    ExpiresIn=expiration,
+                )
+                logger.debug(f"Generated pre-signed URL (expires in {expiration}s)")
+                return url
+            except Exception as e:
+                logger.error(f"Failed to generate pre-signed URL: {e}")
+                raise DownloadError(f"Failed to generate pre-signed URL: {e}") from e
+
+    # Helper methods
+    async def upload_file(self, file_path: Path | str, cloud_path: str) -> str:
+        """Internal method to handle file upload to S3.
+
+        No ContentType is sent, as in 0.1.x, so objects keep the type S3 assigned them before.
+        """
+        async with self.session.client("s3") as s3:
+            try:
+                with Path(file_path).open("rb") as file_obj:
+                    await s3.upload_fileobj(file_obj, self.bucket, cloud_path)
+                    logger.debug(f"Successfully uploaded to s3://{self.bucket}/{cloud_path}")
+                return cloud_path
+            except Exception as e:
+                logger.error(f"Upload failed: {e}")
+                raise UploadError(f"Failed to upload file to S3: {e}") from e
+
+    async def delete_file(self, cloud_path: str) -> bool:
+        """Internal method to handle file deletion from S3."""
+        async with self.session.client("s3") as s3:
+            try:
+                await s3.delete_object(Bucket=self.bucket, Key=cloud_path)
+                logger.debug(f"Successfully deleted s3://{self.bucket}/{cloud_path}")
+                return True
+            except Exception as e:
+                logger.error(f"Deletion failed: {e}")
+                raise DeleteError(f"Failed to delete file from S3: {e}") from e

cloud_storage_manager/azure_storage.py

@@ -0,0 +1,169 @@
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from azure.core.exceptions import ResourceNotFoundError
+from azure.storage.blob import BlobSasPermissions, ContentSettings, generate_blob_sas
+from azure.storage.blob.aio import BlobServiceClient
+
+from . import logger
+from .base_storage import BaseCloudStorage, guess_content_type
+from .exceptions import DeleteError, DownloadError, ListError, NotFoundError, UploadError
+from .storage_schema import StorageConfig
+
+
+def _connection_string_key(connection_string: str) -> str | None:
+    """The AccountKey inside a connection string; None for a SAS-only one."""
+    parts = dict(part.split("=", 1) for part in connection_string.split(";") if "=" in part)
+    return {k.lower(): v for k, v in parts.items()}.get("accountkey")
+
+
+def _content_settings(content_type: str | None) -> dict:
+    # Untyped blobs are served as octet-stream, which browsers download instead of playing.
+    return {"content_settings": ContentSettings(content_type=content_type)} if content_type else {}
+
+
+class AzureBlobStorage(BaseCloudStorage):
+    """Azure Blob Storage client implementation.
+
+    Implements every BaseCloudStorage operation against one blob container, using the
+    async SDK. Signed URLs are read-only blob SAS tokens signed with the account key.
+
+    Attributes:
+        account_name (str): Storage account name.
+        container_name (str): Blob container name.
+    """
+
+    def __init__(self, config: StorageConfig):
+        """Initialize Azure Blob storage client.
+
+        Args:
+            config: Configuration object containing azure.account_name,
+                azure.container_name and one of azure.account_key / azure.connection_string.
+
+        Raises:
+            ValueError: If Azure configuration is missing from config.
+        """
+        if not config.azure:
+            raise ValueError("Azure configuration is required")
+        super().__init__(config)
+        self.account_name = config.azure.account_name
+        self.container_name = config.azure.container_name
+        self._connection_string = config.azure.connection_string
+        self._account_key = config.azure.account_key or _connection_string_key(
+            config.azure.connection_string or ""
+        )
+        logger.info(f"AzureBlobStorage initialized with container: {self.container_name}")
+
+    def _service_client(self) -> BlobServiceClient:
+        if self._connection_string:
+            return BlobServiceClient.from_connection_string(self._connection_string)
+        return BlobServiceClient(
+            account_url=f"https://{self.account_name}.blob.core.windows.net",
+            credential=self._account_key,
+        )
+
+    async def upload(self, file_path: Path | str, cloud_path: str) -> str:
+        """Upload a local file to the container; returns the blob path."""
+        logger.info(f"Starting upload of {file_path} to azure://{self.container_name}/{cloud_path}")
+        settings = _content_settings(guess_content_type(file_path))
+        try:
+            async with self._service_client() as client:
+                blob = client.get_blob_client(self.container_name, cloud_path)
+                with Path(file_path).open("rb") as file_obj:
+                    await blob.upload_blob(file_obj, overwrite=True, **settings)
+            return cloud_path
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            raise UploadError(f"Failed to upload file to Azure: {e}") from e
+
+    async def upload_bytes(
+        self, data: bytes, cloud_path: str, content_type: str | None = None
+    ) -> str:
+        """Upload in-memory bytes to the container; returns the blob path."""
+        logger.info(f"Uploading {len(data)} bytes to azure://{self.container_name}/{cloud_path}")
+        settings = _content_settings(content_type or guess_content_type(cloud_path))
+        try:
+            async with self._service_client() as client:
+                blob = client.get_blob_client(self.container_name, cloud_path)
+                await blob.upload_blob(data, overwrite=True, **settings)
+            return cloud_path
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            raise UploadError(f"Failed to upload bytes to Azure: {e}") from e
+
+    async def download_bytes(self, cloud_path: str) -> bytes:
+        """Download the blob's content."""
+        logger.info(f"Downloading azure://{self.container_name}/{cloud_path}")
+        try:
+            async with self._service_client() as client:
+                blob = client.get_blob_client(self.container_name, cloud_path)
+                downloader = await blob.download_blob()
+                return await downloader.readall()
+        except ResourceNotFoundError as e:
+            raise NotFoundError(f"Azure blob not found: {cloud_path}") from e
+        except Exception as e:
+            logger.error(f"Download failed: {e}")
+            raise DownloadError(f"Failed to download blob from Azure: {e}") from e
+
+    async def list_objects(self, prefix: str) -> list[str]:
+        """List blob names under `prefix`."""
+        return list(await self.list_object_sizes(prefix))
+
+    async def list_object_sizes(self, prefix: str) -> dict[str, int]:
+        """Blob name -> size in bytes under `prefix`."""
+        logger.info(f"Listing azure://{self.container_name}/{prefix}")
+        try:
+            async with self._service_client() as client:
+                container = client.get_container_client(self.container_name)
+                return {
+                    b.name: b.size or 0
+                    async for b in container.list_blobs(name_starts_with=prefix or None)
+                }
+        except Exception as e:
+            logger.error(f"Listing failed: {e}")
+            raise ListError(f"Failed to list blobs in Azure: {e}") from e
+
+    async def delete(self, cloud_path: str) -> bool:
+        """Delete a blob; a missing blob raises DeleteError, as GCP's delete does."""
+        if not await self.delete_if_exists(cloud_path):
+            raise DeleteError(f"Failed to delete blob from Azure: {cloud_path} does not exist")
+        return True
+
+    async def delete_if_exists(self, cloud_path: str) -> bool:
+        """Delete a blob; False when it did not exist."""
+        logger.info(f"Deleting azure://{self.container_name}/{cloud_path} if it exists")
+        try:
+            async with self._service_client() as client:
+                await client.get_blob_client(self.container_name, cloud_path).delete_blob()
+            return True
+        except ResourceNotFoundError:
+            return False
+        except Exception as e:
+            logger.error(f"Deletion failed: {e}")
+            raise DeleteError(f"Failed to delete blob from Azure: {e}") from e
+
+    async def get_public_url(self, cloud_path: str, expiration: int = 3600) -> str:
+        """Generate a read-only SAS URL for the blob, valid for `expiration` seconds.
+
+        The SAS does not override the response Content-Type, so the browser receives the
+        type stored at upload.
+        """
+        logger.info(f"Generating SAS URL for azure://{self.container_name}/{cloud_path}")
+        if not self._account_key:
+            raise DownloadError("Azure SAS signing needs an account key in the configuration")
+        try:
+            sas = generate_blob_sas(
+                account_name=self.account_name,
+                container_name=self.container_name,
+                blob_name=cloud_path,
+                account_key=self._account_key,
+                permission=BlobSasPermissions(read=True),
+                expiry=datetime.now(timezone.utc) + timedelta(seconds=expiration),
+            )
+            async with self._service_client() as client:
+                blob_url = client.get_blob_client(self.container_name, cloud_path).url
+            logger.debug(f"Generated SAS URL (expires in {expiration}s)")
+            return f"{blob_url}?{sas}"
+        except Exception as e:
+            logger.error(f"Failed to generate SAS URL: {e}")
+            raise DownloadError(f"Failed to generate SAS URL: {e}") from e

cloud_storage_manager/base_storage.py

@@ -0,0 +1,156 @@
+import mimetypes
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .storage_schema import StorageConfig
+
+
+def guess_content_type(path: Path | str) -> str | None:
+    """Content type from a file name's extension, or None when it is unknown."""
+    return mimetypes.guess_type(str(path))[0]
+
+
+class BaseCloudStorage(ABC):
+    """Abstract base class for cloud storage operations.
+
+    Only the three 0.1.x operations (upload, delete, get_public_url) are abstract, so a
+    subclass written against 0.1.x still instantiates. The operations added in 0.2.0 raise
+    NotImplementedError until a subclass provides them; every built-in provider does.
+
+    Attributes:
+        config (StorageConfig): Configuration object for the cloud storage.
+    """
+
+    def __init__(self, config: StorageConfig):
+        """Initialize the cloud storage interface.
+
+        Args:
+            config (StorageConfig): Configuration object for the cloud storage.
+        """
+        self.config = config
+
+    def _unsupported(self, operation: str) -> NotImplementedError:
+        return NotImplementedError(f"{type(self).__name__} does not implement {operation}")
+
+    @abstractmethod
+    async def upload(self, file_path: Path | str, cloud_path: str) -> str:
+        """Upload a local file to cloud storage.
+
+        Args:
+            file_path (Path | str): Local path to the file to be uploaded.
+            cloud_path (str): Destination path in cloud storage.
+
+        Returns:
+            str: The path of the uploaded file in cloud storage.
+
+        Raises:
+            UploadError: If the upload fails.
+        """
+
+    async def upload_bytes(
+        self, data: bytes, cloud_path: str, content_type: str | None = None
+    ) -> str:
+        """Upload in-memory bytes to cloud storage.
+
+        Args:
+            data (bytes): The object's content.
+            cloud_path (str): Destination path in cloud storage.
+            content_type (str | None): Stored content type; guessed from cloud_path when None.
+
+        Returns:
+            str: The path of the uploaded object in cloud storage.
+
+        Raises:
+            UploadError: If the upload fails.
+        """
+        raise self._unsupported("upload_bytes")
+
+    async def download_bytes(self, cloud_path: str) -> bytes:
+        """Download an object's content.
+
+        Args:
+            cloud_path (str): Path to the object in cloud storage.
+
+        Returns:
+            bytes: The object's content.
+
+        Raises:
+            NotFoundError: If the object does not exist.
+            DownloadError: If the download fails for any other reason.
+        """
+        raise self._unsupported("download_bytes")
+
+    async def list_objects(self, prefix: str) -> list[str]:
+        """List the names of every object under a prefix.
+
+        Args:
+            prefix (str): Path prefix; an empty string lists the whole bucket.
+
+        Returns:
+            list[str]: Object names, across every page of the listing.
+
+        Raises:
+            ListError: If the listing fails.
+        """
+        raise self._unsupported("list_objects")
+
+    async def list_object_sizes(self, prefix: str) -> dict[str, int]:
+        """Map every object under a prefix to its size in bytes.
+
+        Args:
+            prefix (str): Path prefix; an empty string lists the whole bucket.
+
+        Returns:
+            dict[str, int]: Object name to size in bytes.
+
+        Raises:
+            ListError: If the listing fails.
+        """
+        raise self._unsupported("list_object_sizes")
+
+    @abstractmethod
+    async def delete(self, cloud_path: str) -> bool:
+        """Delete a file from cloud storage, as 0.1.x did.
+
+        A missing object gets each cloud's own answer, unchanged since 0.1.x: GCP and Azure
+        raise DeleteError, S3 deletes nothing and returns True. delete_if_exists gives the
+        same answer on every cloud.
+
+        Args:
+            cloud_path (str): Path to the file in cloud storage to be deleted.
+
+        Returns:
+            bool: True once the delete request succeeded.
+
+        Raises:
+            DeleteError: If the deletion fails.
+        """
+
+    async def delete_if_exists(self, cloud_path: str) -> bool:
+        """Delete an object, reporting whether it was there, the same way on every cloud.
+
+        Args:
+            cloud_path (str): Path to the object in cloud storage.
+
+        Returns:
+            bool: True if the object was deleted, False if it did not exist.
+
+        Raises:
+            DeleteError: If the deletion fails for any other reason.
+        """
+        raise self._unsupported("delete_if_exists")
+
+    @abstractmethod
+    async def get_public_url(self, cloud_path: str, expiration: int = 3600) -> str:
+        """Generate a time-limited, read-only signed URL for the file.
+
+        Args:
+            cloud_path (str): Path to the file in cloud storage.
+            expiration (int, optional): URL expiration time in seconds. Defaults to 3600.
+
+        Returns:
+            str: Signed URL for reading the file.
+
+        Raises:
+            DownloadError: If URL generation fails.
+        """

cloud_storage_manager/exceptions.py

@@ -0,0 +1,26 @@
+class CloudStorageError(Exception):
+    """Base exception for cloud storage operations"""
+
+
+class UploadError(CloudStorageError):
+    """Error occurred during file upload"""
+
+
+class DeleteError(CloudStorageError):
+    """Error occurred during file deletion"""
+
+
+class DownloadError(CloudStorageError):
+    """Error occurred during file download"""
+
+
+class NotFoundError(CloudStorageError):
+    """Resource not found"""
+
+
+class AuthorizationError(CloudStorageError):
+    """Authorization/Authentication failed"""
+
+
+class ListError(CloudStorageError):
+    """Error occurred while listing objects"""

cloud_storage_manager/gcp_storage.py

@@ -0,0 +1,226 @@
+import asyncio
+from pathlib import Path
+
+from google.cloud import storage
+from google.cloud.exceptions import NotFound
+from google.oauth2 import service_account
+
+from . import logger
+from .base_storage import BaseCloudStorage, guess_content_type
+from .exceptions import DeleteError, DownloadError, ListError, NotFoundError, UploadError
+from .storage_schema import StorageConfig
+
+
+class GcpClientStorage(BaseCloudStorage):
+    """Google Cloud Storage client implementation.
+
+    This class implements the BaseCloudStorage interface for Google Cloud Storage.
+    It provides methods for uploading, deleting files and generating signed URLs
+    for temporary access to private objects.
+
+    Attributes:
+        credentials: The GCP service account credentials.
+        bucket_name (str): Name of the GCP storage bucket.
+        client: The GCP storage client instance.
+        bucket: The GCP bucket instance.
+
+    Example:
+        config = StorageConfig(gcp={
+            'credentials': {...},
+            'bucket_name': 'my-bucket'
+        })
+        storage = GcpClientStorage(config)
+        await storage.upload('path.txt', 'remote/path.txt')
+    """
+
+    def __init__(self, config: StorageConfig):
+        """Initialize GCP storage client.
+
+        Args:
+            config: Configuration object containing GCP settings.
+                Must include gcp.credentials (dict) and gcp.bucket_name (str).
+
+        Raises:
+            ValueError: If GCP configuration is missing from config.
+        """
+        if not config.gcp:
+            raise ValueError("GCP configuration is required")
+        super().__init__(config)
+        self.credentials = service_account.Credentials.from_service_account_info(
+            config.gcp.credentials
+        )
+        self.bucket_name = config.gcp.bucket_name
+        self.client = storage.Client(credentials=self.credentials)
+        self.bucket = self.client.get_bucket(self.bucket_name)
+        logger.info(f"GcpClientStorage initialized with bucket: {self.bucket_name}")
+
+    async def upload(self, file_path: Path | str, cloud_path: str | None = None) -> str:
+        """Upload a file to Google Cloud Storage bucket.
+
+        Args:
+            file_path: Local filesystem path of the file to upload.
+                Can be string or Path object.
+            cloud_path: Target path in GCP bucket. If None, uses the original filename.
+
+        Returns:
+            The GCP object path where the file was uploaded.
+
+        Raises:
+            UploadError: If the upload operation fails for any reason.
+        """
+        if cloud_path is None:
+            cloud_path = Path(file_path).name
+
+        logger.info(f"Starting upload of {file_path} to gs://{self.bucket_name}/{cloud_path}")
+        try:
+            return await asyncio.to_thread(self._upload_file, file_path, cloud_path)
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            raise UploadError(f"Failed to upload file to GCP: {e}") from e
+
+    async def upload_bytes(
+        self, data: bytes, cloud_path: str, content_type: str | None = None
+    ) -> str:
+        """Upload in-memory bytes to the GCP bucket; returns the object path."""
+        logger.info(f"Uploading {len(data)} bytes to gs://{self.bucket_name}/{cloud_path}")
+        content_type = content_type or guess_content_type(cloud_path)
+        try:
+            await asyncio.to_thread(
+                self.bucket.blob(cloud_path).upload_from_string, data, content_type=content_type
+            )
+            return cloud_path
+        except Exception as e:
+            logger.error(f"Upload failed: {e}")
+            raise UploadError(f"Failed to upload bytes to GCP: {e}") from e
+
+    async def download_bytes(self, cloud_path: str) -> bytes:
+        """Download the GCP object's content."""
+        logger.info(f"Downloading gs://{self.bucket_name}/{cloud_path}")
+        try:
+            return await asyncio.to_thread(self.bucket.blob(cloud_path).download_as_bytes)
+        except NotFound as e:
+            raise NotFoundError(f"GCP object not found: {cloud_path}") from e
+        except Exception as e:
+            logger.error(f"Download failed: {e}")
+            raise DownloadError(f"Failed to download file from GCP: {e}") from e
+
+    async def list_objects(self, prefix: str) -> list[str]:
+        """List GCP object names under `prefix`."""
+        return list(await self.list_object_sizes(prefix))
+
+    async def list_object_sizes(self, prefix: str) -> dict[str, int]:
+        """GCP object name -> size in bytes under `prefix`."""
+        logger.info(f"Listing gs://{self.bucket_name}/{prefix}")
+        try:
+            return await asyncio.to_thread(self._list_sizes, prefix)
+        except Exception as e:
+            logger.error(f"Listing failed: {e}")
+            raise ListError(f"Failed to list objects in GCP: {e}") from e
+
+    async def delete(self, cloud_path: str) -> bool:
+        """Delete a file from Google Cloud Storage bucket.
+
+        Args:
+            cloud_path: The object path in GCP bucket to delete.
+
+        Returns:
+            True if deletion was successful.
+
+        Raises:
+            DeleteError: If the deletion operation fails, including a missing object.
+        """
+        logger.info(f"Deleting gs://{self.bucket_name}/{cloud_path}")
+        try:
+            return await asyncio.to_thread(self._delete_file, cloud_path)
+        except Exception as e:
+            logger.error(f"Deletion failed: {e}")
+            raise DeleteError(f"Failed to delete file from GCP: {e}") from e
+
+    async def delete_if_exists(self, cloud_path: str) -> bool:
+        """Delete a GCP object; False when it did not exist."""
+        logger.info(f"Deleting gs://{self.bucket_name}/{cloud_path} if it exists")
+        try:
+            return await asyncio.to_thread(self._delete_file, cloud_path)
+        except NotFound:
+            return False
+        except Exception as e:
+            logger.error(f"Deletion failed: {e}")
+            raise DeleteError(f"Failed to delete file from GCP: {e}") from e
+
+    async def get_public_url(self, cloud_path: str, expiration: int = 3600) -> str:
+        """Generate a temporary signed URL for accessing a private GCP object.
+
+        Args:
+            cloud_path: The object path in GCP bucket.
+            expiration: URL validity duration in seconds. Defaults to 1 hour (3600 seconds).
+
+        Returns:
+            A signed URL that provides temporary access to the private object.
+
+        Raises:
+            DownloadError: If URL generation fails.
+        """
+        logger.info(f"Generating signed URL for gs://{self.bucket_name}/{cloud_path}")
+        try:
+            return await asyncio.to_thread(self._generate_signed_url, cloud_path, expiration)
+        except Exception as e:
+            logger.error(f"Failed to generate signed URL: {e}")
+            raise DownloadError(f"Failed to generate signed URL: {e}") from e
+
+    def _upload_file(self, file_path: str | Path, cloud_path: str) -> str:
+        """Perform synchronous file upload to GCP bucket.
+
+        Internal method used by the async upload method.
+
+        Args:
+            file_path: Local file path to upload.
+            cloud_path: Target path in GCP bucket.
+
+        Returns:
+            The GCP object path where file was uploaded.
+        """
+        blob = self.bucket.blob(cloud_path)
+        blob.upload_from_filename(str(file_path))
+        logger.debug(f"Successfully uploaded to gs://{self.bucket_name}/{cloud_path}")
+        return cloud_path
+
+    def _delete_file(self, cloud_path: str) -> bool:
+        """Perform synchronous file deletion from GCP bucket.
+
+        Internal method used by the async delete method.
+
+        Args:
+            cloud_path: Object path in GCP bucket to delete.
+
+        Returns:
+            True if deletion was successful.
+        """
+        blob = self.bucket.blob(cloud_path)
+        blob.delete()
+        logger.debug(f"Successfully deleted gs://{self.bucket_name}/{cloud_path}")
+        return True
+
+    def _list_sizes(self, prefix: str) -> dict[str, int]:
+        """Name -> size for every object under `prefix`.
+
+        `list_blobs` pages lazily over HTTP as it is iterated, so it is drained here on the
+        worker thread rather than back on the event loop.
+        """
+        return {b.name: b.size or 0 for b in self.bucket.list_blobs(prefix=prefix)}
+
+    def _generate_signed_url(self, cloud_path: str, expiration: int) -> str:
+        """Generate a signed URL for temporary object access.
+
+        Internal method used by the async get_public_url method.
+
+        Args:
+            cloud_path: Object path in GCP bucket.
+            expiration: URL validity duration in seconds.
+
+        Returns:
+            A signed URL for temporary object access.
+        """
+        blob = self.bucket.blob(cloud_path)
+        url = blob.generate_signed_url(expiration=expiration, method="GET", version="v4")
+        logger.debug(f"Generated signed URL (expires in {expiration}s)")
+        return url

cloud_storage_manager/storage_provider.py

@@ -0,0 +1,72 @@
+from importlib import import_module
+
+from ._distribution import DISTRIBUTION_NAME
+from .base_storage import BaseCloudStorage
+from .storage_schema import StorageConfig, StorageProvider
+
+__all__ = ["CloudStorageFactory", "StorageProvider"]
+
+# 0.1.x imported these two classes here eagerly; they stay importable from this module, but load
+# on first access so `import cloud_storage_manager` pulls in no cloud SDK.
+_LEGACY_CLASSES = {
+    "AWSClientStorage": ".aws_s3_storage",
+    "GcpClientStorage": ".gcp_storage",
+}
+
+
+def __getattr__(name: str):
+    if name in _LEGACY_CLASSES:
+        return getattr(import_module(_LEGACY_CLASSES[name], __package__), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+class CloudStorageFactory:
+    """Factory class for creating cloud storage client instances.
+
+    Each provider module is imported only when it is asked for, so installing a
+    single cloud's extra (``10x-cloud-storage-manager[gcp]``) is enough to use it.
+
+    Example:
+        >>> config = StorageConfig(gcp=GcpConfig(...))
+        >>> storage = CloudStorageFactory.from_config(config)
+        >>> await storage.upload_bytes(b"...", "remote/path.txt", "text/plain")
+    """
+
+    _providers: dict[StorageProvider, tuple[str, str]] = {
+        StorageProvider.AWS: (".aws_s3_storage", "AWSClientStorage"),
+        StorageProvider.GCP: (".gcp_storage", "GcpClientStorage"),
+        StorageProvider.AZURE: (".azure_storage", "AzureBlobStorage"),
+    }
+
+    @classmethod
+    def get_storage(cls, provider: StorageProvider, config: StorageConfig) -> BaseCloudStorage:
+        """Creates and returns a cloud storage instance for the specified provider.
+
+        Args:
+            provider: The cloud storage provider to use.
+            config: Configuration parameters for initializing the storage client.
+
+        Returns:
+            A concrete implementation of BaseCloudStorage for the specified provider.
+
+        Raises:
+            ValueError: If the specified provider is not supported.
+            ImportError: If the provider's extra is not installed.
+        """
+        target = cls._providers.get(provider)
+        if not target:
+            raise ValueError(f"Unsupported storage provider: {provider}")
+        module_name, class_name = target
+        try:
+            module = import_module(module_name, __package__)
+        except ImportError as e:
+            raise ImportError(
+                f"{provider.value} storage needs its extra: "
+                f"pip install '{DISTRIBUTION_NAME}[{provider.value}]'"
+            ) from e
+        return getattr(module, class_name)(config)
+
+    @classmethod
+    def from_config(cls, config: StorageConfig) -> BaseCloudStorage:
+        """Creates the storage client for whichever provider the config sets."""
+        return cls.get_storage(config.provider, config)

cloud_storage_manager/storage_schema.py

@@ -0,0 +1,73 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class StorageProvider(Enum):
+    """Enumeration of supported cloud storage providers."""
+
+    AWS = "aws"
+    GCP = "gcp"
+    AZURE = "azure"
+
+
+class AwsConfig(BaseModel):
+    bucket_name: str = Field(..., description="AWS S3 bucket name")
+    access_key_id: str = Field(..., description="AWS access key ID")
+    secret_access_key: str = Field(..., description="AWS secret access key")
+    region: str = Field(default="us-east-1", description="AWS region")
+
+
+class GcpConfig(BaseModel):
+    bucket_name: str = Field(..., description="GCP bucket name")
+    credentials: dict = Field(..., description="GCP service account credentials")
+    project_id: str = Field(..., description="GCP project ID")
+
+
+class AzureConfig(BaseModel):
+    account_name: str = Field(..., description="Azure storage account name")
+    container_name: str = Field(..., description="Azure Blob container name")
+    account_key: str | None = Field(None, description="Storage account shared key")
+    connection_string: str | None = Field(None, description="Storage account connection string")
+
+    @model_validator(mode="after")
+    def _exactly_one_credential(self) -> "AzureConfig":
+        if (self.account_key is None) == (self.connection_string is None):
+            raise ValueError("Set exactly one of account_key or connection_string")
+        return self
+
+
+class StorageConfig(BaseModel):
+    """Holds one config per cloud.
+
+    Construction accepts any combination, as 0.1.x did: a caller picks the provider explicitly
+    with CloudStorageFactory.get_storage(provider, config). Only `provider` and
+    `CloudStorageFactory.from_config`, which have to infer it, need exactly one.
+    """
+
+    aws: AwsConfig | None = Field(None, description="AWS configuration")
+    gcp: GcpConfig | None = Field(None, description="GCP configuration")
+    azure: AzureConfig | None = Field(None, description="Azure Blob configuration")
+
+    def _configured(self) -> list[StorageProvider]:
+        return [p for p in StorageProvider if getattr(self, p.value) is not None]
+
+    @property
+    def provider(self) -> StorageProvider:
+        """The one provider this config sets.
+
+        Raises:
+            ValueError: If no provider, or more than one, is configured.
+        """
+        configured = self._configured()
+        if len(configured) != 1:
+            names = ", ".join(p.value for p in configured) or "none"
+            raise ValueError(f"Configure exactly one storage provider (got: {names})")
+        return configured[0]
+
+    def has_valid_provider(self) -> bool:
+        """True when at least one provider is configured, as in 0.1.x."""
+        return bool(self._configured())
+
+    def validate_provider(self) -> None:
+        """Kept for 0.1.x callers, where it never raised; it still does not."""