output

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

flavor.output

Output formatting and redirection for Flavor tools.

Classes

OutputFormat

Bases: Enum

Supported output formats.

OutputHandler

OutputHandler(
    format: OutputFormat = OutputFormat.TEXT,
    file: str | None = None,
)

Handles output formatting and redirection.

Initialize output handler.

Parameters:

Name	Type	Description	Default
format	OutputFormat	Output format (text or json)	TEXT
file	str | None	Output file path, or "STDOUT", "STDERR" (default: STDOUT)	None

Source code in flavor/output.py

def __init__(
    self,
    format: OutputFormat = OutputFormat.TEXT,
    file: str | None = None,
) -> None:
    """
    Initialize output handler.

    Args:
        format: Output format (text or json)
        file: Output file path, or "STDOUT", "STDERR" (default: STDOUT)
    """
    self.format = format
    self._output_file = file
    self._file_handle: TextIO | None = None
    self._output_buffer: list[dict[str, Any]] = []

Functions

__enter__

__enter__() -> OutputHandler

Context manager entry.

Source code in flavor/output.py

def __enter__(self) -> OutputHandler:
    """Context manager entry."""
    if self._output_file and self._output_file not in ("STDOUT", "STDERR"):
        self._file_handle = Path(self._output_file).open("w")
    return self

__exit__

__exit__(exc_type: Any, exc_val: Any, exc_tb: Any) -> None

Context manager exit - flush any buffered output.

Source code in flavor/output.py

def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
    """Context manager exit - flush any buffered output."""
    if self.format == OutputFormat.JSON:
        self._flush_json()
    if self._file_handle:
        self._file_handle.close()

error

error(message: str, **kwargs: Any) -> None

Write an error message.

Source code in flavor/output.py

def error(self, message: str, **kwargs: Any) -> None:
    """Write an error message."""
    if self.format == OutputFormat.JSON:
        self.write({"error": message, **kwargs})
    else:
        # Errors always go to stderr in text mode
        sys.stderr.write(f"Error: {message}\n")
        sys.stderr.flush()

info

info(message: str, **kwargs: Any) -> None

Write an info message.

Source code in flavor/output.py

def info(self, message: str, **kwargs: Any) -> None:
    """Write an info message."""
    if self.format == OutputFormat.JSON:
        self.write({"info": message, **kwargs})
    else:
        self.write(message)

success

success(message: str, **kwargs: Any) -> None

Write a success message.

Source code in flavor/output.py

def success(self, message: str, **kwargs: Any) -> None:
    """Write a success message."""
    if self.format == OutputFormat.JSON:
        self.write({"success": message, **kwargs})
    else:
        pass

write

write(data: Any, **kwargs: Any) -> None

Write output in the configured format.

Parameters:

Name	Type	Description	Default
data	Any	Data to output (string for text, dict/list for JSON)	required
**kwargs	Any	Additional metadata for JSON output	{}

Source code in flavor/output.py

def write(self, data: Any, **kwargs: Any) -> None:
    """
    Write output in the configured format.

    Args:
        data: Data to output (string for text, dict/list for JSON)
        **kwargs: Additional metadata for JSON output
    """
    if self.format == OutputFormat.JSON:
        # Buffer JSON output to write as single document
        if isinstance(data, str):
            entry = {"message": data}
        elif isinstance(data, dict):
            entry = data
        else:
            entry = {"data": data}

        if kwargs:
            entry.update(kwargs)

        self._output_buffer.append(entry)
    else:
        # Text output - write immediately
        stream = self._get_output_stream()
        if isinstance(data, dict):
            # Format dict as key=value pairs for text output
            for key, value in data.items():
                stream.write(f"{key}: {value}\n")
        else:
            stream.write(str(data))
            if not str(data).endswith("\n"):
                stream.write("\n")
        stream.flush()

Functions

get_output_handler

get_output_handler(
    format_env: str | None = None,
    file_env: str | None = None,
) -> OutputHandler

Create output handler from environment or defaults.

Parameters:

Name	Type	Description	Default
format_env	str | None	Environment variable name for format (default: FLAVOR_OUTPUT_FORMAT)	None
file_env	str | None	Environment variable name for file (default: FLAVOR_OUTPUT_FILE)	None

Returns:

Type	Description
OutputHandler	Configured OutputHandler

Source code in flavor/output.py

def get_output_handler(
    format_env: str | None = None,
    file_env: str | None = None,
) -> OutputHandler:
    """
    Create output handler from environment or defaults.

    Args:
        format_env: Environment variable name for format (default: FLAVOR_OUTPUT_FORMAT)
        file_env: Environment variable name for file (default: FLAVOR_OUTPUT_FILE)

    Returns:
        Configured OutputHandler
    """
    from provide.foundation.utils.environment import get_str

    format_env = format_env or "FLAVOR_OUTPUT_FORMAT"
    file_env = file_env or "FLAVOR_OUTPUT_FILE"

    format_str = (get_str(format_env, default="text") or "text").lower()
    output_format = OutputFormat.JSON if format_str == "json" else OutputFormat.TEXT

    output_file = get_str(file_env)

    return OutputHandler(format=output_format, file=output_file)