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.