par_ai_core.output_utils API documentation
Description: Output formatting utilities for enhanced display and data presentation …

# Module `par_ai_core.output_utils`

Output formatting utilities for enhanced display and data presentation.

This module provides a set of utilities for formatting and displaying output in various formats, including plain text, Markdown, CSV, and JSON. It leverages the Rich library to create enhanced terminal output with features such as syntax highlighting, tables, and formatted text.

Key features: - Support for multiple output formats (plain text, Markdown, CSV, JSON) - Conversion of CSV data to Rich tables for improved readability - Syntax highlighting for JSON data - Flexible display options using Rich console - Utilities for handling both string data and file inputs

Main components: - DisplayOutputFormat: An enum class for specifying output format choices - csv_to_table: Converts CSV string data to a Rich Table - csv_file_to_table: Converts a CSV file to a Rich Table - highlight_json: Applies syntax highlighting to JSON string data - highlight_json_file: Applies syntax highlighting to JSON file content - get_output_format_prompt: Generates format-specific instructions for AI models - display_formatted_output: Displays content in the specified format using Rich

Usage: This module can be used to enhance the presentation of data in command-line interfaces, improve the readability of structured data like CSV and JSON, and provide consistent formatting across different output types.

## Example

from par_ai_core.output_utils import display_formatted_output, DisplayOutputFormat

data = '{"name": "John", "age": 30}' display_formatted_output(data, DisplayOutputFormat.JSON)

## Note

This module requires the Rich library for enhanced terminal output.

## Functions

`def csv_file_to_table(csv_file: Path, title: str | None = None) ‑> rich.table.Table`
  Expand source code

      def csv_file_to_table(csv_file: Path, title: str | None = None) -> Table:
          """Convert a CSV file to a Rich Table format.

          Args:
              csv_file: Path to the CSV file to convert
              title: Optional title for the table. If None, uses the filename

          Returns:
              Table: A Rich Table object containing the formatted CSV data

          Raises:
              FileNotFoundError: If the CSV file doesn't exist
              UnicodeDecodeError: If file encoding is not UTF-8
          """
          return csv_to_table(
              csv_file.read_text(encoding="utf-8").strip(),
              csv_file.name if title is None else title,
          )

  Convert a CSV file to a Rich Table format.

  ## Args

  `csv_file`
    Path to the CSV file to convert
  `title`
    Optional title for the table. If None, uses the filename

  ## Returns

  `Table`
    A Rich Table object containing the formatted CSV data

  ## Raises

  `FileNotFoundError`
    If the CSV file doesn't exist
  `UnicodeDecodeError`
    If file encoding is not UTF-8
`def csv_to_table(data: str, title: str = 'Results') ‑> rich.table.Table`
  Expand source code

      def csv_to_table(data: str, title: str = "Results") -> Table:
          """Convert CSV string data to a Rich Table format.

          Args:
              data: CSV formatted string data to convert
              title: Title to display at the top of the table. Defaults to "Results"

          Returns:
              Table: A Rich Table object containing the formatted CSV data

          Raises:
              csv.Error: If CSV parsing fails
              ValueError: If CSV data is malformed
          """
          data = data.strip()
          table = Table(title=title, show_header=True, header_style="bold cyan")

          if not data:
              table.add_column("Empty", justify="left", style="cyan", no_wrap=True)
              return table

          try:
              reader = csv.reader(io.StringIO(data))
              headers = next(reader, None)

              # Check if headers is None or contains only empty strings
              if not headers or all(not field.strip() for field in headers):
                  table.add_column("Error", justify="left", style="red")
                  table.add_row("No fields found in CSV data")
                  return table

              # Add columns
              for field in headers:
                  table.add_column(str(field), justify="left", style="cyan", no_wrap=True)

              # Add rows
              try:
                  for row in reader:
                      if len(row) != len(headers):
                          table = Table(title=title)
                          table.add_column("Error", justify="left", style="red")
                          table.add_row("Failed to parse CSV data: Inconsistent number of fields")
                          return table
                      table.add_row(*[str(val) for val in row])
              except Exception as e:
                  table = Table(title=title)
                  table.add_column("Error", justify="left", style="red")
                  table.add_row(f"Failed to parse CSV data: {str(e)}")
                  return table

          except (csv.Error, ValueError) as e:
              table = Table(title=title)
              table.add_column("Error", justify="left", style="red")
              table.add_row(f"Failed to parse CSV data: {str(e)}")
          return table

  Convert CSV string data to a Rich Table format.

  ## Args

  `data`
    CSV formatted string data to convert
  `title`
    Title to display at the top of the table. Defaults to "Results"

  ## Returns

  `Table`
    A Rich Table object containing the formatted CSV data

  ## Raises

  `csv.Error`
    If CSV parsing fails
  `ValueError`
    If CSV data is malformed
`def display_formatted_output(content: str,
display_format: DisplayOutputFormat,
console: Console | None = None) ‑> None`
  Expand source code

      def display_formatted_output(content: str, display_format: DisplayOutputFormat, console: Console | None = None) -> None:
          """Display content in the specified format using Rich console output.

          Formats and displays content according to the specified DisplayOutputFormat.
          Supports plain text, Markdown, CSV table, and syntax-highlighted JSON output.

          Args:
              content: The content string to display
              display_format: The format to use for displaying the content
              console: Optional Rich Console instance to use. If None, uses console_err

          Returns:
              None

          Note:
              For CSV format, content is converted to a Rich Table before display.
              For JSON format, syntax highlighting is applied.
              If display_format is NONE, nothing is displayed.
          """
          if display_format == DisplayOutputFormat.NONE:
              return

          if not console:
              console = console_err

          if display_format == DisplayOutputFormat.PLAIN:
              print(content)
          elif display_format == DisplayOutputFormat.MD:
              console.print(Markdown(content))
          elif display_format == DisplayOutputFormat.CSV:
              # Convert CSV to rich Table
              table = Table(title="CSV Data")
              csv_reader = csv.reader(io.StringIO(content))
              headers = next(csv_reader)
              for header in headers:
                  table.add_column(header, style="cyan")
              for row in csv_reader:
                  table.add_row(*row)
              console.print(table)
          elif display_format == DisplayOutputFormat.JSON:
              console.print(Syntax(content, "json"))

  Display content in the specified format using Rich console output.

  Formats and displays content according to the specified DisplayOutputFormat. Supports plain text, Markdown, CSV table, and syntax-highlighted JSON output.

  ## Args

  `content`
    The content string to display
  `display_format`
    The format to use for displaying the content
  `console`
    Optional Rich Console instance to use. If None, uses console_err

  ## Returns

  None

  ## Note

  For CSV format, content is converted to a Rich Table before display. For JSON format, syntax highlighting is applied. If display_format is NONE, nothing is displayed.

`def get_output_format_prompt(display_format: DisplayOutputFormat) ‑> str`
  Expand source code

      def get_output_format_prompt(display_format: DisplayOutputFormat) -> str:
          """Get the appropriate output format prompt instructions.

          Args:
              display_format: The desired output format enum value

          Returns:
              str: XML-formatted instructions for the specified output format.
                  Returns empty string if format is NONE.
          """
          if display_format == DisplayOutputFormat.MD:
              return """<output_instructions>
          <instruction>Output properly formatted Markdown.</instruction>
          <instruction>Use table / list formatting when applicable or requested.</instruction>
          <instruction>Do not include an opening ```markdown or closing ```</instruction>
      </output_instructions>
      """
          if display_format == DisplayOutputFormat.JSON:
              return """<output_instructions>
          <instruction>Output proper JSON.</instruction>
          <instruction>Use a schema if provided.</instruction>
          <instruction>Only output JSON. Do not include any other text / markdown or formatting such as opening ```json or closing ```</instruction>
      </output_instructions>
      """
          if display_format == DisplayOutputFormat.CSV:
              return """<output_instructions>
          <instruction>Output proper CSV format.</instruction>
          <instruction>Ensure you use double quotes on fields containing line breaks or commas.</instruction>
          <instruction>Include a header with names of the fields.</instruction>
          <instruction>Only output the CSV header and data.</instruction>
          <instruction>Do not include any other text / Markdown such as opening ```csv or closing ```</instruction>
      </output_instructions>
      """
          if display_format == DisplayOutputFormat.PLAIN:
              return """<output_instructions>
          <instruction>Output plain text without formatting, do not include any other formatting such as markdown.</instruction>
      </output_instructions>
      """
          return ""

  Get the appropriate output format prompt instructions.

  ## Args

  `display_format`
    The desired output format enum value

  ## Returns

  `str`
    XML-formatted instructions for the specified output format. Returns empty string if format is NONE.
`def highlight_json(data: str) ‑> rich.syntax.Syntax`
  Expand source code

      def highlight_json(data: str) -> Syntax:
          """Create syntax-highlighted JSON output.

          Args:
              data: JSON string to highlight

          Returns:
              Syntax: A Rich Syntax object with JSON highlighting applied
          """
          return Syntax(data, "json", background_color="default")

  Create syntax-highlighted JSON output.

  ## Args

  `data`
    JSON string to highlight

  ## Returns

  `Syntax`
    A Rich Syntax object with JSON highlighting applied
`def highlight_json_file(json_file: Path) ‑> rich.syntax.Syntax`
  Expand source code

      def highlight_json_file(json_file: Path) -> Syntax:
          """Create syntax-highlighted output from a JSON file.

          Args:
              json_file: Path to the JSON file to highlight

          Returns:
              Syntax: A Rich Syntax object with JSON highlighting applied

          Raises:
              FileNotFoundError: If the JSON file doesn't exist
              UnicodeDecodeError: If file encoding is not UTF-8
          """
          return highlight_json(json_file.read_text(encoding="utf-8").strip())

  Create syntax-highlighted output from a JSON file.

  ## Args

  `json_file`
    Path to the JSON file to highlight

  ## Returns

  `Syntax`
    A Rich Syntax object with JSON highlighting applied

  ## Raises

  `FileNotFoundError`
    If the JSON file doesn't exist
  `UnicodeDecodeError`
    If file encoding is not UTF-8

## Classes

`class DisplayOutputFormat (*args, **kwds)`
  Expand source code

      class DisplayOutputFormat(StrEnum):
          """Enum for display output format choices."""

          NONE = "none"
          """No output."""
          PLAIN = "plain"
          """Plain text output."""
          MD = "md"
          """Rich Markdown output."""
          CSV = "csv"
          """Rich Table output."""
          JSON = "json"
          """Rich JSON output."""

  Enum for display output format choices.

  ### Ancestors

  - strenum.StrEnum
  - builtins.str
  - enum.Enum

  ### Class variables

  `var CSV`

    Rich Table output.

  `var JSON`

    Rich JSON output.

  `var MD`

    Rich Markdown output.

  `var NONE`

    No output.

  `var PLAIN`

    Plain text output.