elaunira-r2index 0.1.0__py3-none-any.whl

elaunira/r2index/models.py

@@ -0,0 +1,204 @@
+"""Pydantic models for r2index API requests and responses."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RemoteTuple(BaseModel):
+    """Remote file identifier tuple."""
+
+    remote_path: str
+    remote_filename: str
+    remote_version: str
+
+
+class FileCreateRequest(BaseModel):
+    """Request payload for creating/upserting a file record."""
+
+    category: str
+    entity: str
+    remote_path: str
+    remote_filename: str
+    remote_version: str
+    name: str | None = None
+    tags: list[str] | None = None
+    extra: dict[str, Any] | None = None
+    size: int
+    md5: str
+    sha1: str
+    sha256: str
+    sha512: str
+
+
+class FileUpdateRequest(BaseModel):
+    """Request payload for updating a file record."""
+
+    category: str | None = None
+    entity: str | None = None
+    remote_path: str | None = None
+    remote_filename: str | None = None
+    remote_version: str | None = None
+    name: str | None = None
+    tags: list[str] | None = None
+    extra: dict[str, Any] | None = None
+    size: int | None = None
+    md5: str | None = None
+    sha1: str | None = None
+    sha256: str | None = None
+    sha512: str | None = None
+
+
+class FileRecord(BaseModel):
+    """File record as returned by the API."""
+
+    id: str
+    category: str
+    entity: str
+    remote_path: str
+    remote_filename: str
+    remote_version: str
+    name: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    extra: dict[str, Any] | None = None
+    size: int
+    md5: str
+    sha1: str
+    sha256: str
+    sha512: str
+    created_at: datetime
+    updated_at: datetime
+
+
+class FileListResponse(BaseModel):
+    """Response for listing files."""
+
+    files: list[FileRecord]
+    total: int
+    page: int
+    page_size: int = Field(alias="pageSize")
+
+    model_config = {"populate_by_name": True}
+
+
+class IndexEntry(BaseModel):
+    """Single entry in the index response."""
+
+    id: str
+    category: str
+    entity: str
+    remote_path: str
+    remote_filename: str
+    remote_version: str
+    name: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    size: int
+    md5: str
+    sha1: str
+    sha256: str
+    sha512: str
+
+
+class DownloadRecordRequest(BaseModel):
+    """Request payload for recording a download."""
+
+    file_id: str = Field(alias="fileId")
+    ip_address: str = Field(alias="ipAddress")
+    user_agent: str | None = Field(default=None, alias="userAgent")
+
+    model_config = {"populate_by_name": True}
+
+
+class DownloadRecord(BaseModel):
+    """Download record as returned by the API."""
+
+    id: str
+    file_id: str = Field(alias="fileId")
+    ip_address: str = Field(alias="ipAddress")
+    user_agent: str | None = Field(default=None, alias="userAgent")
+    downloaded_at: datetime = Field(alias="downloadedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class TimeseriesDataPoint(BaseModel):
+    """Single data point in timeseries analytics."""
+
+    timestamp: datetime
+    count: int
+
+
+class TimeseriesResponse(BaseModel):
+    """Response for timeseries analytics."""
+
+    data: list[TimeseriesDataPoint]
+    start: datetime
+    end: datetime
+    granularity: str
+
+
+class SummaryResponse(BaseModel):
+    """Response for summary analytics."""
+
+    total_downloads: int = Field(alias="totalDownloads")
+    unique_ips: int = Field(alias="uniqueIps")
+    unique_files: int = Field(alias="uniqueFiles")
+    start: datetime
+    end: datetime
+
+    model_config = {"populate_by_name": True}
+
+
+class DownloadByIpEntry(BaseModel):
+    """Single download entry for by-IP analytics."""
+
+    file_id: str = Field(alias="fileId")
+    downloaded_at: datetime = Field(alias="downloadedAt")
+    user_agent: str | None = Field(default=None, alias="userAgent")
+
+    model_config = {"populate_by_name": True}
+
+
+class DownloadsByIpResponse(BaseModel):
+    """Response for downloads by IP analytics."""
+
+    ip_address: str = Field(alias="ipAddress")
+    downloads: list[DownloadByIpEntry]
+    total: int
+
+    model_config = {"populate_by_name": True}
+
+
+class UserAgentEntry(BaseModel):
+    """Single user agent entry in analytics."""
+
+    user_agent: str = Field(alias="userAgent")
+    count: int
+
+    model_config = {"populate_by_name": True}
+
+
+class UserAgentsResponse(BaseModel):
+    """Response for user agents analytics."""
+
+    user_agents: list[UserAgentEntry] = Field(alias="userAgents")
+    start: datetime
+    end: datetime
+
+    model_config = {"populate_by_name": True}
+
+
+class CleanupResponse(BaseModel):
+    """Response for cleanup operations."""
+
+    deleted_count: int = Field(alias="deletedCount")
+
+    model_config = {"populate_by_name": True}
+
+
+class HealthResponse(BaseModel):
+    """Response for health check."""
+
+    status: str
+    timestamp: datetime

elaunira/r2index/uploader.py

@@ -0,0 +1,147 @@
+"""Synchronous R2 uploader using boto3."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import boto3
+from boto3.s3.transfer import TransferConfig
+
+from .exceptions import UploadError
+
+# 100MB threshold and part size for multipart uploads
+MULTIPART_THRESHOLD = 100 * 1024 * 1024
+MULTIPART_PART_SIZE = 100 * 1024 * 1024
+
+
+@dataclass
+class R2Config:
+    """Configuration for R2 storage."""
+
+    access_key_id: str
+    secret_access_key: str
+    endpoint_url: str
+    bucket: str
+    region: str = "auto"
+
+
+class R2Uploader:
+    """Synchronous R2 uploader using boto3."""
+
+    def __init__(self, config: R2Config) -> None:
+        """
+        Initialize the R2 uploader.
+
+        Args:
+            config: R2 configuration with credentials and endpoint.
+        """
+        self.config = config
+        self._client = boto3.client(
+            "s3",
+            aws_access_key_id=config.access_key_id,
+            aws_secret_access_key=config.secret_access_key,
+            endpoint_url=config.endpoint_url,
+            region_name=config.region,
+        )
+
+    def upload_file(
+        self,
+        file_path: str | Path,
+        object_key: str,
+        content_type: str | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+    ) -> str:
+        """
+        Upload a file to R2.
+
+        Uses multipart upload for files larger than 100MB.
+
+        Args:
+            file_path: Path to the file to upload.
+            object_key: The key (path) to store the object under in R2.
+            content_type: Optional content type for the object.
+            progress_callback: Optional callback called with bytes uploaded so far.
+
+        Returns:
+            The object key of the uploaded file.
+
+        Raises:
+            UploadError: If the upload fails.
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            raise UploadError(f"File not found: {file_path}")
+
+        transfer_config = TransferConfig(
+            multipart_threshold=MULTIPART_THRESHOLD,
+            multipart_chunksize=MULTIPART_PART_SIZE,
+            use_threads=True,
+        )
+
+        extra_args = {}
+        if content_type:
+            extra_args["ContentType"] = content_type
+
+        callback = None
+        if progress_callback:
+            callback = _ProgressCallback(progress_callback)
+
+        try:
+            self._client.upload_file(
+                str(file_path),
+                self.config.bucket,
+                object_key,
+                Config=transfer_config,
+                ExtraArgs=extra_args if extra_args else None,
+                Callback=callback,
+            )
+        except Exception as e:
+            raise UploadError(f"Failed to upload file to R2: {e}") from e
+
+        return object_key
+
+    def delete_object(self, object_key: str) -> None:
+        """
+        Delete an object from R2.
+
+        Args:
+            object_key: The key of the object to delete.
+
+        Raises:
+            UploadError: If the deletion fails.
+        """
+        try:
+            self._client.delete_object(Bucket=self.config.bucket, Key=object_key)
+        except Exception as e:
+            raise UploadError(f"Failed to delete object from R2: {e}") from e
+
+    def object_exists(self, object_key: str) -> bool:
+        """
+        Check if an object exists in R2.
+
+        Args:
+            object_key: The key of the object to check.
+
+        Returns:
+            True if the object exists, False otherwise.
+        """
+        try:
+            self._client.head_object(Bucket=self.config.bucket, Key=object_key)
+            return True
+        except self._client.exceptions.ClientError as e:
+            if e.response["Error"]["Code"] == "404":
+                return False
+            raise UploadError(f"Failed to check object existence: {e}") from e
+
+
+class _ProgressCallback:
+    """Wrapper to track cumulative progress for boto3 callback."""
+
+    def __init__(self, callback: Callable[[int], None]) -> None:
+        self._callback = callback
+        self._bytes_transferred = 0
+
+    def __call__(self, bytes_amount: int) -> None:
+        self._bytes_transferred += bytes_amount
+        self._callback(self._bytes_transferred)

elaunira_r2index-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: elaunira-r2index
+Version: 0.1.0
+Summary: Python library for uploading files to R2 and registering them with the r2index API
+Project-URL: Homepage, https://github.com/elaunira/elaunira-r2-index
+Project-URL: Repository, https://github.com/elaunira/elaunira-r2-index
+Author: Elaunira
+License-Expression: MIT
+Keywords: cloudflare,index,r2,storage,upload
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aioboto3>=12.0.0
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: boto3-stubs[s3]>=1.34.0; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# elaunira-r2index
+
+Python library for uploading files to Cloudflare R2 and registering them with the r2index API.
+
+## Installation
+
+```bash
+pip install elaunira-r2index
+```
+
+## Usage
+
+### Sync Client
+
+```python
+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="your-r2-access-key-id",
+        secret_access_key="your-r2-secret-access-key",
+        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
+        bucket="your-bucket-name",
+    ),
+)
+
+# 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",
+    tags=["release", "stable"],
+)
+```
+
+### Async Client
+
+```python
+from elaunira.r2index import AsyncR2IndexClient, R2Config
+
+async with AsyncR2IndexClient(
+    api_url="https://r2index.example.com",
+    api_token="your-bearer-token",
+    r2_config=R2Config(
+        access_key_id="your-r2-access-key-id",
+        secret_access_key="your-r2-secret-access-key",
+        endpoint_url="https://your-account-id.r2.cloudflarestorage.com",
+        bucket="your-bucket-name",
+    ),
+) as client:
+    record = await 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",
+        tags=["release", "stable"],
+    )
+```
+
+## License
+
+MIT

elaunira_r2index-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+elaunira/__init__.py,sha256=qaXVGBU6uIJyveNTEbWux5EcfVSM186PvDwjyxiXLw4,34
+elaunira/r2index/__init__.py,sha256=dPjPlDfBIUqzS9STNNtyMF1LyPakXeY5I1ypHEM_jTo,2878
+elaunira/r2index/async_client.py,sha256=T8fWZKnJZOTgsDEvdvv67xL-d_QJ5pP1A3LznEZZ6gY,14936
+elaunira/r2index/async_uploader.py,sha256=ctf65f2DjT9gckEh7XXpHRp1Ym14zv6vx1zIgN_SJpg,4868
+elaunira/r2index/checksums.py,sha256=tqRTJ7j3pWLJlQ8FQE20JRYk9lXy5YZzymdpYOhsTFo,3281
+elaunira/r2index/client.py,sha256=LPtE4uq_OKfmyFJKMKM_hdmU8euVAWkCe17T7HAzXL8,14608
+elaunira/r2index/exceptions.py,sha256=JTSztfTH-jar2jSKEUmQO8VKfRNWfHTB0WgvwLJCVU8,795
+elaunira/r2index/models.py,sha256=ie6uOpamrdmOc9bljym61FurRzpcsoQ1qB4rQQGu7_I,4756
+elaunira/r2index/uploader.py,sha256=kKkC6f_YwMIJ-Tict7mn3S0Sdim6pI4rRXF0xvNwjh0,4250
+elaunira_r2index-0.1.0.dist-info/METADATA,sha256=zQ8Up7wJ-7g26hwL-Ay3QXxgtTaIs8ljUGVgloupv3M,2923
+elaunira_r2index-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+elaunira_r2index-0.1.0.dist-info/RECORD,,

elaunira_r2index-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any