stepxmlclient 1.0.0__py3-none-any.whl

stepxmlclient/rest_client/operations/exports.py

@@ -0,0 +1,153 @@
+"""Export and Import operations for STEP REST API v2."""
+
+import logging
+from typing import Any, Optional
+
+from ..base import BaseOperation, handle_rest_errors
+from ..exceptions import NotFoundError, ValidationError
+from ..models.import_export import (
+    BackgroundProcessResponse,
+    ExportJobCreateRequest,
+)
+
+
+class ExportOperations(BaseOperation):
+    """Operations for STEP data exports and imports."""
+
+    def __init__(self, client, logger: Optional[logging.Logger] = None,
+                 context: str | None = None, workspace: str | None = None):
+        """Initialize export operations.
+
+        Args:
+            client: The REST API client
+            logger: Optional logger instance
+            context: STEP context ID for all API calls
+            workspace: STEP workspace ID (defaults to "Main" server-side)
+        """
+        super().__init__(client, operation_name="ExportOperations", logger=logger,
+                         context=context, workspace=workspace)
+
+    @handle_rest_errors
+    def create_export_job(self, export_configuration_id: str,
+                          data: Optional[ExportJobCreateRequest] = None,
+                          use_request_context_workspace: Optional[bool] = None) -> BackgroundProcessResponse:
+        """Trigger an export using a pre-configured export configuration (POST /export/{exportConfigurationId}).
+
+        Args:
+            export_configuration_id: The ID of the export configuration to use (required)
+            data: Optional request body with additional export parameters
+            use_request_context_workspace: If True, use the workspace from the request context
+
+        Returns:
+            ExportJobResponse with job details
+
+        Raises:
+            ValidationError: If export_configuration_id is missing or data is invalid
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"export_configuration_id": export_configuration_id},
+            ["export_configuration_id"]
+        )
+
+        if data is not None:
+            if hasattr(data, 'model_dump'):
+                create_data = data.model_dump(exclude_none=True)
+            else:
+                create_data = dict(data) if not isinstance(data, dict) else data
+        else:
+            create_data = None
+
+        query_params: dict = self._build_context_params()
+        if use_request_context_workspace is not None:
+            query_params["useRequestContextWorkspace"] = use_request_context_workspace
+
+        self._log_operation("startExport", {"exportConfigurationId": export_configuration_id})
+
+        try:
+            if create_data:
+                response = self.client.startExport(exportConfigurationId=export_configuration_id, json=create_data, **query_params)
+            else:
+                response = self.client.startExport(exportConfigurationId=export_configuration_id, **query_params)
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(export_configuration_id, "ExportConfiguration")
+            if "400" in str(e):
+                raise ValidationError(f"Export failed: {str(e)}")
+            raise
+
+        self._check_for_api_error(response, export_configuration_id, "ExportConfiguration")
+        if isinstance(response, dict):
+            return BackgroundProcessResponse(**response)
+        return response
+
+    @handle_rest_errors
+    def create_import_job(self, import_configuration_id: str,
+                          data: Optional[object] = None,
+                          process_description: str | None = None) -> BackgroundProcessResponse:
+        """Trigger an import using a pre-configured import configuration (POST /import/{importConfigurationId}).
+
+        Args:
+            import_configuration_id: The ID of the import configuration to use (required)
+            data: Optional request body with import payload
+            process_description: Optional human-readable description for the import process
+
+        Returns:
+            BackgroundProcessResponse with job/process details
+
+        Raises:
+            ValidationError: If import_configuration_id is missing or data is invalid
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"import_configuration_id": import_configuration_id},
+            ["import_configuration_id"]
+        )
+
+        query_params = self._build_context_params()
+        if process_description:
+            query_params["processDescription"] = process_description
+
+        self._log_operation("startImport", {"importConfigurationId": import_configuration_id})
+
+        try:
+            if data is not None:
+                # Binary data: convert to bytes if needed
+                if isinstance(data, str):
+                    binary_data = data.encode('utf-8')
+                elif isinstance(data, bytes):
+                    binary_data = data
+                else:
+                    # For Pydantic models or dicts, convert to JSON bytes
+                    import json
+                    
+                    from pydantic import BaseModel
+                    if isinstance(data, BaseModel):
+                        binary_data = json.dumps(data.model_dump(exclude_none=True)).encode('utf-8')
+                    else:
+                        binary_data = json.dumps(data).encode('utf-8')
+                
+                response = self.client.startImport(
+                    importConfigurationId=import_configuration_id,
+                    data=binary_data,
+                    **query_params
+                )
+                response_dict: dict[str, Any] = response if isinstance(response, dict) else {"success": True}
+            else:
+                response = self.client.startImport(
+                    importConfigurationId=import_configuration_id,
+                    **query_params
+                )
+                response_dict: dict[str, Any] = response if isinstance(response, dict) else {"success": True}
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(import_configuration_id, "ImportConfiguration")
+            if "400" in str(e):
+                raise ValidationError(f"Import failed: {e!s}")
+            raise
+
+        self._check_for_api_error(response_dict, import_configuration_id, "ImportConfiguration")
+        if isinstance(response_dict, dict):
+            return BackgroundProcessResponse(**response_dict)
+        return response_dict
+    

stepxmlclient/rest_client/operations/gateway.py

@@ -0,0 +1,53 @@
+"""Gateway integration endpoint operations for STEP REST API v2."""
+from typing import Any
+
+from ..base import BaseOperation, handle_rest_errors
+from ..exceptions import NotFoundError
+from ..models.integration_endpoint import IntegrationEndpointResponse
+
+
+class GatewayOperations(BaseOperation):
+    def __init__(self, client, logger=None, context=None, workspace=None):
+        super().__init__(client, operation_name="GatewayOperations", logger=logger, context=context, workspace=workspace)
+
+    @handle_rest_errors
+    def get_gateway_endpoints(self) -> list[dict[str, Any]]:
+        self._log_operation("getGatewayIntegrationEndpoints", {})
+        r = self.client.getGatewayIntegrationEndpoints(**self._build_context_params())
+        return r if isinstance(r, list) else []
+
+    @handle_rest_errors
+    def get_gateway_endpoint(self, ep_id: str) -> IntegrationEndpointResponse:
+        self._validate_required_params({"ep_id": ep_id}, ["ep_id"])
+        self._log_operation("getGatewayIntegrationEndpoint", {"id": ep_id})
+        try:
+            r = self.client.getGatewayIntegrationEndpoint(id=ep_id, **self._build_context_params())
+        except Exception as e:
+            if "404" in str(e): raise NotFoundError(ep_id, "GatewayIntegrationEndpoint")
+            raise
+        return IntegrationEndpointResponse(**r) if isinstance(r, dict) else r
+
+    @handle_rest_errors
+    def get_gateway_endpoint_status(self, ep_id: str) -> IntegrationEndpointResponse:
+        self._validate_required_params({"ep_id": ep_id}, ["ep_id"])
+        self._log_operation("getGatewayIntegrationEndpointStatus", {"id": ep_id})
+        try:
+            r = self.client.getGatewayIntegrationEndpointStatus(id=ep_id, **self._build_context_params())
+        except Exception as e:
+            if "404" in str(e): raise NotFoundError(ep_id, "GatewayIntegrationEndpoint")
+            raise
+        return IntegrationEndpointResponse(**r) if isinstance(r, dict) else r
+
+    @handle_rest_errors
+    def enable_gateway_endpoint(self, ep_id: str) -> IntegrationEndpointResponse:
+        self._validate_required_params({"ep_id": ep_id}, ["ep_id"])
+        self._log_operation("enableGatewayIntegrationEndpoint", {"id": ep_id})
+        r = self.client.enableGatewayIntegrationEndpoint(id=ep_id, **self._build_context_params())
+        return IntegrationEndpointResponse(**r) if isinstance(r, dict) else r
+
+    @handle_rest_errors
+    def disable_gateway_endpoint(self, ep_id: str) -> IntegrationEndpointResponse:
+        self._validate_required_params({"ep_id": ep_id}, ["ep_id"])
+        self._log_operation("disableGatewayIntegrationEndpoint", {"id": ep_id})
+        r = self.client.disableGatewayIntegrationEndpoint(id=ep_id, **self._build_context_params())
+        return IntegrationEndpointResponse(**r) if isinstance(r, dict) else r

stepxmlclient/rest_client/operations/inbound.py

@@ -0,0 +1,472 @@
+"""Inbound Integration Endpoint operations for STEP REST API v2.
+
+Provides high-level operations for uploading STEP-XML to Inbound Integration Endpoints
+and managing their status, including enabling/disabling endpoints and retrieving execution reports.
+"""
+
+import logging
+from typing import Any, Optional, Union
+
+from ..base import BaseOperation, handle_rest_errors
+from ..exceptions import NotFoundError, RestApiError, ValidationError
+
+
+class InboundOperations(BaseOperation):
+    """Operations for STEP Inbound Integration Endpoints (IIEP).
+    
+    Handles uploading STEP-XML documents to configured inbound endpoints
+    and managing endpoint status and execution reports.
+    
+    Example:
+        ```python
+        from stepxmlclient.rest_client.client import StepRestClient
+        from stepxmlclient.creator import Creator
+        
+        # Create and setup client
+        client = StepRestClient(
+            location_base="https://your-step.com/restapiv2",
+            authorisation=auth,
+            context="Context1"
+        )
+        
+        # Generate STEP-XML
+        creator = Creator(context_id="Context1")
+        # ... add products, assets, etc ...
+        creator.build()
+        xml_bytes = creator.to_bytes()
+        
+        # Send to inbound endpoint
+        result = client.inbound.upload_and_invoke(
+            endpoint_id="my_inbound_endpoint",
+            xml_data=xml_bytes,
+            file_name="import_data.xml"
+        )
+        
+        print(f"Uploaded {result.get('processId')} to endpoint")
+        ```
+    """
+    
+    def __init__(self, client, logger: Optional[logging.Logger] = None,
+                 context: str | None = None, workspace: str | None = None):
+        """Initialize inbound operations.
+        
+        Args:
+            client: The REST API client
+            logger: Optional logger instance
+            context: STEP context ID for all API calls (required)
+            workspace: STEP workspace ID (defaults to "Main" server-side)
+        """
+        super().__init__(client, operation_name="InboundOperations", logger=logger,
+                         context=context, workspace=workspace)
+
+    @handle_rest_errors
+    def upload_and_invoke(self, endpoint_id: str, xml_data: Union[bytes, str],
+                          file_name: str | None = None) -> dict[str, Any]:
+        """Upload STEP-XML to an inbound endpoint and trigger processing.
+        
+        Posts STEP-XML content to a configured Inbound Integration Endpoint
+        with a REST receiver plugin. The endpoint is immediately invoked
+        to process the uploaded data.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint (required)
+            xml_data: STEP-XML content as bytes or string
+            file_name: Optional filename hint for the upload (e.g., "import_data.xml")
+            
+        Returns:
+            Dictionary with response details (typically includes processId or similar)
+            
+        Raises:
+            ValidationError: If endpoint_id is missing or endpoint not enabled
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For other API errors
+            
+        Note:
+            - Endpoint must have status "enabled" to invoke
+            - Endpoint must have a REST-enabled receiver plugin configured
+            - The endpoint will begin processing immediately
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id, "xml_data": xml_data},
+            ["endpoint_id", "xml_data"]
+        )
+
+        # Convert string to bytes if needed
+        if isinstance(xml_data, str):
+            xml_data = xml_data.encode('utf-8')
+
+        # Prepare query parameters (context and workspace, plus optional fileName)
+        params: dict[str, Any] = {}
+        if file_name:
+            params["fileName"] = file_name
+        params.update(self._build_context_params())
+
+        self._log_operation("uploadFileToAndInvokeInboundRestEndpoint", {
+            "endpointId": endpoint_id,
+            "fileSize": len(xml_data),
+            "fileName": file_name or "(not specified)"
+        })
+
+        requestor = getattr(self.client, "requestor", None)
+        server_url = None
+        server = getattr(self.client, "server", None)
+        if server is not None:
+            server_url = getattr(server, "url", None)
+        if not server_url:
+            server_url = getattr(self.client, "_server", None)
+            if server_url is not None:
+                server_url = getattr(server_url, "url", None)
+
+        try:
+            if requestor is not None and hasattr(requestor, "post") and server_url:
+                url = f"{server_url.rstrip('/')}/inbound-integration-endpoints/{endpoint_id}/upload-and-invoke"
+                response = requestor.post(url, data=xml_data, params=params, timeout=120)
+                try:
+                    response.raise_for_status()
+                except Exception as exc:
+                    error_str = str(exc)
+                    if "404" in error_str:
+                        raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+                    elif "400" in error_str:
+                        if "not enabled" in error_str.lower() or "disabled" in error_str.lower():
+                            raise ValidationError(
+                                f"Inbound endpoint '{endpoint_id}' is not enabled. "
+                                f"Enable it first using enable_endpoint()."
+                            )
+                        elif "REST receiver" in error_str:
+                            raise ValidationError(
+                                f"Inbound endpoint '{endpoint_id}' does not have a REST-enabled receiver plugin. "
+                                f"Configure a REST receiver in the endpoint settings."
+                            )
+                        raise ValidationError(f"Upload failed: {error_str}")
+                    elif "503" in error_str:
+                        raise RestApiError(503, "Endpoint temporarily unavailable", details=error_str)
+                    raise
+
+                if isinstance(response, dict):
+                    return response
+                if hasattr(response, "json"):
+                    try:
+                        payload = response.json()
+                    except Exception:
+                        payload = None
+                    if isinstance(payload, dict):
+                        return payload
+                return {"success": True, "endpoint": endpoint_id}
+
+            # Fallback to generated OpenAPI operation when a requestor is not available.
+            response = self.client.uploadFileToAndInvokeInboundRestEndpoint(
+                id=endpoint_id,
+                data=xml_data,
+                **params
+            )
+
+            if isinstance(response, dict):
+                return response
+            if hasattr(response, "json"):
+                try:
+                    payload = response.json()
+                except Exception:  # noqa: BLE001
+                    payload = None
+                if isinstance(payload, dict):
+                    return payload
+            return {"success": True, "endpoint": endpoint_id}
+
+        except Exception as e:
+            error_str = str(e)
+            if "404" in error_str:
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            elif "400" in error_str:
+                if "not enabled" in error_str.lower() or "disabled" in error_str.lower():
+                    raise ValidationError(
+                        f"Inbound endpoint '{endpoint_id}' is not enabled. "
+                        f"Enable it first using enable_endpoint()."
+                    )
+                elif "REST receiver" in error_str:
+                    raise ValidationError(
+                        f"Inbound endpoint '{endpoint_id}' does not have a REST-enabled receiver plugin. "
+                        f"Configure a REST receiver in the endpoint settings."
+                    )
+                raise ValidationError(f"Upload failed: {error_str}")
+            elif "503" in error_str:
+                raise RestApiError(503, "Endpoint temporarily unavailable", details=error_str)
+            raise
+
+
+    @handle_rest_errors
+    def list_endpoints(self) -> list[dict[str, Any]]:
+        """Get all accessible inbound integration endpoints.
+        
+        Returns:
+            List of inbound endpoint representations with ID, name, and status info
+            
+        Raises:
+            RestApiError: For API errors
+        """
+        params = self._build_context_params()
+
+        self._log_operation("getInboundIntegrationEndpoints", {})
+
+        try:
+            response = self.client.getInboundIntegrationEndpoints(**params)
+        except Exception as e:
+            raise RestApiError(0, f"Failed to list inbound endpoints: {str(e)}", details=str(e))
+
+        return self._coerce_list_payload(response)
+
+    @handle_rest_errors
+    def get_status(self, endpoint_id: str) -> dict[str, Any]:
+        """Get the current status of an inbound endpoint.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            
+        Returns:
+            Dictionary with status information (status, enabled state, etc.)
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        self._log_operation("getInboundIntegrationEndpointStatus", {
+            "endpointId": endpoint_id
+        })
+
+        try:
+            response = self.client.getInboundIntegrationEndpointStatus(
+                id=endpoint_id,
+                **self._build_context_params()
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        if isinstance(response, dict):
+            return response
+        return {"endpoint": endpoint_id}
+
+    @handle_rest_errors
+    def enable_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        """Enable an inbound integration endpoint.
+        
+        Enables the endpoint so it can receive and process uploads.
+        If endpoint has status "failed", this will resume it.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            
+        Returns:
+            Response from the enable operation
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        self._log_operation("enableInboundIntegrationEndpoint", {
+            "endpointId": endpoint_id
+        })
+
+        try:
+            response = self.client.enableInboundIntegrationEndpoint(
+                id=endpoint_id,
+                **self._build_context_params()
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        if isinstance(response, dict):
+            return response
+        return {"success": True, "endpoint": endpoint_id, "action": "enabled"}
+
+    @handle_rest_errors
+    def disable_endpoint(self, endpoint_id: str) -> dict[str, Any]:
+        """Disable an inbound integration endpoint.
+        
+        Disables the endpoint so it will not accept uploads or process data.
+        Can be called regardless of the endpoint's current status.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            
+        Returns:
+            Response from the disable operation
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        self._log_operation("disableInboundIntegrationEndpoint", {
+            "endpointId": endpoint_id
+        })
+
+        try:
+            response = self.client.disableInboundIntegrationEndpoint(
+                id=endpoint_id,
+                **self._build_context_params()
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        if isinstance(response, dict):
+            return response
+        return {"success": True, "endpoint": endpoint_id, "action": "disabled"}
+
+    @handle_rest_errors
+    def get_execution_report(self, endpoint_id: str) -> list[dict[str, Any]]:
+        """Get the execution report for an inbound endpoint's main process.
+        
+        Returns detailed information about the last execution or current state.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            
+        Returns:
+            List of execution report entries with details about operations performed
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        self._log_operation("getInboundIntegrationEndpointExecutionReport", {
+            "endpointId": endpoint_id
+        })
+
+        try:
+            response = self.client.getInboundIntegrationEndpointExecutionReport(
+                id=endpoint_id,
+                **self._build_context_params()
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        if isinstance(response, (list, dict)):
+            return self._coerce_list_payload(response)
+        if response is not None:
+            return [response]
+        return []
+
+    @handle_rest_errors
+    def get_statistics(self, endpoint_id: str) -> dict[str, Any]:
+        """Get statistics for an inbound integration endpoint.
+        
+        Returns operational statistics and metrics about the endpoint.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            
+        Returns:
+            Dictionary with statistics (message counts, error counts, etc.)
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        self._log_operation("getInboundIntegrationEndpointStatistics", {
+            "endpointId": endpoint_id
+        })
+
+        try:
+            response = self.client.getInboundIntegrationEndpointStatistics(
+                id=endpoint_id,
+                **self._build_context_params()
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        if isinstance(response, dict):
+            return response
+        return {}
+
+    @handle_rest_errors
+    def get_worker_processes(self, endpoint_id: str,
+                             status_filter: str | None = None) -> list[str]:
+        """Get background process IDs started by this endpoint.
+        
+        Args:
+            endpoint_id: ID of the inbound integration endpoint
+            status_filter: Optional filter by process status (PENDING, PROCESSING, COMPLETED, FAILED)
+            
+        Returns:
+            List of background process IDs
+            
+        Raises:
+            ValidationError: If endpoint_id is missing
+            NotFoundError: If endpoint cannot be found
+            RestApiError: For API errors
+        """
+        self._validate_required_params(
+            {"endpoint_id": endpoint_id},
+            ["endpoint_id"]
+        )
+
+        params: dict[str, Any] = self._build_context_params()
+        if status_filter:
+            params["status"] = status_filter
+
+        self._log_operation("getInboundIntegrationEndpointWorkerProcesses", {
+            "endpointId": endpoint_id,
+            "statusFilter": status_filter
+        })
+
+        try:
+            response = self.client.getInboundIntegrationEndpointWorkerProcesses(
+                id=endpoint_id,
+                **params
+            )
+        except Exception as e:
+            if "404" in str(e):
+                raise NotFoundError(endpoint_id, "InboundIntegrationEndpoint")
+            raise
+
+        self._check_for_api_error(response, endpoint_id, "InboundIntegrationEndpoint")
+
+        return self._coerce_list_payload(response)