add record and table --format options

Author: aaschaer

changelog.d/20251205_152802_aaschaer_domain.md

@@ -1,3 +1,6 @@
 ### Enhancements
 
 * Add Domain field to default output of `globus endpoint search` and `globus endpoint show`
+* Add record" and "table" to the options for `--format` to coerce tabular text outputs
+  into lists of records and vice versa. `--format record` may be especially useful
+  for displaying information that defaults to wide tables in narrow terminals

src/globus_cli/commands/endpoint/search.py

@@ -27,7 +27,7 @@
 $ globus endpoint search Tutorial --filter-owner-id go@globusid.org
 ----
 
-Search for endpoints owned by the current user
+Search for endpoints owned by the current user.
 
 [source,bash]
 ----
@@ -122,6 +122,9 @@ def endpoint_search(
     If FILTER_FULLTEXT is given, endpoints which have attributes (display name,
     legacy name, description, organization, department, keywords) that match the
     search text will be returned. The result size limit is 100 endpoints.
+
+    If the default table output is too wide for your terminal consider using
+    --format record.
     """
     from globus_cli.services.transfer import (
         ENDPOINT_LIST_FIELDS,

src/globus_cli/parsing/command_state.py

@@ -13,6 +13,8 @@
 JSON_FORMAT = "json"
 TEXT_FORMAT = "text"
 UNIX_FORMAT = "unix"
+RECORD_FORMAT = "record"
+TABLE_FORMAT = "table"
 
 F = t.TypeVar("F", bound=AnyCommand)
 
@@ -64,6 +66,12 @@ def outformat_is_json(self) -> bool:
     def outformat_is_unix(self) -> bool:
         return self.output_format == UNIX_FORMAT
 
+    def outformat_is_record(self) -> bool:
+        return self.output_format == RECORD_FORMAT
+
+    def outformat_is_table(self) -> bool:
+        return self.output_format == TABLE_FORMAT
+
     def is_verbose(self) -> bool:
         return self.verbosity > 0
 
@@ -128,7 +136,8 @@ def jmespath_callback(
         "-F",
         "--format",
         type=click.Choice(
-            [UNIX_FORMAT, JSON_FORMAT, TEXT_FORMAT], case_sensitive=False
+            [UNIX_FORMAT, JSON_FORMAT, TEXT_FORMAT, RECORD_FORMAT, TABLE_FORMAT],
+            case_sensitive=False,
         ),
         help="Output format for stdout. Defaults to text.",
         expose_value=False,

src/globus_cli/termio/__init__.py

@@ -39,6 +39,8 @@ def print_command_hint(message: str, *, color: str = "yellow") -> None:
     "outformat_is_json",
     "outformat_is_text",
     "outformat_is_unix",
+    "outformat_is_record",
+    "outformat_is_table",
     "get_jmespath_expression",
     "verbosity",
     "is_verbose",

src/globus_cli/termio/_display.py

@@ -6,7 +6,13 @@
 import click
 import globus_sdk
 
-from .context import outformat_is_json, outformat_is_text, outformat_is_unix
+from .context import (
+    outformat_is_json,
+    outformat_is_record,
+    outformat_is_table,
+    outformat_is_text,
+    outformat_is_unix,
+)
 from .field import Field
 from .printers import (
     CustomPrinter,
@@ -94,6 +100,31 @@ def __call__(
             (json output only)
         """
 
+        # if --format record was used, change table outputs into record_lists.
+        # no-op if output format is already record or record list. error on
+        # other output types.
+        if outformat_is_record():
+            if text_mode not in (
+                TextMode.text_table,
+                TextMode.text_record,
+                TextMode.text_record_list,
+            ):
+                raise click.UsageError(
+                    "This command does not support record output formatting"
+                )
+            if text_mode == TextMode.text_table:
+                text_mode = TextMode.text_record_list
+
+        # if --format table was used, change record list outputs into table
+        # outputs. no-op if output format is already table. error on other
+        # output types.
+        elif outformat_is_table():
+            if text_mode not in (TextMode.text_table, TextMode.text_record_list):
+                raise click.UsageError(
+                    "This command does not support table output formatting"
+                )
+            text_mode = TextMode.text_table
+
         if isinstance(response_data, globus_sdk.GlobusHTTPResponse):
             maybe_show_server_timing(response_data)
 

src/globus_cli/termio/context.py

@@ -37,6 +37,24 @@ def outformat_is_text() -> bool:
     return state.outformat_is_text()
 
 
+def outformat_is_record() -> bool:
+    """
+    Only safe to call within a click context.
+    """
+    ctx = click.get_current_context()
+    state = ctx.ensure_object(CommandState)
+    return state.outformat_is_record()
+
+
+def outformat_is_table() -> bool:
+    """
+    Only safe to call within a click context.
+    """
+    ctx = click.get_current_context()
+    state = ctx.ensure_object(CommandState)
+    return state.outformat_is_table()
+
+
 def get_jmespath_expression() -> t.Any:
     """
     Only safe to call within a click context.

tests/functional/endpoint/test_endpoint_search.py

@@ -193,6 +193,20 @@ def test_search_shows_collection_id(run_line, singular_search_response):
     assert meta["endpoint_id"] not in result.output
 
 
+def test_search_format_record(run_line, singular_search_response):
+    singular_search_response.add()
+    meta = singular_search_response.metadata
+
+    result = run_line("globus endpoint search mytestquery --format record")
+
+    assert result.output == (
+        f"ID:           {meta['collection_id']}\n"
+        f"Owner:        {meta['owner_string']}\n"
+        f"Display Name: {meta['display_name']}\n"
+        f"Domain:       {meta['collection_fqdn']}\n"
+    )
+
+
 @pytest.mark.parametrize(
     "entity_type",
     (