stepxmlclient 1.0.0__py3-none-any.whl

stepxmlclient/rest_client/__init__.py

@@ -0,0 +1,16 @@
+"""REST API client for STEP REST API v2.
+
+Provides comprehensive, typed access to STEP REST API operations through
+organized operation groups with shared authentication.
+"""
+
+from . import exceptions
+from .base import BaseOperation, handle_rest_errors
+from .client import StepRestClient
+
+__all__ = [
+    'BaseOperation',
+    'StepRestClient',
+    'exceptions',
+    'handle_rest_errors',
+]

stepxmlclient/rest_client/base.py

@@ -0,0 +1,388 @@
+"""Base operation class for REST API operations.
+
+Provides common functionality for all operation classes including error handling,
+pagination, logging, and request/response processing.
+"""
+
+import logging
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+import requests
+import requests_openapi as roa
+
+from . import exceptions as exc
+from .models.common import PageInfo
+
+T = TypeVar('T')
+
+
+def handle_rest_errors(func: Callable) -> Callable:
+    """Decorator to handle common REST API errors.
+    
+    Converts HTTP errors to appropriate exception types.
+    Allows FileNotFoundError and other file system exceptions to pass through.
+
+    Also detects STEP API error responses returned as dicts when
+    requests_openapi does not raise an exception for non-2xx HTTP responses.
+    The STEP REST API returns error payloads with the form
+    ``{"httpStatus": <int>, "message": "...", "httpReason": "..."}``.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            result = func(*args, **kwargs)
+            # Detect STEP error responses returned as plain dicts instead of
+            # raised exceptions (requests_openapi may not call raise_for_status).
+            if isinstance(result, dict) and 'httpStatus' in result:
+                status = result.get('httpStatus', 0)
+                message = result.get('message') or result.get('httpReason', 'API error')
+                if status == 401:
+                    raise exc.AuthenticationError(f"Authentication failed: {message}")
+                elif status == 403:
+                    raise exc.AuthorizationError(f"Access denied: {message}")
+                elif status == 404:
+                    raise exc.NotFoundError(None, details=result)
+                elif status == 409:
+                    raise exc.ConflictError(status, message)
+                elif status == 429:
+                    raise exc.RateLimitError(details=result)
+                elif 500 <= status < 600:
+                    raise exc.ServerError(status, message)
+                elif 400 <= status < 500:
+                    raise exc.RestApiError(status, message)
+            return result
+        except requests.exceptions.RequestException as e:
+            # Handle requests library exceptions
+            if hasattr(e, 'response') and e.response is not None:
+                status = e.response.status_code
+                try:
+                    error_data = e.response.json()
+                except Exception:
+                    error_data = {"message": e.response.text}
+                
+                error_msg = error_data.get('error_message') or error_data.get('message', str(e))
+                error_code = error_data.get('error_code')
+                
+                if status == 401:
+                    raise exc.AuthenticationError(f"Authentication failed: {error_msg}")
+                elif status == 403:
+                    raise exc.AuthorizationError(f"Access denied: {error_msg}")
+                elif status == 404:
+                    raise exc.NotFoundError(None, details=error_data)
+                elif status == 409:
+                    raise exc.ConflictError(status, error_msg, error_code=error_code)
+                elif status == 429:
+                    retry_after = e.response.headers.get('Retry-After')
+                    raise exc.RateLimitError(retry_after=retry_after, details=error_data)
+                elif 500 <= status < 600:
+                    raise exc.ServerError(status, error_msg, error_code=error_code)
+                else:
+                    raise exc.RestApiError(status, error_msg, error_code=error_code)
+            else:
+                raise exc.RestClientError(f"Request failed: {str(e)}")
+        except (FileNotFoundError, OSError):
+            # Let file system errors pass through unchanged
+            raise
+        except Exception as e:
+            if isinstance(e, exc.RestClientError):
+                raise
+            raise exc.RestClientError(f"Unexpected error: {e!s}")
+    
+    return wrapper
+
+
+class BaseOperation:
+    """Base class for REST API operation groups.
+    
+    Provides common functionality for all operation classes:
+    - Error handling
+    - Pagination helpers
+    - Logging
+    - Response processing
+    
+    Attributes:
+        client: The requests_openapi.Client instance
+        logger: Logger instance for this operation group
+        operation_name: Name of this operation group (for logging)
+        context: STEP context ID passed to every API call
+        workspace: STEP workspace ID passed to every API call (defaults to "Main" server-side)
+    """
+    
+    def __init__(self, client: roa.Client, operation_name: str | None = None, 
+                 logger: Optional[logging.Logger] = None,
+                 context: str | None = None, workspace: str | None = None):
+        """Initialize base operation.
+        
+        Args:
+            client: The requests-openapi Client instance
+            operation_name: Name of this operation group (defaults to class name)
+            logger: Logger instance (defaults to class logger)
+            context: STEP context ID to use for all API calls (required by STEP REST API)
+            workspace: STEP workspace ID (server defaults to "Main" if not supplied)
+        """
+        self.client = client
+        self.operation_name = operation_name or self.__class__.__name__
+        self.context = context
+        self.workspace = workspace
+        
+        if logger is None:
+            self.logger = logging.getLogger(f"{self.__class__.__module__}.{self.operation_name}")
+        else:
+            self.logger = logger
+    
+    def _build_context_params(self) -> Dict[str, Any]:
+        """Build context and workspace parameters for API calls.
+        
+        Returns:
+            Dictionary containing context and/or workspace keys if set.
+        """
+        params: Dict[str, Any] = {}
+        if self.context is not None:
+            params['context'] = self.context
+        if self.workspace is not None:
+            params['workspace'] = self.workspace
+        return params
+
+    def _check_for_api_error(self, response: Any, resource_id: str | None = None,
+                              resource_type: str | None = None) -> None:
+        """Detect STEP error responses returned as dicts instead of raised exceptions.
+
+        The STEP REST API may return an error body like
+        ``{"httpStatus": 404, "message": "...", "httpReason": "..."}`` on a
+        transport-level 200 when using requests_openapi without raise_for_status.
+        This method raises the appropriate library exception in those cases.
+
+        Args:
+            response: The API response (dict, list, or object)
+            resource_id: Resource ID for error messages
+            resource_type: Resource type name for error messages
+
+        Raises:
+            AuthenticationError: If httpStatus is 401
+            AuthorizationError: If httpStatus is 403
+            NotFoundError: If httpStatus is 404
+            ConflictError: If httpStatus is 409
+            RestApiError: For other 4xx/5xx status codes
+        """
+        if not isinstance(response, dict) or 'httpStatus' not in response:
+            return
+        status = response.get('httpStatus', 0)
+        message = response.get('message') or response.get('httpReason', 'API error')
+        if status == 401:
+            raise exc.AuthenticationError(f"Authentication failed: {message}")
+        elif status == 403:
+            raise exc.AuthorizationError(f"Access denied: {message}")
+        elif status == 404:
+            raise exc.NotFoundError(resource_id, resource_type)
+        elif status == 409:
+            raise exc.ConflictError(status, message)
+        elif 400 <= status < 600:
+            raise exc.RestApiError(status, message)
+
+    def _check_response_status(self, response: Any, resource_id: str | None = None,
+                                resource_type: str | None = None) -> None:
+        """Check response for HTTP error status codes returned without raising an exception.
+        
+        Some STEP endpoints (e.g. binary content) return an HTTP error response body
+        (e.g. an HTML 404 page) with a non-error HTTP status from the transport layer.
+        This method inspects the underlying response object and raises the appropriate
+        exception when an error status is detected.
+        
+        Args:
+            response: The API response object
+            resource_id: Resource ID for error messages
+            resource_type: Resource type name for error messages
+            
+        Raises:
+            NotFoundError: If status is 404
+            RestApiError: For other 4xx/5xx status codes
+        """
+        # First check for STEP error dicts (JSON body with httpStatus field)
+        self._check_for_api_error(response, resource_id, resource_type)
+
+        raw_response = getattr(response, '_response', None) or getattr(response, 'response', None)
+        status_code = (
+            getattr(raw_response, 'status_code', None)
+            or getattr(response, 'status_code', None)
+        )
+        if status_code is not None and isinstance(status_code, int) and status_code >= 400:
+            if status_code == 404:
+                raise exc.NotFoundError(resource_id, resource_type)
+            raise exc.RestApiError(status_code, f"HTTP {status_code} for {resource_type} {resource_id}")
+
+    def _log_operation(self, operation_id: str, params: Optional[Dict[str, Any]] = None) -> None:
+        """Log an API operation.
+        
+        Args:
+            operation_id: The OpenAPI operation ID
+            params: Request parameters
+        """
+        self.logger.debug(
+            f"Calling {self.operation_name}.{operation_id}",
+            extra={"params": params}
+        )
+
+    @staticmethod
+    def _coerce_list_payload(payload: Any) -> list[Any]:
+        """Normalize list-like API payloads from various response shapes.
+
+        Supports:
+        - native lists
+        - dicts with common wrapper keys such as items/results/data/values
+        - response-like objects exposing json() or text
+        - single-object payloads, which are returned as a one-item list
+        """
+        if payload is None:
+            return []
+
+        if isinstance(payload, list):
+            return payload
+
+        if isinstance(payload, dict):
+            for key in ("items", "results", "data", "values"):
+                value = payload.get(key)
+                if isinstance(value, list):
+                    return value
+            if payload:
+                return [payload]
+            return []
+
+        if hasattr(payload, "json"):
+            try:
+                parsed = payload.json()
+            except Exception:
+                parsed = None
+            if parsed is not None:
+                return BaseOperation._coerce_list_payload(parsed)
+
+        if hasattr(payload, "text"):
+            try:
+                import json
+                parsed = json.loads(payload.text)
+            except Exception:
+                parsed = None
+            if parsed is not None:
+                return BaseOperation._coerce_list_payload(parsed)
+
+        return []
+    
+    def _process_response(self, response: Any) -> Any:
+        """Process API response (hook for subclasses).
+        
+        Override this method in subclasses to add custom response processing.
+        
+        Args:
+            response: Raw API response
+            
+        Returns:
+            Processed response
+        """
+        return response
+    
+    def _build_pagination_params(self, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+        """Build pagination parameters for requests.
+        
+        Args:
+            limit: Number of items per page
+            offset: Result offset
+            
+        Returns:
+            Dictionary of pagination parameters
+        """
+        return {
+            "limit": max(1, min(limit, 1000)),  # Clamp between 1 and 1000
+            "offset": max(0, offset)
+        }
+    
+    def _build_page_info(self, limit: int, offset: int, 
+                        total: Optional[int] = None) -> PageInfo:
+        """Build PageInfo object from pagination parameters.
+        
+        Args:
+            limit: Items per page
+            offset: Current offset
+            total: Total items (if known)
+            
+        Returns:
+            PageInfo instance
+        """
+        return PageInfo(
+            limit=limit,
+            offset=offset,
+            total=total
+        )
+    
+    def _get_paginated_results(self, operation_id: str, params: Optional[Dict[str, Any]] = None,
+                              item_key: str = "items",
+                              total_key: str = "total") -> tuple:
+        """Execute paginated API call and extract items and total count.
+        
+        Args:
+            operation_id: OpenAPI operation ID to call
+            params: Request parameters (should include limit and offset)
+            item_key: Key in response containing items list
+            total_key: Key in response containing total count
+            
+        Returns:
+            Tuple of (items, total) where total may be None if not in response
+        """
+        self._log_operation(operation_id, params)
+        
+        operation = getattr(self.client, operation_id)
+        response = operation(**(params or {}))
+        
+        # Handle different response formats
+        if isinstance(response, dict):
+            items = response.get(item_key, [])
+            total = response.get(total_key)
+        else:
+            # Handle object responses
+            items = getattr(response, item_key, [])
+            total = getattr(response, total_key, None)
+        
+        return items, total
+    
+    @handle_rest_errors
+    def _call_operation(self, operation_id: str, **params) -> Any:
+        """Call an OpenAPI operation with error handling.
+        
+        Args:
+            operation_id: OpenAPI operation ID to call
+            **params: Operation parameters
+            
+        Returns:
+            Operation response
+        """
+        self._log_operation(operation_id, params)
+        
+        operation = getattr(self.client, operation_id)
+        response = operation(**params)
+        
+        return self._process_response(response)
+    
+    def _validate_required_params(self, params: Dict[str, Any], 
+                                  required: list) -> None:
+        """Validate that required parameters are present.
+        
+        Args:
+            params: Parameters to validate
+            required: List of required parameter names
+            
+        Raises:
+            ValidationError: If required parameters are missing
+        """
+        missing = [p for p in required if p not in params or params[p] is None]
+        if missing:
+            raise exc.ValidationError(f"Missing required parameters: {missing}")
+    
+    def _clean_params(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Remove None values from parameters.
+        
+        Args:
+            params: Parameters to clean
+            
+        Returns:
+            Cleaned parameters
+        """
+        return {k: v for k, v in params.items() if v is not None}

stepxmlclient/rest_client/client.py

@@ -0,0 +1,127 @@
+"""Extended STEP REST API client with operation groups.
+
+Extends the base StiboStepRestClient to provide organized access to
+operation groups for different STEP entities.
+"""
+
+import logging
+from typing import Optional
+
+from ..client import StiboStepRestClient
+from .base import BaseOperation
+from .operations.assets import AssetOperations
+from .operations.attributes import AttributeOperations
+from .operations.background_processes import BackgroundProcessOperations
+from .operations.batch import BatchOperations
+from .operations.classifications import ClassificationOperations
+from .operations.collection_groups import CollectionGroupOperations
+from .operations.collections import CollectionOperations
+from .operations.contexts import ContextOperations
+from .operations.data_type_groups import DataTypeGroupOperations
+from .operations.entities import EntityOperations
+from .operations.event_processors import EventProcessorOperations
+from .operations.exports import ExportOperations
+from .operations.gateway import GatewayOperations
+from .operations.inbound import InboundOperations
+from .operations.outbound import OutboundOperations
+from .operations.products import ProductOperations
+from .operations.relations import RelationOperations
+from .operations.reports import ReportOperations
+from .operations.system_information import SystemInformationOperations
+from .operations.user_groups import UserGroupOperations
+from .operations.users import UserOperations
+from .operations.workflow_tasks import WorkflowTaskOperations
+from .operations.workflows import WorkflowOperations
+
+
+class StepRestClient(StiboStepRestClient):
+    """Extended REST client with organized operation groups.
+    
+    Inherits authentication and base functionality from StiboStepRestClient,
+    adding domain-specific operation groups for easier API access.
+    
+    Attributes:
+        products: ProductOperations instance
+        assets: AssetOperations instance
+        classifications: ClassificationOperations instance
+        entities: EntityOperations instance
+        attributes: AttributeOperations instance
+        exports: ExportOperations instance
+        relations: RelationOperations instance
+        inbound: InboundOperations instance (for IIEP uploads)
+    """
+    
+    def __init__(self, location_base, authorisation,
+                 openapi_file=None, logger=None,
+                 proxies=None, ssl_version=None,
+                 cache_openapi=False, nocert=False,
+                 context: str | None = None, workspace: str | None = None):
+        """Initialize StepRestClient with operation groups.
+        
+        Args:
+            location_base: Base URL of STEP REST API
+            authorisation: Authentication handler (e.g., BasicAuthorisation)
+            openapi_file: Path to OpenAPI specification file
+            logger: Logger instance
+            proxies: Proxy configuration
+            ssl_version: SSL version configuration
+            cache_openapi: Whether to cache OpenAPI spec
+            nocert: Whether to skip SSL certificate verification
+            context: STEP context ID passed to all context-aware API calls
+            workspace: STEP workspace ID (server defaults to "Main" if not supplied)
+        """
+        # Initialize parent class
+        super().__init__(
+            location_base=location_base,
+            authorisation=authorisation,
+            openapi_file=openapi_file,
+            logger=logger,
+            proxies=proxies,
+            ssl_version=ssl_version,
+            cache_openapi=cache_openapi,
+            nocert=nocert
+        )
+        
+        # Get logger for operation groups
+        if logger is None:
+            op_logger = logging.getLogger(f"{self.__class__.__module__}.operations")
+        else:
+            op_logger = logger
+        
+        # Initialize operation groups (context/workspace passed to entity-level operations)
+        self.products = ProductOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.assets = AssetOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.classifications = ClassificationOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.entities = EntityOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.attributes = AttributeOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.relations = RelationOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.inbound = InboundOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.exports = ExportOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.contexts = ContextOperations(self.client, logger=op_logger)
+        self.system_information = SystemInformationOperations(self.client, logger=op_logger)
+        self.users = UserOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.user_groups = UserGroupOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.collections = CollectionOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.collection_groups = CollectionGroupOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.batch = BatchOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.data_type_groups = DataTypeGroupOperations(self.client, logger=op_logger)
+        self.background_processes = BackgroundProcessOperations(self.client, logger=op_logger)
+        self.event_processors = EventProcessorOperations(self.client, logger=op_logger)
+        self.outbound = OutboundOperations(self.client, logger=op_logger)
+        self.gateway = GatewayOperations(self.client, logger=op_logger)
+        self.workflows = WorkflowOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.workflow_tasks = WorkflowTaskOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+        self.reports = ReportOperations(self.client, logger=op_logger, context=context, workspace=workspace)
+    
+    def get_operation_group(self, group_name: str) -> BaseOperation | None:
+        """Get an operation group by name.
+        
+        Useful for dynamic access to operation groups.
+        
+        Args:
+            group_name: Name of operation group (e.g., 'products', 'assets')
+            
+        Returns:
+            Operation group instance or None if not found
+        """
+        return getattr(self, group_name, None)

stepxmlclient/rest_client/exceptions.py

@@ -0,0 +1,97 @@
+"""REST API client exceptions.
+
+Provides REST-specific exception classes for error handling in rest_client operations.
+"""
+
+
+class RestClientError(Exception):
+    """Base exception for REST API client errors."""
+    pass  # noqa: PIE790
+
+
+class RestApiError(RestClientError):
+    """Exception raised for API response errors.
+    
+    Attributes:
+        status_code: HTTP status code from the API response
+        error_message: Error message from the API
+        error_code: API-specific error code if available
+        details: Additional error details from response body
+    """
+    
+    def __init__(self, status_code, error_message, error_code=None, details=None):
+        self.status_code = status_code
+        self.error_message = error_message
+        self.error_code = error_code
+        self.details = details
+        message = f"API Error ({status_code}): {error_message}"
+        if error_code:
+            message += f" [Code: {error_code}]"
+        super().__init__(message)
+
+
+class AuthenticationError(RestClientError):
+    """Exception raised for authentication failures."""
+    
+    pass  # noqa: PIE790
+
+
+class AuthorizationError(RestClientError):
+    """Exception raised for authorization failures (insufficient permissions)."""
+    
+    pass  # noqa: PIE790  # noqa: PIE790
+
+
+class NotFoundError(RestApiError):
+    """Exception raised when a requested resource is not found (HTTP 404)."""
+    
+    def __init__(self, resource_id, resource_type=None, details=None):
+        message = "Resource not found"
+        if resource_type:
+            message += f": {resource_type}"
+        if resource_id:
+            message += f" (ID: {resource_id})"
+        super().__init__(404, message, error_code="NOT_FOUND", details=details)
+        self.resource_id = resource_id
+        self.resource_type = resource_type
+
+
+class ValidationError(RestClientError):
+    """Exception raised for request validation errors."""
+    
+    def __init__(self, validation_errors):
+        self.validation_errors = validation_errors
+        message = f"Validation error: {validation_errors}"
+        super().__init__(message)
+
+
+class ConflictError(RestApiError):
+    """Exception raised for resource conflicts (HTTP 409)."""
+    
+    pass  # noqa: PIE790
+
+
+class RateLimitError(RestApiError):
+    """Exception raised when rate limit is exceeded (HTTP 429)."""
+    
+    def __init__(self, retry_after=None, details=None):
+        super().__init__(429, "Rate limit exceeded", error_code="RATE_LIMITED", details=details)
+        self.retry_after = retry_after
+
+
+class ServerError(RestApiError):
+    """Exception raised for server errors (HTTP 5xx)."""
+    
+    pass  # noqa: PIE790
+
+
+class TimeoutError(RestClientError):
+    """Exception raised when request times out."""
+    
+    pass  # noqa: PIE790
+
+
+class OperationError(RestClientError):
+    """Exception raised for operation-specific errors."""
+    
+    pass  # noqa: PIE790