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

srx_lib_azure-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: srx-lib-azure
+Version: 0.3.0
+Summary: Azure helpers for SRX services: Blob, Email, Table, Document Intelligence, Speech Services
+Author-email: SRX <dev@srx.id>
+Requires-Python: >=3.12
+Requires-Dist: azure-ai-documentintelligence>=1.0.0
+Requires-Dist: azure-communication-email>=1.0.0
+Requires-Dist: azure-data-tables>=12.7.0
+Requires-Dist: azure-storage-blob>=12.22.0
+Requires-Dist: loguru>=0.7.2
+Provides-Extra: all
+Requires-Dist: azure-ai-documentintelligence>=1.0.0; extra == 'all'
+Requires-Dist: azure-cognitiveservices-speech>=1.41.1; extra == 'all'
+Provides-Extra: document
+Requires-Dist: azure-ai-documentintelligence>=1.0.0; extra == 'document'
+Provides-Extra: speech
+Requires-Dist: azure-cognitiveservices-speech>=1.41.1; extra == 'speech'
+Description-Content-Type: text/markdown
+
+# srx-lib-azure
+
+Lightweight wrappers over Azure SDKs used across SRX services.
+
+What it includes:
+- **Blob**: upload/download helpers, SAS URL generation
+- **Email** (Azure Communication Services): simple async sender
+- **Table**: simple CRUD helpers
+- **Document Intelligence** (OCR): document analysis from URLs or bytes
+
+## Install
+
+PyPI (public):
+
+- `pip install srx-lib-azure`
+
+uv (pyproject):
+```
+[project]
+dependencies = ["srx-lib-azure>=0.1.0"]
+```
+
+## Usage
+
+Blob:
+```
+from srx_lib_azure.blob import AzureBlobService
+blob = AzureBlobService()
+url = await blob.upload_file(upload_file, "documents/report.pdf")
+```
+
+Email:
+```
+from srx_lib_azure.email import EmailService
+svc = EmailService()
+await svc.send_notification("user@example.com", "Subject", "Hello", html=False)
+```
+
+Table:
+```
+from srx_lib_azure.table import AzureTableService
+store = AzureTableService()
+store.ensure_table("events")
+store.upsert_entity("events", {"PartitionKey":"p","RowKey":"r","EventType":"x"})
+```
+
+Document Intelligence (OCR):
+```python
+from srx_lib_azure import AzureDocumentIntelligenceService
+
+# Initialize with endpoint and key
+doc_service = AzureDocumentIntelligenceService(
+    endpoint="https://your-resource.cognitiveservices.azure.com/",
+    key="your-api-key"
+)
+
+# Analyze document from URL
+result = await doc_service.analyze_document_from_url(
+    url="https://example.com/document.pdf",
+    model_id="prebuilt-read"  # or "prebuilt-layout", "prebuilt-invoice", etc.
+)
+
+# Analyze document from bytes
+with open("document.pdf", "rb") as f:
+    content = f.read()
+result = await doc_service.analyze_document_from_bytes(
+    file_content=content,
+    model_id="prebuilt-read"
+)
+
+# Result structure:
+# {
+#     "success": True/False,
+#     "content": "extracted text...",
+#     "pages": [{"page_number": 1, "width": 8.5, ...}, ...],
+#     "page_count": 10,
+#     "confidence": 0.98,
+#     "model_id": "prebuilt-read",
+#     "metadata": {...},
+#     "error": None  # or error message if failed
+# }
+```
+
+## Environment Variables
+
+- **Blob & Table**: `AZURE_STORAGE_CONNECTION_STRING` (required)
+- **Email (ACS)**: `ACS_CONNECTION_STRING`, `EMAIL_SENDER`
+- **Document Intelligence**: `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT`, `AZURE_DOCUMENT_INTELLIGENCE_KEY`
+- **Optional**: `AZURE_STORAGE_ACCOUNT_KEY`, `AZURE_BLOB_URL`, `AZURE_SAS_TOKEN`
+
+## Optional Dependencies
+
+All services are optional and won't break if their dependencies aren't installed:
+
+```bash
+# Base installation (includes all services by default)
+pip install srx-lib-azure
+
+# Or install only what you need - document intelligence is optional
+pip install srx-lib-azure[document]  # Adds Document Intelligence support
+
+# Install with all optional dependencies
+pip install srx-lib-azure[all]
+```
+
+If you import a service without its required Azure SDK, it will log a warning but won't crash.
+
+## Release
+
+Tag `vX.Y.Z` to publish to GitHub Packages via Actions.
+
+## License
+
+Proprietary © SRX

srx_lib_azure-0.3.0/README.md

@@ -0,0 +1,114 @@
+# srx-lib-azure
+
+Lightweight wrappers over Azure SDKs used across SRX services.
+
+What it includes:
+- **Blob**: upload/download helpers, SAS URL generation
+- **Email** (Azure Communication Services): simple async sender
+- **Table**: simple CRUD helpers
+- **Document Intelligence** (OCR): document analysis from URLs or bytes
+
+## Install
+
+PyPI (public):
+
+- `pip install srx-lib-azure`
+
+uv (pyproject):
+```
+[project]
+dependencies = ["srx-lib-azure>=0.1.0"]
+```
+
+## Usage
+
+Blob:
+```
+from srx_lib_azure.blob import AzureBlobService
+blob = AzureBlobService()
+url = await blob.upload_file(upload_file, "documents/report.pdf")
+```
+
+Email:
+```
+from srx_lib_azure.email import EmailService
+svc = EmailService()
+await svc.send_notification("user@example.com", "Subject", "Hello", html=False)
+```
+
+Table:
+```
+from srx_lib_azure.table import AzureTableService
+store = AzureTableService()
+store.ensure_table("events")
+store.upsert_entity("events", {"PartitionKey":"p","RowKey":"r","EventType":"x"})
+```
+
+Document Intelligence (OCR):
+```python
+from srx_lib_azure import AzureDocumentIntelligenceService
+
+# Initialize with endpoint and key
+doc_service = AzureDocumentIntelligenceService(
+    endpoint="https://your-resource.cognitiveservices.azure.com/",
+    key="your-api-key"
+)
+
+# Analyze document from URL
+result = await doc_service.analyze_document_from_url(
+    url="https://example.com/document.pdf",
+    model_id="prebuilt-read"  # or "prebuilt-layout", "prebuilt-invoice", etc.
+)
+
+# Analyze document from bytes
+with open("document.pdf", "rb") as f:
+    content = f.read()
+result = await doc_service.analyze_document_from_bytes(
+    file_content=content,
+    model_id="prebuilt-read"
+)
+
+# Result structure:
+# {
+#     "success": True/False,
+#     "content": "extracted text...",
+#     "pages": [{"page_number": 1, "width": 8.5, ...}, ...],
+#     "page_count": 10,
+#     "confidence": 0.98,
+#     "model_id": "prebuilt-read",
+#     "metadata": {...},
+#     "error": None  # or error message if failed
+# }
+```
+
+## Environment Variables
+
+- **Blob & Table**: `AZURE_STORAGE_CONNECTION_STRING` (required)
+- **Email (ACS)**: `ACS_CONNECTION_STRING`, `EMAIL_SENDER`
+- **Document Intelligence**: `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT`, `AZURE_DOCUMENT_INTELLIGENCE_KEY`
+- **Optional**: `AZURE_STORAGE_ACCOUNT_KEY`, `AZURE_BLOB_URL`, `AZURE_SAS_TOKEN`
+
+## Optional Dependencies
+
+All services are optional and won't break if their dependencies aren't installed:
+
+```bash
+# Base installation (includes all services by default)
+pip install srx-lib-azure
+
+# Or install only what you need - document intelligence is optional
+pip install srx-lib-azure[document]  # Adds Document Intelligence support
+
+# Install with all optional dependencies
+pip install srx-lib-azure[all]
+```
+
+If you import a service without its required Azure SDK, it will log a warning but won't crash.
+
+## Release
+
+Tag `vX.Y.Z` to publish to GitHub Packages via Actions.
+
+## License
+
+Proprietary © SRX

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

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "srx-lib-azure"
-version = "0.1.7"
-description = "Azure helpers for SRX services: Blob, Email, Table"
+version = "0.3.0"
+description = "Azure helpers for SRX services: Blob, Email, Table, Document Intelligence, Speech Services"
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "SRX", email = "dev@srx.id" }]
@@ -14,6 +14,22 @@ dependencies = [
   "azure-storage-blob>=12.22.0",
   "azure-communication-email>=1.0.0",
   "azure-data-tables>=12.7.0",
+  "azure-ai-documentintelligence>=1.0.0",
+]
+
+[project.optional-dependencies]
+# Optional extra for Document Intelligence (OCR)
+document = [
+  "azure-ai-documentintelligence>=1.0.0",
+]
+# Optional extra for Speech Services (audio transcription)
+speech = [
+  "azure-cognitiveservices-speech>=1.41.1",
+]
+# Install all optional dependencies
+all = [
+  "azure-ai-documentintelligence>=1.0.0",
+  "azure-cognitiveservices-speech>=1.41.1",
 ]
 
 [tool.hatch.build.targets.wheel]

srx_lib_azure-0.3.0/src/srx_lib_azure/__init__.py

@@ -0,0 +1,23 @@
+from .blob import AzureBlobService
+from .document import AzureDocumentIntelligenceService
+from .email import EmailService
+from .table import AzureTableService
+
+# Optional import - only available if speech extra is installed
+try:
+    from .speech import AzureSpeechService
+    __all__ = [
+        "AzureBlobService",
+        "AzureDocumentIntelligenceService",
+        "AzureTableService",
+        "EmailService",
+        "AzureSpeechService",
+    ]
+except ImportError:
+    # Speech SDK not installed - service not available
+    __all__ = [
+        "AzureBlobService",
+        "AzureDocumentIntelligenceService",
+        "AzureTableService",
+        "EmailService",
+    ]

{srx_lib_azure-0.1.7 → srx_lib_azure-0.3.0}/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