feat(emitter):add structured data output with JSON and table formatting

Author: dharapandya85

craft_cli/__init__.py

@@ -29,8 +29,9 @@
 
 # names included here only to be exposed as external API; the particular order of imports
 # is to break cyclic dependencies
-from .messages import EmitterMode, emit  # isort:skip
+from .messages import EmitterMode, emit,Emitter # isort:skip
 from .dispatcher import BaseCommand, CommandGroup, Dispatcher, GlobalArgument
+from .completion import complete
 from .errors import (
     ArgumentParsingError,
     CraftError,
@@ -51,4 +52,6 @@
     "HIDDEN",
     "ProvideHelpException",
     "emit",
+    "complete",
+    "Emitter"
 ]

craft_cli/dispatcher.py

@@ -179,6 +179,12 @@ def fill_parser(self, parser: _CustomArgumentParser) -> None:
 
         :param parser: The object to fill with this command's parameters.
         """
+        parser.add_argument(
+            "--format",
+            choices=["json","table"],
+            default="table",
+            help="Format for structured output",
+        )
 
     # NOTE: run() returns `Optional[int]` instead of `int | None` as the latter would
     # be a breaking change for subclasses that override this with just `None` and
@@ -192,7 +198,10 @@ def run(self, parsed_args: argparse.Namespace) -> int | None:
         :param parsed_args: The parsed arguments that were defined in :meth:`fill_parser`.
         :return: This method should return ``None`` or the desired process' return code.
         """
-        raise NotImplementedError
+        emit=Emitter()
+        sample_data=[{"name":"App A","version":"1.0.1"},{"name":"App B","version":"2.3.0"}]
+        emit.data(sample_data,format=parsed_args.format)
+        return 0
 
 
 class _CustomArgumentParser(argparse.ArgumentParser):

craft_cli/messages.py

@@ -36,13 +36,67 @@
 from collections.abc import Callable, Generator
 from contextlib import contextmanager
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Literal, TextIO, TypeVar, cast
-
+from typing import TYPE_CHECKING, Any, Literal, TextIO, TypeVar, cast, Union, List, Dict
+import json
 import platformdirs
 
 from craft_cli import errors
 from craft_cli.printer import Printer
+from abc import ABC, abstractmethod
+#from .formatters import BaseFormatter
+
+TabularData=Union[List[Dict[str,Any]],Dict[str,Any]]
+
+class BaseFormatter(ABC):
+    @abstractmethod
+    def format(self,data:TabularData,headers:dict[str,str] | None=None)->str:
+        pass
+class JSONFormatter(BaseFormatter):
+    """
+    Format data into JSON.
 
+    Example
+    -------
+    >>> formatter=JsonFormatter()
+    >>> formatter.format([{"name":"Alice","age":30})
+    '{"name":"Alice","age":30}'
+    """
+    def format(self,data: TabularData,headers: dict[str,str] | None=None)->str:
+        return json.dumps(data,indent=2,default=str)
+class TableFormatter(BaseFormatter):
+    """
+    Format data into a pretty table.
+
+    Example
+    -------
+    >>> formatter=TableFormatter()
+    >>> formatter.format([["Name","Age"],["Alice",30]])
+    'Name Age\nAlice 30'
+    """
+    def format(self,data:TabularData,headers:dict[str,str] | None=None)->str:
+        """Format a list of rows into a table string."""
+        if not data:
+            return "[no data]"
+        table_headers:list[str]
+        if isinstance(data,list):
+            #list_data=cast(List[Dict[str,Any]],data)
+            all_keys: set[str]=set().union(*(row.keys() for row in data))
+            table_headers:list[str]=sorted(list(all_keys))
+            rows=[[str(row.get(h,"")) for h in table_headers] for row in data]
+        else:
+            table_headers=["Key", "Value"]
+            #data_dict=cast(Dict[str,Any],data)
+            rows=[[str(k),str(v)] for k,v in data.items()]
+        cols_widths=[max(len(str(item)) for item in col) for col in zip(*([table_headers]+rows))]
+
+        def format_row(row: list[str])->str:
+            return " | ".join(str(cell).ljust(width) for cell, width in zip(row,cols_widths))
+        table=[format_row(table_headers)]
+        table.append("-" * sum(cols_widths)+"---"*(len(table_headers)-1))
+        table.extend(format_row(row) for row in rows)
+        return "\n".join(table)
+        
+                     
 if TYPE_CHECKING:
     from types import TracebackType
 
@@ -462,6 +516,10 @@ def __init__(self) -> None:
         self._log_handler: _Handler = None  # type: ignore[assignment]
         self._streaming_brief = False
         self._docs_base_url: str | None = None
+        self._formatters={
+"json":JSONFormatter(),
+"table":TableFormatter(),
+}
 
     def init(
         self,
@@ -888,6 +946,14 @@ def prompt(self, prompt_text: str, *, hide: bool = False) -> str:
         if not val:
             raise errors.CraftError("input cannot be empty")
         return val
+    
+    @_active_guard()
+    def data(self,records: list[dict], format:str="table")->None:
+        if format not in self._formatters:
+            raise ValueError(f"Unsupported format: {format}")
+        formatter=self._formatters[format]
+        formatted_output=formatter.format(records)
+        self.message(formatted_output)
 
     @property
     def log_filepath(self) -> pathlib.Path:
@@ -905,3 +971,4 @@ def _format_details(details: str) -> str:
     if "\n" in details:
         return details if details.startswith("\n") else f"\n{details}"
     return details
+

craft_cli/pytest_plugin.py

@@ -25,6 +25,7 @@
 from typing import TYPE_CHECKING, Any, Literal
 from unittest.mock import call
 
+
 import pytest
 from typing_extensions import Self
 
@@ -43,6 +44,8 @@ def init_emitter(monkeypatch: pytest.MonkeyPatch) -> Generator[None]:
 
     This is an "autouse" fixture, so it just works, no need to declare it in your tests.
     """
+    # messages.emit._initiated = False
+    # messages.emit._stopped = False
     # initiate with a custom log filepath so user directories are not involved here; note that
     # we're not using pytest's standard tmp_path as Emitter would write logs there, and in
     # effect we would be polluting that temporary directory (potentially messing with
@@ -59,7 +62,8 @@ def init_emitter(monkeypatch: pytest.MonkeyPatch) -> Generator[None]:
         yield
     # end machinery (just in case it was not ended before; note it's ok to "double end")
     messages.emit.ended_ok()
-
+    # messages.emit._initiated = False
+    # messages.emit._stopped = True
 
 class _RegexComparingText(str):
     """A string that compares for equality using regex.match."""

examples.py

@@ -594,6 +594,20 @@ def example_35() -> None:
 
     emit.message("Takeover complete. Have a nice day!")
 
+def example_36(*args)->None:
+    print(">>> Running example_33 with args:", args)
+    sample_data=[
+        {"name":"App A","version":"1.0.1","status":"active"},
+        {"name":"App B","version":"2.3.0","status":"inactive"},
+    ]
+    fmt=args[0] if args else "table"
+    emit.message(f"{fmt.upper()} output:")
+    #emit.message("JSON output:")
+    emit.data(sample_data,format=fmt)
+    # emit.message("Table output:")
+    # emit.data(sample_data,format="table")
+    
+    # emit.structured(sample_data,fmt=fmt)
 
 # -- end of test cases
 
@@ -627,3 +641,4 @@ def example_35() -> None:
     emit.error(error)
 else:
     emit.ended_ok()
+

tests/unit/test_messages_emitter.py

@@ -18,6 +18,7 @@
 
 import logging
 import sys
+import json
 from collections.abc import Callable
 from typing import Any, cast
 from unittest import mock
@@ -27,7 +28,7 @@
 import pytest_mock
 from craft_cli import messages
 from craft_cli.errors import CraftCommandError, CraftError
-from craft_cli.messages import Emitter, EmitterMode, _Handler
+from craft_cli.messages import Emitter, EmitterMode, _Handler,TableFormatter,JSONFormatter
 
 FAKE_LOG_NAME = "fakelog.log"
 
@@ -1532,3 +1533,24 @@ def test_prompt_does_not_allow_empty_input(
 
     with pytest.raises(CraftError, match="input cannot be empty"):
         initiated_emitter.prompt("prompt")
+def test_table_formatter_simple_dict_list():
+    data=[{"a":1,"b":2},{"a":3,"b":4}]
+    fmt=TableFormatter()
+    out=fmt.format(data)
+    assert "a" in out and "b" in out
+    assert "1" in out and "4" in out
+def test_table_formatter_empty_list():
+    fmt=TableFormatter()
+    out=fmt.format([])
+    assert out=="[no data]"
+def test_table_formatter_dict_input():
+    fmt=TableFormatter()
+    out=fmt.format({"foo":"bar"})
+    assert "foo" in out and "bar" in out
+def test_json_formatter_dict_list():
+    data=[{"x":1},{"x":2}]
+    fmt=JSONFormatter()
+    out=fmt.format(data)
+    parsed=json.loads(out)
+    assert isinstance(parsed,list)
+    assert parsed[0]["x"]==1