pvw-cli 1.2.8__py3-none-any.whl

purviewcli/client/_domain.py

@@ -0,0 +1,414 @@
+"""
+Governance Domain Management Client for Microsoft Purview
+
+NOTE: Governance Domains are currently not available in the public Microsoft Purview REST API.
+This feature may be in preview, portal-only, or planned for future release.
+
+This client provides a foundation for when the API becomes available and includes
+alternative approaches for domain-like organization.
+"""
+
+from .endpoint import Endpoint
+from .endpoints import ENDPOINTS, DATAMAP_API_VERSION
+
+
+class Domain(Endpoint):
+    """Client for managing governance domains in Microsoft Purview."""
+
+    def __init__(self):
+        Endpoint.__init__(self)
+        self.app = "catalog"  # Use catalog app as fallback
+
+    def domainsList(self, args):
+        """
+Retrieve domain information.
+    
+    Retrieves detailed information about the specified domain.
+    Returns complete domain metadata and properties.
+    
+Args:
+        args: Dictionary of operation arguments.
+               Contains operation-specific parameters.
+               See method implementation for details.
+    
+Returns:
+        List of resource dictionaries, each containing:
+            - guid (str): Unique identifier
+            - name (str): Resource name
+            - attributes (dict): Resource attributes
+            - status (str): Resource status
+        
+        Returns empty list if no resources found.
+    
+Raises:
+        ValueError: When required parameters are missing or invalid:
+            - Empty or None values for required fields
+            - Invalid GUID format
+            - Out-of-range values
+        
+        AuthenticationError: When Azure credentials are invalid:
+            - DefaultAzureCredential not configured
+            - Insufficient permissions
+            - Expired authentication token
+        
+        HTTPError: When Purview API returns error:
+            - 400: Bad request (invalid parameters)
+            - 401: Unauthorized (authentication failed)
+            - 403: Forbidden (insufficient permissions)
+            - 404: Resource not found
+            - 429: Rate limit exceeded
+            - 500: Internal server error
+        
+        NetworkError: When network connectivity fails
+    
+Example:
+        # Basic usage
+        client = Domain()
+        
+        result = client.domainsList(args=...)
+        print(f"Result: {result}")
+    
+Use Cases:
+        - Data Discovery: Find and explore data assets
+        - Compliance Auditing: Review metadata and classifications
+        - Reporting: Generate catalog reports
+    """
+        result = {
+            "status": "not_available",
+            "message": "Governance Domains are not currently available in the public Microsoft Purview REST API. Please use the Azure portal to manage governance domains, or use collections as an alternative organizational structure.",
+            "alternatives": [
+                "Use collections to organize assets hierarchically",
+                "Use custom entity attributes to tag assets with domain information",
+                "Use glossary terms to create domain vocabularies",
+            ],
+        }
+        return result
+
+    def domainsCreate(self, args):
+        """
+Create a new domain.
+    
+    Creates a new domain in Microsoft Purview.
+    Requires appropriate permissions and valid domain definition.
+    
+Args:
+        args: Dictionary of operation arguments.
+               Contains operation-specific parameters.
+               See method implementation for details.
+    
+Returns:
+        Dictionary containing created domain:
+            {
+                'guid': str,         # Unique identifier
+                'name': str,         # Resource name
+                'status': str,       # Creation status
+                'attributes': dict,  # Resource attributes
+                'createTime': int    # Creation timestamp
+            }
+    
+Raises:
+        ValueError: When required parameters are missing or invalid:
+            - Empty or None values for required fields
+            - Invalid GUID format
+            - Out-of-range values
+        
+        AuthenticationError: When Azure credentials are invalid:
+            - DefaultAzureCredential not configured
+            - Insufficient permissions
+            - Expired authentication token
+        
+        HTTPError: When Purview API returns error:
+            - 400: Bad request (invalid parameters)
+            - 401: Unauthorized (authentication failed)
+            - 403: Forbidden (insufficient permissions)
+            - 404: Resource not found
+            - 409: Conflict (resource already exists)
+            - 429: Rate limit exceeded
+            - 500: Internal server error
+        
+        NetworkError: When network connectivity fails
+    
+Example:
+        # Basic usage
+        client = Domain()
+        
+        result = client.domainsCreate(args=...)
+        print(f"Result: {result}")
+        
+        # With detailed data
+        data = {
+            'name': 'My Resource',
+            'description': 'Resource description',
+            'attributes': {
+                'key1': 'value1',
+                'key2': 'value2'
+            }
+        }
+        
+        result = client.domainsCreate(data)
+        print(f"Created/Updated: {result['guid']}")
+    
+Use Cases:
+        - Data Onboarding: Register new data sources in catalog
+        - Metadata Management: Add descriptive metadata to assets
+        - Automation: Programmatically populate catalog
+    """
+        result = {
+            "status": "not_available",
+            "message": "Governance Domain creation is not currently available in the public Microsoft Purview REST API. Please use the Azure portal or consider using collections as an alternative.",
+            "suggested_action": f"Consider creating a collection named '{args.get('--name', 'unknown')}' instead using: pvw collections create --collection-name {args.get('--name', 'domain-name')}",
+        }
+        return result
+
+    def domainsGet(self, args):
+        """
+Retrieve domain information.
+    
+    Retrieves detailed information about the specified domain.
+    Returns complete domain metadata and properties.
+    
+Args:
+        args: Dictionary of operation arguments.
+               Contains operation-specific parameters.
+               See method implementation for details.
+    
+Returns:
+        Dictionary containing domain information:
+            {
+                'guid': str,          # Unique identifier
+                'name': str,          # Resource name
+                'attributes': dict,   # Resource attributes
+                'status': str,        # Resource status
+                'updateTime': int     # Last update timestamp
+            }
+    
+Raises:
+        ValueError: When required parameters are missing or invalid:
+            - Empty or None values for required fields
+            - Invalid GUID format
+            - Out-of-range values
+        
+        AuthenticationError: When Azure credentials are invalid:
+            - DefaultAzureCredential not configured
+            - Insufficient permissions
+            - Expired authentication token
+        
+        HTTPError: When Purview API returns error:
+            - 400: Bad request (invalid parameters)
+            - 401: Unauthorized (authentication failed)
+            - 403: Forbidden (insufficient permissions)
+            - 404: Resource not found
+            - 429: Rate limit exceeded
+            - 500: Internal server error
+        
+        NetworkError: When network connectivity fails
+    
+Example:
+        # Basic usage
+        client = Domain()
+        
+        result = client.domainsGet(args=...)
+        print(f"Result: {result}")
+    
+Use Cases:
+        - Data Discovery: Find and explore data assets
+        - Compliance Auditing: Review metadata and classifications
+        - Reporting: Generate catalog reports
+    """
+        domain_name = args.get("--domainName", "unknown")
+        result = {
+            "status": "not_available",
+            "message": f"Cannot retrieve governance domain '{domain_name}' - feature not available in public API",
+            "suggested_action": f"Try: pvw collections get --collection-name {domain_name}",
+        }
+        return result
+
+    def domainsUpdate(self, args):
+        """
+Update an existing domain.
+    
+    Updates an existing domain with new values.
+    Only specified fields are modified; others remain unchanged.
+    
+Args:
+        args: Dictionary of operation arguments.
+               Contains operation-specific parameters.
+               See method implementation for details.
+    
+Returns:
+        Dictionary containing updated domain:
+            {
+                'guid': str,          # Unique identifier
+                'attributes': dict,   # Updated attributes
+                'updateTime': int     # Update timestamp
+            }
+    
+Raises:
+        ValueError: When required parameters are missing or invalid:
+            - Empty or None values for required fields
+            - Invalid GUID format
+            - Out-of-range values
+        
+        AuthenticationError: When Azure credentials are invalid:
+            - DefaultAzureCredential not configured
+            - Insufficient permissions
+            - Expired authentication token
+        
+        HTTPError: When Purview API returns error:
+            - 400: Bad request (invalid parameters)
+            - 401: Unauthorized (authentication failed)
+            - 403: Forbidden (insufficient permissions)
+            - 404: Resource not found
+            - 429: Rate limit exceeded
+            - 500: Internal server error
+        
+        NetworkError: When network connectivity fails
+    
+Example:
+        # Basic usage
+        client = Domain()
+        
+        result = client.domainsUpdate(args=...)
+        print(f"Result: {result}")
+        
+        # With detailed data
+        data = {
+            'name': 'My Resource',
+            'description': 'Resource description',
+            'attributes': {
+                'key1': 'value1',
+                'key2': 'value2'
+            }
+        }
+        
+        result = client.domainsUpdate(data)
+        print(f"Created/Updated: {result['guid']}")
+    
+Use Cases:
+        - Metadata Enrichment: Update descriptions and tags
+        - Ownership Changes: Reassign data ownership
+        - Classification: Apply or modify data classifications
+    """
+        domain_name = args.get("--domainName", "unknown")
+        result = {
+            "status": "not_available",
+            "message": f"Cannot update governance domain '{domain_name}' - feature not available in public API",
+        }
+        return result
+
+    def domainsDelete(self, args):
+        """
+Delete a domain.
+    
+    Permanently deletes the specified domain.
+    This operation cannot be undone. Use with caution.
+    
+Args:
+        args: Dictionary of operation arguments.
+               Contains operation-specific parameters.
+               See method implementation for details.
+    
+Returns:
+        Dictionary with deletion status:
+            {
+                'guid': str,       # Deleted resource ID
+                'status': str,     # Deletion status
+                'message': str     # Confirmation message
+            }
+    
+Raises:
+        ValueError: When required parameters are missing or invalid:
+            - Empty or None values for required fields
+            - Invalid GUID format
+            - Out-of-range values
+        
+        AuthenticationError: When Azure credentials are invalid:
+            - DefaultAzureCredential not configured
+            - Insufficient permissions
+            - Expired authentication token
+        
+        HTTPError: When Purview API returns error:
+            - 400: Bad request (invalid parameters)
+            - 401: Unauthorized (authentication failed)
+            - 403: Forbidden (insufficient permissions)
+            - 404: Resource not found
+            - 429: Rate limit exceeded
+            - 500: Internal server error
+        
+        NetworkError: When network connectivity fails
+    
+Example:
+        # Basic usage
+        client = Domain()
+        
+        result = client.domainsDelete(args=...)
+        print(f"Result: {result}")
+    
+Use Cases:
+        - Data Cleanup: Remove obsolete or test data
+        - Decommissioning: Delete resources no longer in use
+        - Testing: Clean up test environments
+    """
+        domain_name = args.get("--domainName", "unknown")
+        result = {
+            "status": "not_available",
+            "message": f"Cannot delete governance domain '{domain_name}' - feature not available in public API",
+        }
+        return result
+
+    def get_api_version(self):
+        """
+        Get the API version string for governance domain (datamap) operations.
+
+        Returns:
+            str: The API version string (e.g., "2023-09-01") used for all domain-related endpoints.
+
+        Raises:
+            None: This method does not raise exceptions.
+
+        Example:
+            ```python
+            domain = Domain()
+            version = domain.get_api_version()
+            print(f"Using API version: {version}")
+            ```
+
+        Use Cases:
+            - Retrieve the current API version for documentation purposes
+            - Construct custom API requests with correct version parameter
+            - Validate API compatibility when integrating with other systems
+            - Log API version information for troubleshooting
+        """
+        return DATAMAP_API_VERSION
+
+    def get_api_version_params(self):
+        """
+        Get the API version parameter dictionary for governance domain operations.
+
+        Returns:
+            dict: Dictionary containing the API version parameter in the format
+                  {"api-version": "2023-09-01"} ready for use in HTTP requests.
+
+        Raises:
+            None: This method does not raise exceptions.
+
+        Example:
+            ```python
+            domain = Domain()
+            params = domain.get_api_version_params()
+            # Use in requests: requests.get(url, params=params)
+            print(params)  # {"api-version": "2023-09-01"}
+            ```
+
+        Use Cases:
+            - Automatically add correct API version to HTTP request parameters
+            - Ensure consistent API version across all domain operations
+            - Simplify request parameter construction when calling domain endpoints
+            - Maintain version compatibility when API versions change
+        """
+        return {"api-version": DATAMAP_API_VERSION}
+
+    # Example usage in a real API call (when available):
+    # version = self.get_api_version()
+    # params = self.get_api_version_params()
+    # ... use version/params in requests ...