fabric-pbi 1.0.0__py3-none-any.whl

fabricpandas/semantic_model/semantic_model_client.py

@@ -0,0 +1,643 @@
+"""
+Semantic Model Client for Microsoft Fabric
+Provides operations for managing Semantic Models in Fabric workspaces.
+"""
+
+import requests
+import base64
+import time
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from ..auth import BaseClient
+
+
+class SemanticModelClient(BaseClient):
+    """
+    Client for interacting with Fabric Semantic Model APIs
+    
+    Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items
+    """
+    
+    def create_semantic_model(
+        self,
+        workspace_id: str,
+        display_name: str,
+        description: Optional[str] = None,
+        definition: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new Semantic Model
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/create-semantic-model
+        
+        Args:
+            workspace_id: The workspace ID where the semantic model will be created
+            display_name: Display name for the semantic model
+            description: Optional description
+            definition: Optional semantic model definition
+            
+        Returns:
+            Created semantic model details
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels"
+        
+        payload = {
+            "displayName": display_name
+        }
+        
+        if description:
+            payload["description"] = description
+        
+        if definition:
+            payload["definition"] = definition
+        
+        response = self._make_request("POST", endpoint, data=payload)
+        return response.json()
+    
+    def get_semantic_model(
+        self,
+        workspace_id: str,
+        semantic_model_id: str
+    ) -> Dict[str, Any]:
+        """
+        Get a Semantic Model by ID
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/get-semantic-model
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID
+            
+        Returns:
+            Semantic model details
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}"
+        response = self._make_request("GET", endpoint)
+        return response.json()
+    
+    def list_semantic_models(
+        self,
+        workspace_id: str,
+        continuation_token: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        List all Semantic Models in a workspace
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/list-semantic-models-definition
+        
+        Args:
+            workspace_id: The workspace ID
+            continuation_token: Optional token for pagination
+            
+        Returns:
+            List of semantic models
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels"
+        params = {}
+        
+        if continuation_token:
+            params["continuationToken"] = continuation_token
+        
+        response = self._make_request("GET", endpoint, params=params)
+        return response.json()
+    
+    def get_semantic_model_definition(
+        self,
+        workspace_id: str,
+        semantic_model_id: str,
+        format: Optional[str] = None,
+        save_to_folder: bool = False,
+        output_folder: Optional[str] = None,
+        use_model_id_as_folder: bool = False,
+        wait_for_completion: bool = True,
+        max_retries: int = 30,
+        retry_delay: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Get a Semantic Model's definition with optional waiting and saving
+        
+        This unified method handles:
+        - Getting the definition
+        - Waiting for long-running operations (optional)
+        - Saving to folder structure (optional)
+        - Auto-naming folders based on model name or ID
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/get-semantic-model-definition
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID
+            format: Optional format for the definition (e.g., "TMSL", "TMDL")
+            save_to_folder: If True, saves definition to folder structure (default: False)
+            output_folder: Root folder to save files (optional, auto-generated if not provided)
+            use_model_id_as_folder: If True, uses model ID as folder name instead of display name (default: False)
+            wait_for_completion: If True, waits for long-running operations (default: True)
+            max_retries: Maximum number of polling attempts (default: 30)
+            retry_delay: Seconds to wait between retries (default: 5)
+            
+        Returns:
+            Dictionary containing:
+            - 'definition': The semantic model definition
+            - 'saved_files': List of saved file paths (if save_to_folder=True)
+            - 'output_folder': The folder path used (if save_to_folder=True)
+            - 'model_info': Semantic model metadata (if save_to_folder=True or output_folder=None)
+        """
+        # Step 1: Initiate the get definition request
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}/getDefinition"
+        
+        payload = {}
+        if format:
+            payload["format"] = format
+        
+        response = self._make_request("POST", endpoint, data=payload)
+        
+        # Step 2: Handle the response
+        # Check if it's a long-running operation (202 Accepted)
+        if response.status_code == 202:
+            if not wait_for_completion:
+                # Return operation info without waiting
+                return {
+                    "status": "Accepted",
+                    "status_code": 202,
+                    "x-ms-operation-id": response.headers.get("x-ms-operation-id"),
+                    "retry_after": response.headers.get("Retry-After"),
+                    "message": "Long-running operation started. Use the location header to check status."
+                }
+            
+            # Wait for operation to complete
+            operation_id = response.headers.get("x-ms-operation-id")
+            if operation_id:
+                print(f"Long-running operation started (ID: {operation_id})")
+                print(f"Waiting for operation to complete (checking every {retry_delay}s)...")
+                result = self.get_operation_result(operation_id, max_retries, retry_delay)
+            else:
+                raise Exception("Operation accepted but no operation ID returned")
+        else:
+            # Immediate response
+            if response.text:
+                result = response.json()
+            else:
+                result = {
+                    "status": "Success",
+                    "status_code": response.status_code,
+                    "message": "Request completed but no content returned"
+                }
+        
+        # Step 3: Extract definition from result
+        if "definition" in result:
+            definition = result["definition"]
+        elif "format" in result and "parts" in result:
+            # Already the definition object
+            definition = result
+        else:
+            # Return as-is if not a standard definition format
+            return result
+        
+        # Step 4: Prepare response
+        response_data = {
+            "definition": definition
+        }
+        
+        # Step 5: Save to folder if requested
+        if save_to_folder:
+            # Determine folder name if not provided
+            if output_folder is None:
+                if use_model_id_as_folder:
+                    # Use semantic model ID as folder name
+                    output_folder = semantic_model_id
+                    print(f"Using model ID as folder: '{output_folder}'\n")
+                else:
+                    # Use semantic model display name as folder name
+                    print("Getting semantic model information...")
+                    model_info = self.get_semantic_model(workspace_id, semantic_model_id)
+                    model_name = model_info.get("displayName", f"semantic_model_{semantic_model_id}")
+                    
+                    # Clean the name for use as folder name (remove invalid characters)
+                    import re
+                    output_folder = re.sub(r'[<>:"/\\|?*]', "_", model_name)
+                    print(f"Using model name as folder: '{output_folder}'\n")
+                    
+                    response_data["model_info"] = model_info
+            
+            # Save to folder structure
+            saved_files = self.save_definition_to_folder(definition, output_folder)
+            response_data["saved_files"] = saved_files
+            response_data["output_folder"] = output_folder
+        
+        return response_data
+    
+    def get_operation_result(
+        self,
+        operation_id: str,
+        max_retries: int = 30,
+        retry_delay: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Poll a long-running operation until completion and retrieve the result
+        
+        Args:
+            operation_id: The operation ID from the x-ms-operation-id header
+            max_retries: Maximum number of polling attempts (default: 30)
+            retry_delay: Seconds to wait between retries (default: 5)
+            
+        Returns:
+            Operation result data
+            
+        Raises:
+            Exception: If operation fails or times out
+        """
+        # Construct the operation status URL
+        status_url = f"https://api.fabric.microsoft.com/v1/operations/{operation_id}"
+        
+        for attempt in range(max_retries):
+            response = requests.get(
+                status_url,
+                headers={"Authorization": f"Bearer {self.config.access_token}"}
+            )
+            response.raise_for_status()
+            
+            result = response.json()
+            status = result.get("status", "").lower()
+            
+            if status in ["succeeded"]:
+                # When operation is done, try to fetch the result from the /result endpoint
+                result_url = f"https://api.fabric.microsoft.com/v1/operations/{operation_id}/result"
+                
+                print("Operation completed. Checking for result...")
+                result_response = requests.get(
+                    result_url,
+                    headers={"Authorization": f"Bearer {self.config.access_token}"}
+                )
+                
+                # Some operations (like update) don't have results, only status
+                if result_response.status_code == 200:
+                    # Return the actual result data
+                    return result_response.json()
+                elif result_response.status_code == 400:
+                    # Check if it's "OperationHasNoResult" error
+                    try:
+                        error_data = result_response.json()
+                        if error_data.get("errorCode") == "OperationHasNoResult":
+                            # Operation succeeded but has no result data, return status info
+                            print("Operation completed successfully (no result data)")
+                            return result
+                    except:
+                        pass
+                    # Re-raise for other 400 errors
+                    result_response.raise_for_status()
+                else:
+                    result_response.raise_for_status()
+                    
+            elif status == "failed":
+                error_details = result.get("error", result)
+                raise Exception(f"Operation failed: {error_details}")
+            elif status in ["running", "notstarted", "inprogress"]:
+                if attempt < max_retries - 1:
+                    print(f"Operation status: {status}. Waiting {retry_delay}s... (attempt {attempt + 1}/{max_retries})")
+                    time.sleep(retry_delay)
+                    continue
+            else:
+                # Unknown status, return as-is
+                print(f"Warning: Unknown operation status: {status}")
+                return result
+        
+        raise Exception(f"Operation timed out after {max_retries} attempts")
+    
+    def update_semantic_model(
+        self,
+        workspace_id: str,
+        semantic_model_id: str,
+        display_name: Optional[str] = None,
+        description: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Update a Semantic Model's metadata
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/update-semantic-model
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID
+            display_name: New display name
+            description: New description
+            
+        Returns:
+            Updated semantic model details
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}"
+        
+        payload = {}
+        if display_name:
+            payload["displayName"] = display_name
+        if description:
+            payload["description"] = description
+        
+        response = self._make_request("PATCH", endpoint, data=payload)
+        return response.json()
+    
+    def update_semantic_model_definition(
+        self,
+        workspace_id: str,
+        semantic_model_id: str,
+        definition: Optional[Dict[str, Any]] = None,
+        definition_folder: Optional[str] = None,
+        update_metadata: bool = True,
+        wait_for_completion: bool = True,
+        max_retries: int = 30,
+        retry_delay: int = 5
+    ) -> Dict[str, Any]:
+        """
+        Update semantic model definition from either a definition object or folder structure
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/update-semantic-model-definition
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID
+            definition: Definition object with 'format' and 'parts' (optional if definition_folder provided)
+            definition_folder: Path to folder containing model files (optional if definition provided)
+            update_metadata: If True, updates item metadata from .platform file (default: True)
+            wait_for_completion: Wait for the operation to complete (default: True)
+            max_retries: Maximum number of polling attempts (default: 30)
+            retry_delay: Delay in seconds between polling attempts (default: 5)
+            
+        Returns:
+            Dictionary with operation status and result
+            
+        Note:
+            - When update_metadata=True and .platform file is in definition, the item's 
+              metadata (display name, description) will be updated from the .platform file
+            - The update always replaces the entire definition (Full update)
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}/updateDefinition"
+        
+        # Build definition from folder if provided
+        if definition_folder and not definition:
+            print(f"Building definition from folder: {definition_folder}")
+            definition = self._build_definition_from_folder(definition_folder)
+        
+        if not definition:
+            raise ValueError("Either 'definition' or 'definition_folder' must be provided")
+        
+        # Prepare request body according to API spec
+        payload = {
+            "definition": definition,
+            "updateMetadata": update_metadata
+        }
+        
+        print("Updating semantic model definition...")
+        print(f"Update metadata from .platform file: {update_metadata}")
+        print(f"Number of parts: {len(definition.get('parts', []))}\n")
+        
+        # Make the request
+        response = self._make_request("POST", endpoint, data=payload)
+        
+        # Handle long-running operation (202 Accepted)
+        if response.status_code == 202:
+            if not wait_for_completion:
+                return {
+                    "status": "Accepted",
+                    "message": "Update initiated. Operation is running.",
+                    "location": response.headers.get("Location"),
+                    "retry_after": response.headers.get("Retry-After")
+                }
+            
+            # Extract operation ID from Location header
+            operation_id = response.headers.get("x-ms-operation-id")
+            
+            if not operation_id:
+                raise ValueError("No operation ID found in response headers")
+            
+            print(f"Long-running operation initiated. Operation ID: {operation_id}")
+            print("Polling for completion...\n")
+            
+            # Wait for operation to complete (update operations don't return result data)
+            status_url = f"https://api.fabric.microsoft.com/v1/operations/{operation_id}"
+            
+            for attempt in range(max_retries):
+                status_response = requests.get(
+                    status_url,
+                    headers={"Authorization": f"Bearer {self.config.access_token}"}
+                )
+                status_response.raise_for_status()
+                
+                operation_status = status_response.json()
+                status = operation_status.get("status", "").lower()
+                
+                if status == "succeeded":
+                    print("✓ Operation completed successfully!")
+                    return {
+                        "status": "Completed",
+                        "message": "Definition updated successfully",
+                        "operation_details": operation_status
+                    }
+                elif status == "failed":
+                    error_details = operation_status.get("error", operation_status)
+                    raise Exception(f"Operation failed: {error_details}")
+                elif status in ["running", "notstarted", "inprogress"]:
+                    if attempt < max_retries - 1:
+                        print(f"Operation status: {status}. Waiting {retry_delay}s... (attempt {attempt + 1}/{max_retries})")
+                        time.sleep(retry_delay)
+                        continue
+                else:
+                    print(f"Warning: Unknown operation status: {status}")
+                    
+            raise Exception(f"Operation timed out after {max_retries} attempts")
+        
+        # Handle immediate success (200 OK)
+        elif response.status_code == 200:
+            return {
+                "status": "Completed",
+                "message": "Definition updated successfully"
+            }
+        
+        # Unexpected response
+        else:
+            return {
+                "status": "Unknown",
+                "status_code": response.status_code,
+                "response": response.text
+            }
+    
+    def _build_definition_from_folder(
+        self,
+        folder_path: str,
+        format_type: str = "TMDL"
+    ) -> Dict[str, Any]:
+        """
+        Build definition object from folder structure by encoding files to Base64
+        
+        Args:
+            folder_path: Path to folder containing model files
+            format_type: Definition format (default: "TMDL")
+            
+        Returns:
+            Definition object with 'format' and 'parts'
+        """
+        folder = Path(folder_path)
+        if not folder.exists():
+            raise FileNotFoundError(f"Folder not found: {folder_path}")
+        
+        parts = []
+        
+        # Walk through all files in the folder
+        for file_path in folder.rglob("*"):
+            if file_path.is_file():
+                # Get relative path from root folder
+                relative_path = file_path.relative_to(folder)
+                path_str = str(relative_path).replace("\\", "/")
+                
+                # Read file content
+                try:
+                    with open(file_path, "r", encoding="utf-8") as f:
+                        content = f.read()
+                    
+                    # Encode to Base64
+                    encoded_content = base64.b64encode(content.encode("utf-8")).decode("utf-8")
+                    
+                    # Add to parts
+                    parts.append({
+                        "path": path_str,
+                        "payload": encoded_content,
+                        "payloadType": "InlineBase64"
+                    })
+                    
+                    print(f"  ✓ Added: {path_str}")
+                    
+                except Exception as e:
+                    print(f"  ✗ Failed to read {path_str}: {e}")
+        
+        print(f"\nTotal files processed: {len(parts)}\n")
+        
+        return {
+            "format": format_type,
+            "parts": parts
+        }
+    
+    def delete_semantic_model(
+        self,
+        workspace_id: str,
+        semantic_model_id: str
+    ) -> None:
+        """
+        Delete a Semantic Model
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/delete-semantic-model
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID to delete
+            
+        Returns:
+            None (204 No Content on success)
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}"
+        self._make_request("DELETE", endpoint)
+    
+    def save_definition_to_folder(
+        self,
+        definition_data: Dict[str, Any],
+        output_folder: str = "model_definition"
+    ) -> List[str]:
+        """
+        Save semantic model definition parts to folder structure
+        
+        Args:
+            definition_data: The definition object from API response (containing 'format' and 'parts')
+            output_folder: Root folder to save files (default: "model_definition")
+            
+        Returns:
+            List of saved file paths
+        """
+        # Get format and parts
+        format_type = definition_data.get("format", "TMDL")
+        parts = definition_data.get("parts", [])
+        
+        print(f"Format: {format_type}")
+        print(f"Number of parts: {len(parts)}\n")
+        
+        # Create output folder
+        output_path = Path(output_folder)
+        output_path.mkdir(parents=True, exist_ok=True)
+        
+        saved_files = []
+        
+        # Process each part
+        for part in parts:
+            file_path = part.get("path", "")
+            payload = part.get("payload", "")
+            payload_type = part.get("payloadType", "")
+            
+            if not file_path or not payload:
+                print("⚠ Skipping part with missing path or payload")
+                continue
+            
+            # Decode payload based on type
+            if payload_type == "InlineBase64":
+                try:
+                    decoded_content = base64.b64decode(payload).decode("utf-8")
+                except Exception as e:
+                    print(f"✗ Failed to decode {file_path}: {e}")
+                    continue
+            else:
+                # If not base64, assume it's plain text
+                decoded_content = payload
+            
+            # Create full file path
+            full_path = output_path / file_path
+            
+            # Create parent directories
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            # Write file
+            try:
+                with open(full_path, "w", encoding="utf-8") as f:
+                    f.write(decoded_content)
+                
+                print(f"✓ Saved: {file_path}")
+                saved_files.append(str(full_path))
+            except Exception as e:
+                print(f"✗ Failed to save {file_path}: {e}")
+        
+        print(f"\n{'=' * 60}")
+        print(f"Summary: Saved {len(saved_files)} files to '{output_folder}'")
+        print(f"{'=' * 60}")
+        
+        return saved_files
+    
+    def bind_semantic_model_connection(
+        self,
+        workspace_id: str,
+        semantic_model_id: str,
+        connection_id: str
+    ) -> None:
+        """
+        Bind a connection to a Semantic Model
+        
+        Reference: https://learn.microsoft.com/en-us/rest/api/fabric/semanticmodel/items/bind-semantic-model-connection
+        
+        Args:
+            workspace_id: The workspace ID
+            semantic_model_id: The semantic model ID
+            connection_id: The connection ID to bind
+            
+        Returns:
+            None (200 OK on success)
+        """
+        endpoint = f"workspaces/{workspace_id}/semanticModels/{semantic_model_id}/bindConnection"
+        
+        payload = {
+            "connectionId": connection_id
+        }
+        
+        self._make_request("POST", endpoint, data=payload)
+
+
+# Example usage
+if __name__ == "__main__":
+    print("SemanticModelClient - Client for Fabric Semantic Models")
+    print("\nExample usage:")
+    print("  from semantic_model_client import SemanticModelClient")
+    print("  client = SemanticModelClient()")
+    print("  client.list_semantic_models(workspace_id)")
+

fabricpandas/utils/__init__.py

@@ -0,0 +1,6 @@
+"""
+Utility functions for FabricPandas
+"""
+
+__all__ = []
+

fabricpandas/workspace/__init__.py

@@ -0,0 +1,8 @@
+"""
+Workspace module for FabricPandas
+"""
+
+from .workspace_client import WorkspaceClient
+
+__all__ = ["WorkspaceClient"]
+