srx-lib-azure 0.1.7__tar.gz → 0.1.8__tar.gz

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: srx-lib-azure
-Version: 0.1.7
+Version: 0.1.8
 Summary: Azure helpers for SRX services: Blob, Email, Table
 Author-email: SRX <dev@srx.id>
 Requires-Python: >=3.12

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "srx-lib-azure"
-version = "0.1.7"
+version = "0.1.8"
 description = "Azure helpers for SRX services: Blob, Email, Table"
 readme = "README.md"
 requires-python = ">=3.12"

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/src/srx_lib_azure/__init__.py

@@ -3,4 +3,3 @@ from .email import EmailService
 from .table import AzureTableService
 
 __all__ = ["AzureBlobService", "EmailService", "AzureTableService"]
-

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/src/srx_lib_azure/blob.py

@@ -4,6 +4,11 @@ from datetime import datetime, timedelta, timezone
 from typing import Optional, BinaryIO, Tuple
 
 from azure.storage.blob import BlobServiceClient, BlobSasPermissions, generate_blob_sas
+from azure.core.exceptions import (
+    ResourceNotFoundError,
+    ClientAuthenticationError,
+    HttpResponseError,
+)
 from fastapi import UploadFile
 
 from loguru import logger
@@ -49,9 +54,7 @@ class AzureBlobService:
             return None, None
         try:
             clean = self.connection_string.strip().strip('"').strip("'")
-            parts = dict(
-                seg.split("=", 1) for seg in clean.split(";") if "=" in seg
-            )
+            parts = dict(seg.split("=", 1) for seg in clean.split(";") if "=" in seg)
             account_name = parts.get("AccountName")
             account_key = parts.get("AccountKey") or self.account_key
             return account_name, account_key
@@ -93,9 +96,20 @@ class AzureBlobService:
         if self.base_blob_url:
             base_url = self.base_blob_url.strip().strip('"').strip("'").rstrip("/")
             return f"{base_url}/{blob_name}?{sas}"
-        return f"https://{account_name}.blob.core.windows.net/{self.container_name}/{blob_name}?{sas}"
+        return (
+            f"https://{account_name}.blob.core.windows.net/{self.container_name}/{blob_name}?{sas}"
+        )
 
     async def upload_file(self, file: UploadFile, blob_path: str) -> Optional[str]:
+        """Upload a file to Azure Blob Storage and return a SAS URL.
+
+        Args:
+            file: File to upload
+            blob_path: Destination path in the container
+
+        Returns:
+            SAS URL if successful, None on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -105,13 +119,37 @@ class AzureBlobService:
             container = client.get_container_client(self.container_name)
             content = await file.read()
             blob_client = container.get_blob_client(blob_path)
-            blob_client.upload_blob(content, overwrite=True, content_type=file.content_type or "application/octet-stream")
+            blob_client.upload_blob(
+                content,
+                overwrite=True,
+                content_type=file.content_type or "application/octet-stream",
+            )
             return self._generate_sas_url(blob_path)
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed uploading {file.filename}: {e}")
+            return None
+        except HttpResponseError as e:
+            logger.error(
+                f"Azure service error uploading {file.filename}: {e.status_code} - {e.message}"
+            )
+            return None
         except Exception as e:
-            logger.error(f"Failed to upload file {file.filename}: {e}")
+            logger.error(f"Unexpected error uploading {file.filename}: {e}")
             return None
 
-    async def upload_stream(self, stream: BinaryIO, blob_path: str, content_type: str = "application/octet-stream") -> Optional[str]:
+    async def upload_stream(
+        self, stream: BinaryIO, blob_path: str, content_type: str = "application/octet-stream"
+    ) -> Optional[str]:
+        """Upload a binary stream to Azure Blob Storage and return a SAS URL.
+
+        Args:
+            stream: Binary stream to upload
+            blob_path: Destination path in the container
+            content_type: MIME type of the content
+
+        Returns:
+            SAS URL if successful, None on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -122,12 +160,27 @@ class AzureBlobService:
             blob_client = container.get_blob_client(blob_path)
             blob_client.upload_blob(stream, overwrite=True, content_type=content_type)
             return self._generate_sas_url(blob_path)
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed uploading stream to {blob_path}: {e}")
+            return None
+        except HttpResponseError as e:
+            logger.error(
+                f"Azure service error uploading stream to {blob_path}: {e.status_code} - {e.message}"
+            )
+            return None
         except Exception as e:
-            logger.error(f"Failed to upload stream to {blob_path}: {e}")
+            logger.error(f"Unexpected error uploading stream to {blob_path}: {e}")
             return None
 
     async def download_file(self, blob_path: str) -> Optional[bytes]:
-        """Download a blob's content as bytes."""
+        """Download a blob's content as bytes.
+
+        Returns:
+            bytes if successful, None if blob doesn't exist
+
+        Raises:
+            RuntimeError: For connection/auth errors (caller should handle)
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -139,9 +192,24 @@ class AzureBlobService:
             content = download_stream.readall()
             logger.info(f"Successfully downloaded {blob_path}")
             return content
-        except Exception as e:
-            logger.error(f"Failed to download {blob_path}: {e}")
+        except ResourceNotFoundError:
+            # Blob doesn't exist - this is expected in many scenarios
+            logger.info(f"Blob not found: {blob_path}")
             return None
+        except ClientAuthenticationError as e:
+            # Auth errors should not be retried - they need credential fixes
+            logger.error(f"Authentication failed for {blob_path}: {e}")
+            raise RuntimeError(f"Azure authentication failed: {e}") from e
+        except HttpResponseError as e:
+            # Other Azure service errors (rate limits, service issues, etc.)
+            logger.error(
+                f"Azure service error downloading {blob_path}: {e.status_code} - {e.message}"
+            )
+            raise RuntimeError(f"Azure Blob download failed for {blob_path}: {e.message}") from e
+        except Exception as e:
+            # Catch-all for unexpected errors (network, etc.)
+            logger.error(f"Unexpected error downloading {blob_path}: {e}")
+            raise RuntimeError(f"Unexpected error downloading {blob_path}: {e}") from e
 
     async def download_to_temp_file(self, blob_path: str) -> Optional[str]:
         """Download a blob to a temporary file and return its path."""
@@ -149,7 +217,9 @@ class AzureBlobService:
         if content is None:
             return None
         try:
-            with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(blob_path)[1]) as tf:
+            with tempfile.NamedTemporaryFile(
+                delete=False, suffix=os.path.splitext(blob_path)[1]
+            ) as tf:
                 tf.write(content)
                 path = tf.name
             logger.info(f"Downloaded {blob_path} to temporary file: {path}")
@@ -172,7 +242,14 @@ class AzureBlobService:
         return None
 
     async def delete_file(self, blob_path: str) -> bool:
-        """Delete a blob and return True on success."""
+        """Delete a blob and return True on success.
+
+        Args:
+            blob_path: Path to the blob to delete
+
+        Returns:
+            True if deleted successfully or blob doesn't exist, False on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return False
@@ -183,12 +260,29 @@ class AzureBlobService:
             blob_client.delete_blob()
             logger.info(f"Successfully deleted {blob_path}")
             return True
+        except ResourceNotFoundError:
+            # Blob already doesn't exist - this is still success
+            logger.info(f"Blob {blob_path} already deleted or doesn't exist")
+            return True
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed when deleting {blob_path}: {e}")
+            return False
+        except HttpResponseError as e:
+            logger.error(f"Azure service error deleting {blob_path}: {e.status_code} - {e.message}")
+            return False
         except Exception as e:
-            logger.error(f"Failed to delete {blob_path}: {e}")
+            logger.error(f"Unexpected error deleting {blob_path}: {e}")
             return False
 
     async def file_exists(self, blob_path: str) -> bool:
-        """Check if a blob exists in the container."""
+        """Check if a blob exists in the container.
+
+        Args:
+            blob_path: Path to the blob to check
+
+        Returns:
+            True if blob exists, False otherwise (including on errors)
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return False
@@ -197,6 +291,12 @@ class AzureBlobService:
             container = client.get_container_client(self.container_name)
             blob_client = container.get_blob_client(blob_path)
             return blob_client.exists()
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed checking {blob_path}: {e}")
+            return False
+        except HttpResponseError as e:
+            logger.error(f"Azure service error checking {blob_path}: {e.status_code} - {e.message}")
+            return False
         except Exception as e:
-            logger.error(f"Failed to check existence of {blob_path}: {e}")
+            logger.error(f"Unexpected error checking existence of {blob_path}: {e}")
             return False

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/src/srx_lib_azure/email.py

@@ -4,8 +4,16 @@ from typing import Dict, Any
 
 try:
     from azure.communication.email.aio import EmailClient
+    from azure.core.exceptions import (
+        ClientAuthenticationError,
+        HttpResponseError,
+        ServiceRequestError,
+    )
 except Exception:  # pragma: no cover - optional dependency at import time
     EmailClient = None  # type: ignore
+    ClientAuthenticationError = None  # type: ignore
+    HttpResponseError = None  # type: ignore
+    ServiceRequestError = None  # type: ignore
 
 logger = logging.getLogger(__name__)
 
@@ -39,10 +47,27 @@ class EmailService:
                 self.email_client = None
                 logger.warning("EmailService initialization failed: %s", e)
 
-    async def send_notification(self, recipient: str, subject: str, body: str, html: bool = False) -> Dict[str, Any]:
+    async def send_notification(
+        self, recipient: str, subject: str, body: str, html: bool = False
+    ) -> Dict[str, Any]:
+        """Send an email notification via Azure Communication Services.
+
+        Args:
+            recipient: Email address of the recipient
+            subject: Email subject line
+            body: Email body content
+            html: If True, send as HTML; otherwise plain text
+
+        Returns:
+            Dict with status, message, and optional message_id
+            - status: "success" | "error" | "skipped"
+            - message: Human-readable message
+            - message_id: Azure message ID (only on success)
+        """
         if not self.email_client or not self.sender_address:
             logger.warning("Email skipped: service not configured")
             return {"status": "skipped", "message": "Email service not configured"}
+
         message = {
             "content": {"subject": subject},
             "recipients": {"to": [{"address": recipient}]},
@@ -52,15 +77,41 @@ class EmailService:
             message["content"]["html"] = body
         else:
             message["content"]["plainText"] = body
+
         try:
             poller = await self.email_client.begin_send(message)
             result = await poller.result()
             message_id = result.get("id")
             if message_id:
                 logger.info("Email sent to %s with Message ID: %s", recipient, message_id)
-                return {"status": "success", "message": "Email sent successfully", "message_id": message_id}
+                return {
+                    "status": "success",
+                    "message": "Email sent successfully",
+                    "message_id": message_id,
+                }
             logger.error("Failed to send email. Result: %s", result)
             return {"status": "error", "message": f"Failed to send email: {result}"}
+        except ClientAuthenticationError as e:
+            # Auth errors should not be retried - they need credential fixes
+            logger.error("Authentication failed sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Authentication failed: {e}"}
+        except HttpResponseError as e:
+            # Azure service errors (rate limits, invalid recipient, etc.)
+            logger.error(
+                "Azure service error sending email to %s: %s - %s",
+                recipient,
+                e.status_code,
+                e.message,
+            )
+            return {
+                "status": "error",
+                "message": f"Azure service error ({e.status_code}): {e.message}",
+            }
+        except ServiceRequestError as e:
+            # Network/connection errors - may be retryable
+            logger.error("Network error sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Network error: {e}"}
         except Exception as e:
-            logger.error("Email send exception: %s", e)
-            return {"status": "error", "message": str(e)}
+            # Catch-all for unexpected errors
+            logger.error("Unexpected error sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Unexpected error: {e}"}

{srx_lib_azure-0.1.7 → srx_lib_azure-0.1.8}/src/srx_lib_azure/table.py

@@ -9,8 +9,18 @@ from loguru import logger
 
 try:
     from azure.data.tables import TableServiceClient
+    from azure.core.exceptions import (
+        ResourceNotFoundError,
+        ResourceExistsError,
+        ClientAuthenticationError,
+        HttpResponseError,
+    )
 except Exception:  # pragma: no cover
     TableServiceClient = None  # type: ignore
+    ResourceNotFoundError = None  # type: ignore
+    ResourceExistsError = None  # type: ignore
+    ClientAuthenticationError = None  # type: ignore
+    HttpResponseError = None  # type: ignore
 
 
 def _now_iso() -> str:
@@ -62,15 +72,25 @@ class AzureTableService:
             table_name: Name of the table to delete
 
         Returns:
-            True if deleted successfully, False otherwise
+            True if deleted successfully or table doesn't exist, False on other errors
         """
         client = self._get_client()
         try:
             client.delete_table(table_name=table_name)
             logger.info("Deleted table: %s", table_name)
             return True
+        except ResourceNotFoundError:
+            # Table already deleted or doesn't exist - this is still success
+            logger.info(f"Table {table_name} already deleted or doesn't exist")
+            return True
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed deleting table %s: %s", table_name, exc)
+            return False
+        except HttpResponseError as exc:
+            logger.error("Azure service error deleting table %s: %s", table_name, exc.message)
+            return False
         except Exception as exc:
-            logger.error("Failed to delete table %s: %s", table_name, exc)
+            logger.error("Unexpected error deleting table %s: %s", table_name, exc)
             return False
 
     def table_exists(self, table_name: str) -> bool:
@@ -85,38 +105,105 @@ class AzureTableService:
         return table_name in self.list_tables()
 
     def put_entity(self, table_name: str, entity: Dict[str, Any]) -> Dict[str, Any]:
+        """Insert a new entity into a table.
+
+        Args:
+            table_name: Name of the table
+            entity: Entity dictionary with PartitionKey and RowKey
+
+        Returns:
+            Dict with etag and timestamp
+
+        Raises:
+            RuntimeError: If entity already exists or other errors occur
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
-        res = table.create_entity(entity=entity)
-        logger.info(
-            "Inserted entity into %s: PK=%s RK=%s",
-            table_name,
-            entity.get("PartitionKey"),
-            entity.get("RowKey"),
-        )
-        return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        try:
+            res = table.create_entity(entity=entity)
+            logger.info(
+                "Inserted entity into %s: PK=%s RK=%s",
+                table_name,
+                entity.get("PartitionKey"),
+                entity.get("RowKey"),
+            )
+            return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        except ResourceExistsError as e:
+            pk, rk = entity.get("PartitionKey"), entity.get("RowKey")
+            logger.error(f"Entity already exists in {table_name}: PK={pk} RK={rk}")
+            raise RuntimeError(f"Entity already exists: {e}") from e
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed inserting entity into {table_name}: {e}")
+            raise RuntimeError(f"Authentication failed: {e}") from e
+        except HttpResponseError as e:
+            logger.error(f"Azure service error inserting entity into {table_name}: {e.message}")
+            raise RuntimeError(f"Failed to insert entity: {e.message}") from e
 
     def upsert_entity(self, table_name: str, entity: Dict[str, Any]) -> Dict[str, Any]:
+        """Insert or update an entity in a table.
+
+        Args:
+            table_name: Name of the table
+            entity: Entity dictionary with PartitionKey and RowKey
+
+        Returns:
+            Dict with etag and timestamp
+
+        Raises:
+            RuntimeError: If authentication or service errors occur
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
-        res = table.upsert_entity(entity=entity, mode="merge")
-        logger.info(
-            "Upserted entity into %s: PK=%s RK=%s",
-            table_name,
-            entity.get("PartitionKey"),
-            entity.get("RowKey"),
-        )
-        return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        try:
+            res = table.upsert_entity(entity=entity, mode="merge")
+            logger.info(
+                "Upserted entity into %s: PK=%s RK=%s",
+                table_name,
+                entity.get("PartitionKey"),
+                entity.get("RowKey"),
+            )
+            return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed upserting entity into {table_name}: {e}")
+            raise RuntimeError(f"Authentication failed: {e}") from e
+        except HttpResponseError as e:
+            logger.error(f"Azure service error upserting entity into {table_name}: {e.message}")
+            raise RuntimeError(f"Failed to upsert entity: {e.message}") from e
 
     def delete_entity(self, table_name: str, partition_key: str, row_key: str) -> bool:
+        """Delete an entity from a table.
+
+        Args:
+            table_name: Name of the table
+            partition_key: Partition key of the entity
+            row_key: Row key of the entity
+
+        Returns:
+            True if deleted successfully or entity doesn't exist, False on other errors
+
+        Note:
+            Azure Tables delete_entity doesn't fail if entity doesn't exist
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
         try:
             table.delete_entity(partition_key=partition_key, row_key=row_key)
             logger.info("Deleted entity in %s (%s/%s)", table_name, partition_key, row_key)
             return True
+        except ResourceNotFoundError:
+            # Entity already deleted or doesn't exist - this is still success
+            logger.info(
+                f"Entity in {table_name} ({partition_key}/{row_key}) already deleted or doesn't exist"
+            )
+            return True
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed deleting entity in %s: %s", table_name, exc)
+            return False
+        except HttpResponseError as exc:
+            logger.error("Azure service error deleting entity in %s: %s", table_name, exc.message)
+            return False
         except Exception as exc:
-            logger.error("Failed to delete entity in %s: %s", table_name, exc)
+            logger.error("Unexpected error deleting entity in %s: %s", table_name, exc)
             return False
 
     def get_entity(
@@ -130,7 +217,7 @@ class AzureTableService:
             row_key: Row key of the entity
 
         Returns:
-            Entity dict if found, None otherwise
+            Entity dict if found, None otherwise (including on auth/service errors)
         """
         client = self._get_client()
         table = client.get_table_client(table_name)
@@ -138,11 +225,20 @@ class AzureTableService:
             entity = table.get_entity(partition_key=partition_key, row_key=row_key)
             logger.info("Retrieved entity from %s: PK=%s RK=%s", table_name, partition_key, row_key)
             return dict(entity)
-        except Exception as exc:
-            logger.warning(
-                "Entity not found in %s (%s/%s): %s", table_name, partition_key, row_key, exc
+        except ResourceNotFoundError:
+            logger.info("Entity not found in %s (%s/%s)", table_name, partition_key, row_key)
+            return None
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed retrieving entity from %s: %s", table_name, exc)
+            return None
+        except HttpResponseError as exc:
+            logger.error(
+                "Azure service error retrieving entity from %s: %s", table_name, exc.message
             )
             return None
+        except Exception as exc:
+            logger.error("Unexpected error retrieving entity from %s: %s", table_name, exc)
+            return None
 
     def entity_exists(self, table_name: str, partition_key: str, row_key: str) -> bool:
         """Check if an entity exists without retrieving it.