data explorer: "Copy as Code" comms (#8536)

related issue: #8531
related pr for Ark: posit-dev/ark#873 

I'm not exactly sure of the flow of these PRs with Ark, but I believe
we'll want to merge that PR, release Ark, and then pick up the new
release in this PR before this PR is merged.

This PR implements makes 3 major changes to the comms:
- **add `convert_to_code` as a supported feature:** there are other
supported features, such as row filters and column filters. This
structure includes if it is supported as well as supported syntaxes, as
an array of values.
- **`suggest_code_syntax` message:** for a particular data explorer
instance, decide what options a user has for generating code. I would
expect the return value of this to be `base-r` or something to that
effect.
- **`convert_to_code` message:** for a particular data explorer
instance, this message sends over the filters and sorts applied to the
data and the desired syntax. The expectation is that this will return a
code snippet string. The front end will (eventually) apply code
highlighting and formatting.

Below is a diagram of the general flow through comms. Note that these
comm messages will not call each other; they will be triggered by a
modal in Positron core.

```mermaid
flowchart TD
    A["Data explorer instance is created"] --> B["Get all potential syntaxes from language pack via the **supported_features**." ]
    B -->  C["Also set suggested syntax with **suggest_code_syntax**"]
    C --> D[Open modal]
    D --> E["Use **dataExplorerInstance.suggestedSyntax**"]
    E --> F["Translate data view (filters, sorts) to code with **_translate_to_code_**"]
    F --> G[Display code for user to copy]
    G -->|user chooses another syntax from modal dropdown| F
```

There is an open PR that builds off this branch to use these comms, so
you can actually fire them off/interact with them #8537

### Release Notes

<!--
Optionally, replace `N/A` with text to be included in the next release
notes.
The `N/A` bullets are ignored. If you refer to one or more Positron
issues,
these issues are used to collect information about the feature or
bugfix, such
as the relevant language pack as determined by Github labels of type
`lang: `.
  The note will automatically be tagged with the language.

These notes are typically filled by the Positron team. If you are an
external
  contributor, you may ignore this section.
-->

#### New Features

- N/A

#### Bug Fixes

- N/A


### QA Notes

It doesn't look like we have much testing for comms, but open to ideas!
Currently I plan on adding unit tests on each language runtime and then
e2e tests for the UI pieces.

---------

Signed-off-by: Isabel Zimmerman <54685329+isabelizimm@users.noreply.github.com>
Co-authored-by: Jennifer (Jenny) Bryan <jenny.f.bryan@gmail.com>

Author: isabelizimm

extensions/positron-python/python_files/posit/positron/data_explorer.py

@@ -27,6 +27,7 @@
 from .data_explorer_comm import (
     ArraySelection,
     BackendState,
+    CodeSyntaxName,
     ColumnDisplayType,
     ColumnFilter,
     ColumnFilterType,
@@ -45,6 +46,9 @@
     ColumnSortKey,
     ColumnSummaryStats,
     ColumnValue,
+    ConvertedCode,
+    ConvertToCodeFeatures,
+    ConvertToCodeRequest,
     DataExplorerBackendMessageContent,
     DataExplorerFrontendEvent,
     DataSelectionCellRange,
@@ -81,6 +85,7 @@
     SetRowFiltersParams,
     SetSortColumnsFeatures,
     SetSortColumnsParams,
+    SuggestCodeSyntaxRequest,
     SummaryStatsBoolean,
     SummaryStatsDate,
     SummaryStatsDatetime,
@@ -281,6 +286,12 @@ def get_schema(self, params: GetSchemaParams):
     def _get_single_column_schema(self, column_index: int) -> ColumnSchema:
         raise NotImplementedError
 
+    def suggest_code_syntax(self, request: SuggestCodeSyntaxRequest):
+        raise NotImplementedError
+
+    def convert_to_code(self, request: ConvertToCodeRequest):
+        raise NotImplementedError
+
     def search_schema(self, params: SearchSchemaParams):
         filters = params.filters
         start_index = params.start_index
@@ -804,6 +815,13 @@ def _prof_histogram(
             support_status=SupportStatus.Unsupported,
             supported_formats=[],
         ),
+        convert_to_code=ConvertToCodeFeatures(
+            support_status=SupportStatus.Supported,
+            code_syntaxes=[
+                CodeSyntaxName(code_syntax_name="pandas"),
+                CodeSyntaxName(code_syntax_name="polars"),
+            ],
+        ),
     )
 
 
@@ -1350,6 +1368,16 @@ def schema_getter(column_name, column_index):
 
         return schema_updated, new_state
 
+    def suggest_code_syntax(self, request: SuggestCodeSyntaxRequest):  # noqa: ARG002
+        """Returns the supported code types for exporting data."""
+        return CodeSyntaxName(code_syntax_name="pandas").dict()
+
+    def convert_to_code(self, request: ConvertToCodeRequest):  # noqa: ARG002
+        """Translates the current data view, including filters and sorts, into a code snippet."""
+        return ConvertedCode(
+            converted_code=["import pandas as pd", "# TODO: Implement export to code"]
+        ).dict()
+
     @classmethod
     def _construct_schema(
         cls, column, column_name, column_index: int, state: DataExplorerState
@@ -1911,6 +1939,10 @@ def _prof_histogram(
                 ExportFormat.Html,
             ],
         ),
+        convert_to_code=ConvertToCodeFeatures(
+            support_status=SupportStatus.Supported,
+            code_syntaxes=[CodeSyntaxName(code_syntax_name="pandas")],
+        ),
     )
 
 
@@ -2280,6 +2312,16 @@ def schema_getter(column_name, column_index):
 
         return schema_updated, new_state
 
+    def suggest_code_syntax(self, request: SuggestCodeSyntaxRequest):  # noqa: ARG002
+        """Returns the supported code types for exporting data."""
+        return CodeSyntaxName(code_syntax_name="polars").dict()
+
+    def convert_to_code(self, request: ConvertToCodeRequest):  # noqa: ARG002
+        """Translates the current data view, including filters and sorts, into a code snippet."""
+        return ConvertedCode(
+            converted_code=["import polars as pl", "# TODO: Implement export to code"]
+        ).dict()
+
     def _get_single_column_schema(self, column_index: int):
         if self.state.schema_cache:
             return self.state.schema_cache[column_index]
@@ -2762,6 +2804,10 @@ def _prof_histogram(
             supported_formats=[ExportFormat.Csv, ExportFormat.Tsv],
         ),
         set_sort_columns=SetSortColumnsFeatures(support_status=SupportStatus.Supported),
+        convert_to_code=ConvertToCodeFeatures(
+            support_status=SupportStatus.Supported,
+            code_syntaxes=[CodeSyntaxName(code_syntax_name="polars")],
+        ),
     )
 
 

extensions/positron-python/python_files/posit/positron/data_explorer_comm.py

@@ -252,6 +252,26 @@ class ExportedData(BaseModel):
     )
 
 
+class ConvertedCode(BaseModel):
+    """
+    Code snippet for the data view
+    """
+
+    converted_code: List[StrictStr] = Field(
+        description="Lines of code that implement filters and sort keys",
+    )
+
+
+class CodeSyntaxName(BaseModel):
+    """
+    Syntax to use for code conversion
+    """
+
+    code_syntax_name: StrictStr = Field(
+        description="The name of the code syntax, eg, pandas, polars, dplyr, etc.",
+    )
+
+
 class FilterResult(BaseModel):
     """
     The result of applying filters to a table
@@ -972,6 +992,10 @@ class SupportedFeatures(BaseModel):
         description="Support for 'export_data_selection' RPC and its features",
     )
 
+    convert_to_code: ConvertToCodeFeatures = Field(
+        description="Support for 'convert_to_code' RPC and its features",
+    )
+
 
 class SearchSchemaFeatures(BaseModel):
     """
@@ -1057,6 +1081,21 @@ class SetSortColumnsFeatures(BaseModel):
     )
 
 
+class ConvertToCodeFeatures(BaseModel):
+    """
+    Feature flags for convert to code RPC
+    """
+
+    support_status: SupportStatus = Field(
+        description="The support status for this RPC method",
+    )
+
+    code_syntaxes: Optional[List[CodeSyntaxName]] = Field(
+        default=None,
+        description="The syntaxes for converted code",
+    )
+
+
 class TableSelection(BaseModel):
     """
     A selection on the data grid, for copying to the clipboard or other
@@ -1208,6 +1247,12 @@ class DataExplorerBackendRequest(str, enum.Enum):
     # Export data selection as a string in different formats
     ExportDataSelection = "export_data_selection"
 
+    # Converts the current data view into a code snippet.
+    ConvertToCode = "convert_to_code"
+
+    # Suggest code syntax for code conversion
+    SuggestCodeSyntax = "suggest_code_syntax"
+
     # Set column filters to select subset of table columns
     SetColumnFilters = "set_column_filters"
 
@@ -1422,6 +1467,65 @@ class ExportDataSelectionRequest(BaseModel):
     )
 
 
+class ConvertToCodeParams(BaseModel):
+    """
+    Converts filters and sort keys as code in different syntaxes like
+    pandas, polars, data.table, dplyr
+    """
+
+    column_filters: List[ColumnFilter] = Field(
+        description="Zero or more column filters to apply",
+    )
+
+    row_filters: List[RowFilter] = Field(
+        description="Zero or more row filters to apply",
+    )
+
+    sort_keys: List[ColumnSortKey] = Field(
+        description="Zero or more sort keys to apply",
+    )
+
+    code_syntax_name: CodeSyntaxName = Field(
+        description="The code syntax to use for conversion",
+    )
+
+
+class ConvertToCodeRequest(BaseModel):
+    """
+    Converts filters and sort keys as code in different syntaxes like
+    pandas, polars, data.table, dplyr
+    """
+
+    params: ConvertToCodeParams = Field(
+        description="Parameters to the ConvertToCode method",
+    )
+
+    method: Literal[DataExplorerBackendRequest.ConvertToCode] = Field(
+        description="The JSON-RPC method name (convert_to_code)",
+    )
+
+    jsonrpc: str = Field(
+        default="2.0",
+        description="The JSON-RPC version specifier",
+    )
+
+
+class SuggestCodeSyntaxRequest(BaseModel):
+    """
+    Suggest code syntax for code conversion based on the current backend
+    state
+    """
+
+    method: Literal[DataExplorerBackendRequest.SuggestCodeSyntax] = Field(
+        description="The JSON-RPC method name (suggest_code_syntax)",
+    )
+
+    jsonrpc: str = Field(
+        default="2.0",
+        description="The JSON-RPC version specifier",
+    )
+
+
 class SetColumnFiltersParams(BaseModel):
     """
     Set or clear column filters on table, replacing any previous filters
@@ -1575,6 +1679,8 @@ class DataExplorerBackendMessageContent(BaseModel):
         GetDataValuesRequest,
         GetRowLabelsRequest,
         ExportDataSelectionRequest,
+        ConvertToCodeRequest,
+        SuggestCodeSyntaxRequest,
         SetColumnFiltersRequest,
         SetRowFiltersRequest,
         SetSortColumnsRequest,
@@ -1623,6 +1729,10 @@ class ReturnColumnProfilesParams(BaseModel):
 
 ExportedData.update_forward_refs()
 
+ConvertedCode.update_forward_refs()
+
+CodeSyntaxName.update_forward_refs()
+
 FilterResult.update_forward_refs()
 
 BackendState.update_forward_refs()
@@ -1705,6 +1815,8 @@ class ReturnColumnProfilesParams(BaseModel):
 
 SetSortColumnsFeatures.update_forward_refs()
 
+ConvertToCodeFeatures.update_forward_refs()
+
 TableSelection.update_forward_refs()
 
 DataSelectionSingleCell.update_forward_refs()
@@ -1741,6 +1853,12 @@ class ReturnColumnProfilesParams(BaseModel):
 
 ExportDataSelectionRequest.update_forward_refs()
 
+ConvertToCodeParams.update_forward_refs()
+
+ConvertToCodeRequest.update_forward_refs()
+
+SuggestCodeSyntaxRequest.update_forward_refs()
+
 SetColumnFiltersParams.update_forward_refs()
 
 SetColumnFiltersRequest.update_forward_refs()