pltr-cli 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

pltr/services/streams.py

@@ -0,0 +1,290 @@
+"""
+Streams service wrapper for Foundry SDK.
+Provides access to streaming dataset and stream operations.
+"""
+
+from typing import Any, Dict, Optional
+from .base import BaseService
+
+
+class StreamsService(BaseService):
+    """Service wrapper for Foundry Streams operations."""
+
+    def _get_service(self) -> Any:
+        """Get the Foundry Streams service."""
+        return self.client.streams
+
+    # ===== Dataset Operations =====
+
+    def create_dataset(
+        self,
+        name: str,
+        parent_folder_rid: str,
+        schema: Dict[str, Any],
+        branch_name: Optional[str] = None,
+        compressed: Optional[bool] = None,
+        partitions_count: Optional[int] = None,
+        stream_type: Optional[str] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Create a streaming dataset with a stream on the specified branch.
+
+        Args:
+            name: Dataset name
+            parent_folder_rid: Parent folder RID (e.g., ri.compass.main.folder.xxx)
+            schema: Foundry schema for the stream (dict with field definitions)
+            branch_name: Branch to create stream on (default: 'master')
+            compressed: Enable compression for the stream (default: False)
+            partitions_count: Number of partitions (default: 1)
+                Generally, each partition can handle ~5 MB/s
+            stream_type: Stream type ('HIGH_THROUGHPUT' or 'LOW_LATENCY', default: 'LOW_LATENCY')
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Dataset information dictionary containing:
+            - rid: Dataset resource identifier
+            - name: Dataset name
+            - streamRid: Stream resource identifier
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> schema = {"fieldSchemaList": [{"name": "value", "type": "STRING"}]}
+            >>> dataset = service.create_dataset(
+            ...     name="my-stream",
+            ...     parent_folder_rid="ri.compass.main.folder.xxx",
+            ...     schema=schema
+            ... )
+        """
+        try:
+            dataset = self.service.Dataset.create(
+                name=name,
+                parent_folder_rid=parent_folder_rid,
+                schema=schema,
+                branch_name=branch_name,
+                compressed=compressed,
+                partitions_count=partitions_count,
+                stream_type=stream_type,
+                preview=preview,
+            )
+            return self._serialize_response(dataset)
+        except Exception as e:
+            raise RuntimeError(f"Failed to create streaming dataset '{name}': {e}")
+
+    # ===== Stream Operations =====
+
+    def create_stream(
+        self,
+        dataset_rid: str,
+        branch_name: str,
+        schema: Dict[str, Any],
+        compressed: Optional[bool] = None,
+        partitions_count: Optional[int] = None,
+        stream_type: Optional[str] = None,
+        preview: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Create a new stream on a branch of an existing streaming dataset.
+
+        Args:
+            dataset_rid: Dataset RID (e.g., ri.foundry.main.dataset.xxx)
+            branch_name: Branch name to create stream on
+            schema: Foundry schema for this stream
+            compressed: Enable compression (default: False)
+            partitions_count: Number of partitions (default: 1)
+            stream_type: Stream type ('HIGH_THROUGHPUT' or 'LOW_LATENCY')
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Stream information dictionary containing:
+            - streamRid: Stream resource identifier
+            - branchName: Branch name
+            - schema: Stream schema
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> stream = service.create_stream(
+            ...     dataset_rid="ri.foundry.main.dataset.xxx",
+            ...     branch_name="feature-branch",
+            ...     schema={"fieldSchemaList": [{"name": "id", "type": "INTEGER"}]}
+            ... )
+        """
+        try:
+            stream = self.service.Dataset.Stream.create(
+                dataset_rid=dataset_rid,
+                branch_name=branch_name,
+                schema=schema,
+                compressed=compressed,
+                partitions_count=partitions_count,
+                stream_type=stream_type,
+                preview=preview,
+            )
+            return self._serialize_response(stream)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to create stream on branch '{branch_name}': {e}"
+            )
+
+    def get_stream(
+        self, dataset_rid: str, stream_branch_name: str, preview: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Get information about a stream.
+
+        Args:
+            dataset_rid: Dataset RID
+            stream_branch_name: Branch name of the stream
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Stream information dictionary
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> stream = service.get_stream(
+            ...     dataset_rid="ri.foundry.main.dataset.xxx",
+            ...     stream_branch_name="master"
+            ... )
+        """
+        try:
+            stream = self.service.Dataset.Stream.get(
+                dataset_rid=dataset_rid,
+                stream_branch_name=stream_branch_name,
+                preview=preview,
+            )
+            return self._serialize_response(stream)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to get stream on branch '{stream_branch_name}': {e}"
+            )
+
+    def publish_record(
+        self,
+        dataset_rid: str,
+        stream_branch_name: str,
+        record: Dict[str, Any],
+        view_rid: Optional[str] = None,
+        preview: bool = False,
+    ) -> None:
+        """
+        Publish a single record to a stream.
+
+        Args:
+            dataset_rid: Dataset RID
+            stream_branch_name: Branch name of the stream
+            record: Record data as dictionary matching stream schema
+            view_rid: Optional view RID for partitioning
+            preview: Enable preview mode (default: False)
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> service.publish_record(
+            ...     dataset_rid="ri.foundry.main.dataset.xxx",
+            ...     stream_branch_name="master",
+            ...     record={"id": 123, "name": "test", "timestamp": 1234567890}
+            ... )
+        """
+        try:
+            self.service.Dataset.Stream.publish_record(
+                dataset_rid=dataset_rid,
+                stream_branch_name=stream_branch_name,
+                record=record,
+                view_rid=view_rid,
+                preview=preview,
+            )
+        except Exception as e:
+            raise RuntimeError(f"Failed to publish record to stream: {e}")
+
+    def publish_records(
+        self,
+        dataset_rid: str,
+        stream_branch_name: str,
+        records: list,
+        view_rid: Optional[str] = None,
+        preview: bool = False,
+    ) -> None:
+        """
+        Publish multiple records to a stream in a batch.
+
+        Args:
+            dataset_rid: Dataset RID
+            stream_branch_name: Branch name of the stream
+            records: List of record dictionaries matching stream schema
+            view_rid: Optional view RID for partitioning
+            preview: Enable preview mode (default: False)
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> records = [
+            ...     {"id": 1, "name": "alice"},
+            ...     {"id": 2, "name": "bob"}
+            ... ]
+            >>> service.publish_records(
+            ...     dataset_rid="ri.foundry.main.dataset.xxx",
+            ...     stream_branch_name="master",
+            ...     records=records
+            ... )
+        """
+        try:
+            self.service.Dataset.Stream.publish_records(
+                dataset_rid=dataset_rid,
+                stream_branch_name=stream_branch_name,
+                records=records,
+                view_rid=view_rid,
+                preview=preview,
+            )
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to publish {len(records)} records to stream: {e}"
+            )
+
+    def reset_stream(
+        self, dataset_rid: str, stream_branch_name: str, preview: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Reset a stream, clearing all existing data.
+
+        Args:
+            dataset_rid: Dataset RID
+            stream_branch_name: Branch name of the stream to reset
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Updated stream information
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = StreamsService()
+            >>> stream = service.reset_stream(
+            ...     dataset_rid="ri.foundry.main.dataset.xxx",
+            ...     stream_branch_name="master"
+            ... )
+        """
+        try:
+            stream = self.service.Dataset.Stream.reset(
+                dataset_rid=dataset_rid,
+                stream_branch_name=stream_branch_name,
+                preview=preview,
+            )
+            return self._serialize_response(stream)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to reset stream on branch '{stream_branch_name}': {e}"
+            )

pltr/services/third_party_applications.py

@@ -0,0 +1,53 @@
+"""
+Third-party applications service wrapper for Foundry SDK.
+Provides access to third-party application management operations.
+"""
+
+from typing import Any, Dict
+
+from .base import BaseService
+
+
+class ThirdPartyApplicationsService(BaseService):
+    """Service wrapper for Foundry third-party applications operations."""
+
+    def _get_service(self) -> Any:
+        """Get the Foundry third-party applications service."""
+        return self.client.third_party_applications.ThirdPartyApplication
+
+    def get_application(
+        self, application_rid: str, preview: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Get information about a specific third-party application.
+
+        Args:
+            application_rid: Third-party application Resource Identifier
+                Expected format: ri.third-party-applications.<realm>.third-party-application.<locator>
+                Example: ri.third-party-applications.main.third-party-application.my-app-123
+            preview: Enable preview mode (default: False)
+
+        Returns:
+            Third-party application information dictionary containing:
+            - rid: Application resource identifier
+            - name: Application name
+            - description: Application description (if available)
+            - status: Application status (if available)
+
+        Raises:
+            RuntimeError: If the operation fails
+
+        Example:
+            >>> service = ThirdPartyApplicationsService()
+            >>> app = service.get_application(
+            ...     "ri.third-party-applications.main.third-party-application.my-app"
+            ... )
+            >>> print(app['name'])
+        """
+        try:
+            application = self.service.get(application_rid, preview=preview)
+            return self._serialize_response(application)
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to get third-party application {application_rid}: {e}"
+            )

pltr/utils/formatting.py

@@ -4,7 +4,7 @@ Output formatting utilities for CLI commands.
 
 import json
 import csv
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union, Callable
 from datetime import datetime
 from io import StringIO
 
@@ -12,6 +12,12 @@ from rich.console import Console
 from rich.table import Table
 from rich import print as rich_print
 
+# Type checking import to avoid circular dependencies
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
 
 class OutputFormatter:
     """Handles different output formats for CLI commands."""
@@ -460,6 +466,118 @@ class OutputFormatter:
                 else:
                     f.write(str(data))
 
+    def format_paginated_output(
+        self,
+        result: Any,  # PaginationResult
+        format_type: str = "table",
+        output_file: Optional[str] = None,
+        formatter_fn: Optional[Callable] = None,
+    ) -> Optional[str]:
+        """
+        Format paginated results with metadata.
+
+        This method handles display of paginated data and automatically
+        includes pagination information based on the output format.
+
+        Args:
+            result: PaginationResult object with .data and .metadata attributes
+            format_type: Output format ('table', 'json', 'csv')
+            output_file: Optional output file path
+            formatter_fn: Optional custom formatter function for the data
+
+        Returns:
+            Formatted string if no output file specified
+
+        Example:
+            >>> result = PaginationResult(data=[...], metadata=metadata)
+            >>> formatter.format_paginated_output(result, "json")
+        """
+        # Extract data and metadata
+        data = result.data if hasattr(result, "data") else result
+        metadata = result.metadata if hasattr(result, "metadata") else None
+
+        # JSON format: include pagination metadata in output
+        if format_type == "json":
+            if metadata:
+                output_data = {
+                    "data": data,
+                    "pagination": {
+                        "page": metadata.current_page,
+                        "items_count": metadata.items_fetched,
+                        "has_more": metadata.has_more,
+                        "total_pages_fetched": metadata.total_pages_fetched,
+                    },
+                }
+                # Include next_page_token if available
+                if metadata.next_page_token:
+                    output_data["pagination"]["next_page_token"] = (
+                        metadata.next_page_token
+                    )
+
+                return self._format_json(output_data, output_file)
+            else:
+                # No metadata, format data directly
+                return self._format_json(data, output_file)
+
+        # Table/CSV format: format data normally, then print pagination info
+        else:
+            # Format the data using custom formatter or default
+            if formatter_fn:
+                formatted_result = formatter_fn(data, format_type, output_file)
+            else:
+                formatted_result = self.format_output(data, format_type, output_file)
+
+            # Print pagination info to console (even when saving to file)
+            # For CSV/table formats, pagination metadata is shown on console
+            # while data is written to file
+            if metadata:
+                self.print_pagination_info(metadata)
+
+            return formatted_result
+
+    def print_pagination_info(self, metadata: Any) -> None:  # PaginationMetadata
+        """
+        Print pagination information to the console.
+
+        This provides users with helpful information about the current
+        pagination state and how to fetch more data.
+
+        Args:
+            metadata: PaginationMetadata object
+
+        Example output:
+            Fetched 20 items (page 1)
+            Next page: --page-token abc123
+            Fetch all: Add --all flag
+        """
+        if not metadata:
+            return
+
+        # Build info message
+        info_lines = []
+
+        # Current state
+        info_lines.append(
+            f"Fetched {metadata.items_fetched} items (page {metadata.current_page})"
+        )
+
+        # Next steps if more data available
+        if metadata.has_more:
+            if metadata.next_page_token:
+                info_lines.append(f"Next page: --page-token {metadata.next_page_token}")
+            else:
+                # Iterator pattern without explicit token
+                info_lines.append(
+                    f"Next page: Use --max-pages {metadata.current_page + 1}"
+                )
+
+            info_lines.append("Fetch all: Add --all flag")
+        else:
+            info_lines.append("No more pages available")
+
+        # Print as info message
+        self.print_info("\n".join(info_lines))
+
     def format_sql_results(
         self,
         results: Any,
@@ -826,6 +944,38 @@ class OutputFormatter:
 
         return self.format_output(formatted_schedules, format_type, output_file)
 
+    def format_schedule_runs_list(
+        self,
+        runs: List[Dict[str, Any]],
+        format_type: str = "table",
+        output_file: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Format list of schedule runs.
+
+        Args:
+            runs: List of schedule run dictionaries
+            format_type: Output format
+            output_file: Optional output file path
+
+        Returns:
+            Formatted string if no output file specified
+        """
+        formatted_runs = []
+        for run in runs:
+            build_rid = run.get("build_rid", "")
+            formatted_run = {
+                "RID": run.get("rid", ""),
+                "Status": run.get("status", ""),
+                "Started": self._format_datetime(run.get("started_time")),
+                "Finished": self._format_datetime(run.get("finished_time")),
+                "Build": build_rid[:40] + "..." if len(build_rid) > 40 else build_rid,
+                "Result": run.get("result", ""),
+            }
+            formatted_runs.append(formatted_run)
+
+        return self.format_output(formatted_runs, format_type, output_file)
+
     # MediaSets formatting methods
 
     def format_media_item_info(
@@ -953,6 +1103,50 @@ class OutputFormatter:
         else:
             return self.format_output(reference, format_type, output_file)
 
+    def format_thumbnail_status(
+        self,
+        status: Dict[str, Any],
+        format_type: str = "table",
+        output_file: Optional[str] = None,
+    ) -> Optional[str]:
+        """
+        Format thumbnail calculation status for display.
+
+        Args:
+            status: Thumbnail status dictionary
+            format_type: Output format
+            output_file: Optional output file path
+
+        Returns:
+            Formatted string if no output file specified
+        """
+        if format_type == "table":
+            details = []
+
+            property_order = [
+                ("status", "Status"),
+                ("transformation_id", "Transformation ID"),
+                ("media_item_rid", "Media Item RID"),
+            ]
+
+            for key, label in property_order:
+                if status.get(key) is not None:
+                    details.append({"Property": label, "Value": str(status[key])})
+
+            # Add any remaining properties
+            for key, value in status.items():
+                if (
+                    key not in [prop[0] for prop in property_order]
+                    and value is not None
+                ):
+                    details.append(
+                        {"Property": key.replace("_", " ").title(), "Value": str(value)}
+                    )
+
+            return self.format_output(details, format_type, output_file)
+        else:
+            return self.format_output(status, format_type, output_file)
+
     # Dataset formatting methods
 
     def format_branches(