elaunira-r2index 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

elaunira/r2index/__init__.py

@@ -1,43 +1,11 @@
-"""
-R2 Index Python Library.
+"""Python library for uploading and downloading files to/from Cloudflare R2 with the r2index API."""
 
-A Python library for uploading files to Cloudflare R2 and registering them
-with the r2index API. Supports both sync and async operations with streaming
-checksums for memory-efficient handling of large files.
+from importlib.metadata import version
 
-Usage:
-    from elaunira.r2index import R2IndexClient, R2Config
-
-    client = R2IndexClient(
-        api_url="https://r2index.example.com",
-        api_token="your-bearer-token",
-        r2_config=R2Config(
-            access_key_id="...",
-            secret_access_key="...",
-            endpoint_url="https://xxx.r2.cloudflarestorage.com",
-            bucket="your-bucket",
-        ),
-    )
-
-    # Upload and register a file
-    record = client.upload_and_register(
-        file_path="./myfile.zip",
-        category="software",
-        entity="myapp",
-        remote_path="/releases",
-        remote_filename="myapp-1.0.0.zip",
-        remote_version="1.0.0",
-    )
-
-Async usage:
-    from elaunira.r2index import AsyncR2IndexClient, R2Config
-
-    async with AsyncR2IndexClient(...) as client:
-        record = await client.upload_and_register(...)
-"""
+__version__ = version("elaunira-r2index")
 
 from .async_client import AsyncR2IndexClient
-from .async_uploader import AsyncR2Uploader
+from .async_storage import AsyncR2Storage
 from .checksums import (
     ChecksumResult,
     compute_checksums,
@@ -48,6 +16,7 @@ from .client import R2IndexClient
 from .exceptions import (
     AuthenticationError,
     ConflictError,
+    DownloadError,
     NotFoundError,
     R2IndexError,
     UploadError,
@@ -72,44 +41,48 @@ from .models import (
     UserAgentEntry,
     UserAgentsResponse,
 )
-from .uploader import R2Config, R2Uploader
+from .storage import R2Config, R2Storage, R2TransferConfig
 
 __all__ = [
+    # Version
+    "__version__",
     # Clients
-    "R2IndexClient",
     "AsyncR2IndexClient",
-    # Uploaders
-    "R2Uploader",
-    "AsyncR2Uploader",
+    "R2IndexClient",
+    # Storage
+    "AsyncR2Storage",
     "R2Config",
+    "R2Storage",
+    "R2TransferConfig",
     # Checksums
     "ChecksumResult",
     "compute_checksums",
     "compute_checksums_async",
     "compute_checksums_from_file_object",
     # Exceptions
-    "R2IndexError",
     "AuthenticationError",
-    "NotFoundError",
-    "ValidationError",
     "ConflictError",
+    "DownloadError",
+    "NotFoundError",
+    "R2IndexError",
     "UploadError",
+    "ValidationError",
     # Models - File operations
-    "FileRecord",
     "FileCreateRequest",
-    "FileUpdateRequest",
     "FileListResponse",
+    "FileRecord",
+    "FileUpdateRequest",
     "IndexEntry",
     "RemoteTuple",
     # Models - Downloads
     "DownloadRecord",
     "DownloadRecordRequest",
     # Models - Analytics
-    "TimeseriesDataPoint",
-    "TimeseriesResponse",
-    "SummaryResponse",
     "DownloadByIpEntry",
     "DownloadsByIpResponse",
+    "SummaryResponse",
+    "TimeseriesDataPoint",
+    "TimeseriesResponse",
     "UserAgentEntry",
     "UserAgentsResponse",
     # Models - Other

elaunira/r2index/async_client.py

@@ -7,7 +7,7 @@ from typing import Any
 
 import httpx
 
-from .async_uploader import AsyncR2Uploader
+from .async_storage import AsyncR2Storage
 from .checksums import compute_checksums_async
 from .exceptions import (
     AuthenticationError,
@@ -32,7 +32,48 @@ from .models import (
     TimeseriesResponse,
     UserAgentsResponse,
 )
-from .uploader import R2Config
+from . import __version__
+from .storage import R2Config, R2TransferConfig
+
+CHECKIP_URL = "https://checkip.amazonaws.com"
+DEFAULT_USER_AGENT = f"elaunira-r2index/{__version__}"
+
+
+def _parse_object_id(object_id: str, bucket: str) -> RemoteTuple:
+    """
+    Parse an object_id into remote_path, remote_version, and remote_filename.
+
+    Format: /path/to/object/version/filename.ext
+    - remote_filename: last component (filename.ext)
+    - remote_version: second-to-last component (version)
+    - remote_path: everything before that (/path/to/object)
+
+    Args:
+        object_id: Full object path like /releases/myapp/v1/myapp.zip
+        bucket: The S3/R2 bucket name.
+
+    Returns:
+        RemoteTuple with parsed components including bucket.
+
+    Raises:
+        ValueError: If object_id doesn't have enough components.
+    """
+    parts = object_id.strip("/").split("/")
+    if len(parts) < 3:
+        raise ValueError(
+            f"object_id must have at least 3 components (path/version/filename), got: {object_id}"
+        )
+
+    remote_filename = parts[-1]
+    remote_version = parts[-2]
+    remote_path = "/" + "/".join(parts[:-2])
+
+    return RemoteTuple(
+        bucket=bucket,
+        remote_path=remote_path,
+        remote_filename=remote_filename,
+        remote_version=remote_version,
+    )
 
 
 class AsyncR2IndexClient:
@@ -40,29 +81,42 @@ class AsyncR2IndexClient:
 
     def __init__(
         self,
-        api_url: str,
-        api_token: str,
-        r2_config: R2Config | None = None,
+        index_api_url: str,
+        index_api_token: str,
+        r2_access_key_id: str | None = None,
+        r2_secret_access_key: str | None = None,
+        r2_endpoint_url: str | None = None,
         timeout: float = 30.0,
     ) -> None:
         """
         Initialize the async R2Index client.
 
         Args:
-            api_url: Base URL of the r2index API.
-            api_token: Bearer token for authentication.
-            r2_config: Optional R2 configuration for upload operations.
+            index_api_url: Base URL of the r2index API.
+            index_api_token: Bearer token for authentication.
+            r2_access_key_id: R2 access key ID for storage operations.
+            r2_secret_access_key: R2 secret access key for storage operations.
+            r2_endpoint_url: R2 endpoint URL for storage operations.
             timeout: Request timeout in seconds.
         """
-        self.api_url = api_url.rstrip("/")
-        self._token = api_token
+        self.api_url = index_api_url.rstrip("/")
+        self._token = index_api_token
         self._timeout = timeout
-        self._r2_config = r2_config
-        self._uploader: AsyncR2Uploader | None = None
+        self._storage: AsyncR2Storage | None = None
+
+        # Build R2 config if credentials provided
+        if r2_access_key_id and r2_secret_access_key and r2_endpoint_url:
+            self._r2_config: R2Config | None = R2Config(
+                access_key_id=r2_access_key_id,
+                secret_access_key=r2_secret_access_key,
+                endpoint_url=r2_endpoint_url,
+            )
+        else:
+            self._r2_config = None
 
         self._client = httpx.AsyncClient(
             base_url=self.api_url,
-            headers={"Authorization": f"Bearer {api_token}"},
+            headers={"Authorization": f"Bearer {index_api_token}"},
             timeout=timeout,
         )
 
@@ -76,13 +130,13 @@ class AsyncR2IndexClient:
         """Close the HTTP client."""
         await self._client.aclose()
 
-    def _get_uploader(self) -> AsyncR2Uploader:
+    def _get_storage(self) -> AsyncR2Storage:
         """Get or create the async R2 uploader."""
         if self._r2_config is None:
             raise R2IndexError("R2 configuration required for upload operations")
-        if self._uploader is None:
-            self._uploader = AsyncR2Uploader(self._r2_config)
-        return self._uploader
+        if self._storage is None:
+            self._storage = AsyncR2Storage(self._r2_config)
+        return self._storage
 
     def _handle_response(self, response: httpx.Response) -> Any:
         """Handle API response and raise appropriate exceptions."""
@@ -109,8 +163,9 @@ class AsyncR2IndexClient:
 
     # File Operations
 
-    async def list_files(
+    async def list(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -121,6 +176,7 @@ class AsyncR2IndexClient:
         List files with optional filters.
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -131,6 +187,8 @@ class AsyncR2IndexClient:
             FileListResponse with files and pagination info.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -146,7 +204,7 @@ class AsyncR2IndexClient:
         data = self._handle_response(response)
         return FileListResponse.model_validate(data)
 
-    async def create_file(self, data: FileCreateRequest) -> FileRecord:
+    async def create(self, data: FileCreateRequest) -> FileRecord:
         """
         Create or upsert a file record.
 
@@ -160,7 +218,7 @@ class AsyncR2IndexClient:
         result = self._handle_response(response)
         return FileRecord.model_validate(result)
 
-    async def get_file(self, file_id: str) -> FileRecord:
+    async def get(self, file_id: str) -> FileRecord:
         """
         Get a file by ID.
 
@@ -177,7 +235,7 @@ class AsyncR2IndexClient:
         data = self._handle_response(response)
         return FileRecord.model_validate(data)
 
-    async def update_file(self, file_id: str, data: FileUpdateRequest) -> FileRecord:
+    async def update(self, file_id: str, data: FileUpdateRequest) -> FileRecord:
         """
         Update a file record.
 
@@ -195,7 +253,7 @@ class AsyncR2IndexClient:
         result = self._handle_response(response)
         return FileRecord.model_validate(result)
 
-    async def delete_file(self, file_id: str) -> None:
+    async def delete(self, file_id: str) -> None:
         """
         Delete a file by ID.
 
@@ -208,17 +266,18 @@ class AsyncR2IndexClient:
         response = await self._client.delete(f"/files/{file_id}")
         self._handle_response(response)
 
-    async def delete_file_by_tuple(self, remote_tuple: RemoteTuple) -> None:
+    async def delete_by_tuple(self, remote_tuple: RemoteTuple) -> None:
         """
         Delete a file by remote tuple.
 
         Args:
-            remote_tuple: The remote path, filename, and version.
+            remote_tuple: The bucket, remote path, filename, and version.
 
         Raises:
             NotFoundError: If the file is not found.
         """
         params = {
+            "bucket": remote_tuple.bucket,
             "remotePath": remote_tuple.remote_path,
             "remoteFilename": remote_tuple.remote_filename,
             "remoteVersion": remote_tuple.remote_version,
@@ -226,8 +285,32 @@ class AsyncR2IndexClient:
         response = await self._client.delete("/files", params=params)
         self._handle_response(response)
 
-    async def get_index(
+    async def get_by_tuple(self, remote_tuple: RemoteTuple) -> FileRecord:
+        """
+        Get a file by remote tuple.
+
+        Args:
+            remote_tuple: The bucket, remote path, filename, and version.
+
+        Returns:
+            The FileRecord.
+
+        Raises:
+            NotFoundError: If the file is not found.
+        """
+        params = {
+            "bucket": remote_tuple.bucket,
+            "remotePath": remote_tuple.remote_path,
+            "remoteFilename": remote_tuple.remote_filename,
+            "remoteVersion": remote_tuple.remote_version,
+        }
+        response = await self._client.get("/files/by-tuple", params=params)
+        data = self._handle_response(response)
+        return FileRecord.model_validate(data)
+
+    async def index(
         self,
+        bucket: str | None = None,
         category: str | None = None,
         entity: str | None = None,
         tags: list[str] | None = None,
@@ -236,6 +319,7 @@ class AsyncR2IndexClient:
         Get file index (lightweight listing).
 
         Args:
+            bucket: Filter by bucket.
             category: Filter by category.
             entity: Filter by entity.
             tags: Filter by tags.
@@ -244,6 +328,8 @@ class AsyncR2IndexClient:
             List of IndexEntry objects.
         """
         params: dict[str, Any] = {}
+        if bucket:
+            params["bucket"] = bucket
         if category:
             params["category"] = category
         if entity:
@@ -424,9 +510,10 @@ class AsyncR2IndexClient:
 
     # High-Level Pipeline
 
-    async def upload_and_register(
+    async def upload(
         self,
-        file_path: str | Path,
+        bucket: str,
+        local_path: str | Path,
         category: str,
         entity: str,
         remote_path: str,
@@ -447,7 +534,8 @@ class AsyncR2IndexClient:
         3. Register with r2index API
 
         Args:
-            file_path: Path to the file to upload.
+            bucket: The S3/R2 bucket name.
+            local_path: Local path to the file to upload.
             category: File category.
             entity: File entity.
             remote_path: Remote path in R2 (e.g., "/data/files").
@@ -466,18 +554,19 @@ class AsyncR2IndexClient:
             R2IndexError: If R2 config is not provided.
             UploadError: If upload fails.
         """
-        file_path = Path(file_path)
-        uploader = self._get_uploader()
+        local_path = Path(local_path)
+        uploader = self._get_storage()
 
         # Step 1: Compute checksums
-        checksums = await compute_checksums_async(file_path)
+        checksums = await compute_checksums_async(local_path)
 
         # Step 2: Build R2 object key
         object_key = f"{remote_path.strip('/')}/{remote_filename}"
 
         # Step 3: Upload to R2
         await uploader.upload_file(
-            file_path,
+            local_path,
+            bucket,
             object_key,
             content_type=content_type,
             progress_callback=progress_callback,
@@ -485,6 +574,7 @@ class AsyncR2IndexClient:
 
         # Step 4: Register with API
         create_request = FileCreateRequest(
+            bucket=bucket,
             category=category,
             entity=entity,
             remote_path=remote_path,
@@ -500,4 +590,86 @@ class AsyncR2IndexClient:
             sha512=checksums.sha512,
         )
 
-        return await self.create_file(create_request)
+        return await self.create(create_request)
+
+    async def _get_public_ip(self) -> str:
+        """Fetch public IP address from checkip.amazonaws.com."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(CHECKIP_URL, timeout=10.0)
+            return response.text.strip()
+
+    async def download(
+        self,
+        bucket: str,
+        object_id: str,
+        destination: str | Path,
+        ip_address: str | None = None,
+        user_agent: str | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+        transfer_config: R2TransferConfig | None = None,
+    ) -> tuple[Path, FileRecord]:
+        """
+        Download a file from R2 and record the download in the index asynchronously.
+
+        This is a convenience method that performs:
+        1. Parse object_id into remote_path, remote_version, remote_filename
+        2. Fetch file record from the API using these components
+        3. Download the file from R2
+        4. Record the download in the index for analytics
+
+        Args:
+            bucket: The S3/R2 bucket name.
+            object_id: Full S3 object path in format: /path/to/object/version/filename
+                Example: /releases/myapp/v1/myapp.zip
+                - remote_path: /releases/myapp
+                - remote_version: v1
+                - remote_filename: myapp.zip
+            destination: Local path where the file will be saved.
+            ip_address: IP address of the downloader. If not provided, fetched
+                from checkip.amazonaws.com.
+            user_agent: User agent string. Defaults to "elaunira-r2index/<version>".
+            progress_callback: Optional callback for download progress.
+            transfer_config: Optional transfer configuration for multipart/threading.
+
+        Returns:
+            A tuple of (downloaded file path, file record).
+
+        Raises:
+            R2IndexError: If R2 config is not provided.
+            ValueError: If object_id format is invalid.
+            NotFoundError: If the file is not found in the index.
+            DownloadError: If download fails.
+        """
+        storage = self._get_storage()
+
+        # Resolve defaults
+        if ip_address is None:
+            ip_address = await self._get_public_ip()
+        if user_agent is None:
+            user_agent = DEFAULT_USER_AGENT
+
+        # Step 1: Parse object_id into components
+        remote_tuple = _parse_object_id(object_id, bucket)
+
+        # Step 2: Get file record by tuple
+        file_record = await self.get_by_tuple(remote_tuple)
+
+        # Step 3: Build R2 object key and download
+        object_key = object_id.strip("/")
+        downloaded_path = await storage.download_file(
+            bucket,
+            object_key,
+            destination,
+            progress_callback=progress_callback,
+            transfer_config=transfer_config,
+        )
+
+        # Step 4: Record the download
+        download_request = DownloadRecordRequest(
+            file_id=file_record.id,
+            ip_address=ip_address,
+            user_agent=user_agent,
+        )
+        await self.record_download(download_request)
+
+        return downloaded_path, file_record