Formatter

Convert device responses to different output formats (table, JSON, CSV, TSV, etc.). ResponseView provides two perspectives of the data (nested and flattened), and ResponseFormatter outputs them in your chosen format.

---

Architecture

Class Diagram

classDiagram
    class DeviceResponse {
        +type: str
        +status: str
        +received_us: int
        +...dynamic_fields: Any
    }

    class ResponseView {
        -raw: DeviceResponse
        -flat: DeviceResponse
        +__init__(response: DeviceResponse)
    }

    class ResponseFormatter {
        -supported_formats: list
        +display(response: DeviceResponse, format: str)
        -_format_table(response: DeviceResponse) str
        -_format_json(response: DeviceResponse) str
        -_format_jsonl(response: DeviceResponse) str
        -_format_csv(response: DeviceResponse) str
        -_format_ssv(response: DeviceResponse) str
        -_format_tsv(response: DeviceResponse) str
        -_format_ltsv(response: DeviceResponse) str
    }

    ResponseView --> DeviceResponse: uses (raw)
    ResponseView --> DeviceResponse: uses (flat)
    ResponseFormatter --> DeviceResponse: formats

Response Perspective Transformation

flowchart LR
    A["DeviceResponse<br/>(nested structure)"] --> B["ResponseView"]
    B --> C["raw perspective<br/>(original nested)"]
    B --> D["flat perspective<br/>(underscore-separated keys)"]
    C --> E["ResponseFormatter"]
    D --> E
    E --> F["Output Format<br/>table/json/csv/etc"]

    style A fill:#e1f5ff
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style F fill:#e8f5e9

Supported Output Formats

graph TD
    A["ResponseFormatter"] --> B["table"]
    A --> C["json"]
    A --> D["jsonl"]
    A --> E["csv"]
    A --> F["ssv<br/>space-separated"]
    A --> G["tsv<br/>tab-separated"]
    A --> H["ltsv<br/>labeled tsv"]

    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e3f2fd
    style E fill:#e8f5e9
    style F fill:#fce4ec
    style G fill:#f1f8e9
    style H fill:#ede7f6

---

ResponseView

kazunoko.formatter.ResponseView dataclass

Response view wrapper providing both raw and flattened perspectives.

Provides convenient access to raw (nested) and flat (flattened) representations of a DeviceResponse for developers. Automatically flattens nested structures in post_init.

Attributes:

Name	Type	Description
raw	DeviceResponse	Original DeviceResponse with nested structure
flat	DeviceResponse	Flattened version of the response as DeviceResponse

Example

from kazunoko import Command, connect

with connect() as device:
    cmd = Command(device)
    dev_resp = cmd.status()

    # Wrap in ResponseView to get both perspectives
    rv = ResponseView(raw=dev_resp)

    # Access raw nested structure
    raw_data = rv.raw.model_dump()

    # Access flattened structure (type-safe)
    flat_data = rv.flat

    # Use with ResponseFormatter
    fmt = ResponseFormatter(rv.flat)
    fmt.display("table")

Source code in src/kazunoko/formatter.py

@dataclass
class ResponseView:
    """
    Response view wrapper providing both raw and flattened perspectives.

    Provides convenient access to raw (nested) and flat (flattened) representations
    of a DeviceResponse for developers. Automatically flattens nested structures
    in __post_init__.

    Attributes:
        raw: Original DeviceResponse with nested structure
        flat: Flattened version of the response as DeviceResponse

    Example:
        ```python
        from kazunoko import Command, connect

        with connect() as device:
            cmd = Command(device)
            dev_resp = cmd.status()

            # Wrap in ResponseView to get both perspectives
            rv = ResponseView(raw=dev_resp)

            # Access raw nested structure
            raw_data = rv.raw.model_dump()

            # Access flattened structure (type-safe)
            flat_data = rv.flat

            # Use with ResponseFormatter
            fmt = ResponseFormatter(rv.flat)
            fmt.display("table")
        ```
    """
    raw: DeviceResponse
    flat: DeviceResponse = None

    def __post_init__(self) -> None:
        """Initialize flat representation from raw response."""
        if self.flat is None:
            flat_dict = self._flatten(self.raw.model_dump())
            self.flat = DeviceResponse(**flat_dict)

    @staticmethod
    def _flatten(obj: object, sep: str = "_", parent_key: str = "") -> dict[str, Any]:
        """
        Flatten a nested dictionary/list structure into a single-level dict.

        Recursively converts nested dicts and lists into a flat structure with
        underscore-separated keys and numeric indices for array elements.

        Args:
            obj: Object to flatten (typically dict or list)
            sep: Separator for joining keys (default: "_")
            parent_key: Prefix for keys (used in recursion)

        Returns:
            Flattened dictionary with underscore-separated keys and leaf values
        """
        items: list[tuple[str, Any]] = []

        if isinstance(obj, dict):
            for key, value in obj.items():
                new_key = f"{parent_key}{sep}{key}" if parent_key else key
                if isinstance(value, (dict, list)):
                    items.extend(ResponseView._flatten(value, sep, new_key).items())
                else:
                    items.append((new_key, value))
        elif isinstance(obj, list):
            for idx, value in enumerate(obj):
                new_key = f"{parent_key}{sep}{idx}" if parent_key else str(idx)
                if isinstance(value, (dict, list)):
                    items.extend(ResponseView._flatten(value, sep, new_key).items())
                else:
                    items.append((new_key, value))
        else:
            # Scalar value
            items.append((parent_key, obj))

        return dict(items)

__post_init__()

Initialize flat representation from raw response.

Source code in src/kazunoko/formatter.py

def __post_init__(self) -> None:
    """Initialize flat representation from raw response."""
    if self.flat is None:
        flat_dict = self._flatten(self.raw.model_dump())
        self.flat = DeviceResponse(**flat_dict)

---

ResponseFormatter

kazunoko.formatter.ResponseFormatter

Format and render device responses in multiple output formats

Provides methods to convert DeviceResponse objects into various output formats (Rich table, JSONL, CSV) for display or export.

The formatter accepts DeviceResponse objects. For dual perspective support (raw/flat), use ResponseView to access both perspectives, then format the desired one.

Parameters:

Name	Type	Description	Default
response	DeviceResponse	DeviceResponse object to format	required
console	Console | None	Optional Rich Console instance for output (default: new Console)	None

Example

from kazunoko import Command, ResponseFormatter, ResponseView, connect

with connect() as device:
    cmd = Command(device)
    dev_resp = cmd.status()

    # Wrap response to get both perspectives
    rv = ResponseView(raw=dev_resp)

    # Format flattened view (type-safe)
    fmt = ResponseFormatter(rv.flat)
    fmt.display()  # prints as table

    # Format raw view (type-safe)
    fmt = ResponseFormatter(rv.raw)
    fmt.display()

    # Format as JSONL
    jsonl_str = fmt.to_jsonl()
    print(jsonl_str)

    # Explicit format selection
    fmt.display(format="csv")

Source code in src/kazunoko/formatter.py

class ResponseFormatter:
    """
    Format and render device responses in multiple output formats

    Provides methods to convert DeviceResponse objects into various output formats
    (Rich table, JSONL, CSV) for display or export.

    The formatter accepts DeviceResponse objects. For dual perspective support (raw/flat),
    use ResponseView to access both perspectives, then format the desired one.

    Args:
        response: DeviceResponse object to format
        console: Optional Rich Console instance for output (default: new Console)

    Example:
        ```python
        from kazunoko import Command, ResponseFormatter, ResponseView, connect

        with connect() as device:
            cmd = Command(device)
            dev_resp = cmd.status()

            # Wrap response to get both perspectives
            rv = ResponseView(raw=dev_resp)

            # Format flattened view (type-safe)
            fmt = ResponseFormatter(rv.flat)
            fmt.display()  # prints as table

            # Format raw view (type-safe)
            fmt = ResponseFormatter(rv.raw)
            fmt.display()

            # Format as JSONL
            jsonl_str = fmt.to_jsonl()
            print(jsonl_str)

            # Explicit format selection
            fmt.display(format="csv")
        ```
    """

    def __init__(
        self,
        response: DeviceResponse,
        console: Console | None = None,
    ) -> None:
        """
        Initialize ResponseFormatter

        Args:
            response: DeviceResponse object to format
            console: Optional Rich Console instance for output
        """
        self.data = response.model_dump()
        self.console = console if console is not None else Console()

    def to_table(self) -> Table:
        """
        Convert response to Rich Table format

        Creates a formatted table with field names and values.

        Returns:
            Rich Table object ready for display

        Example:
            ```python
            fmt = ResponseFormatter(resp.flat)
            table = fmt.to_table()
            console.print(table)
            ```
        """
        table = Table(title="Device Response")
        table.add_column("Field", style="cyan")
        table.add_column("Value", style="green")

        for key, value in self.data.items():
            table.add_row(key, str(value))

        return table

    def to_jsonl(self) -> str:
        """
        Convert response to JSONL format (single-line JSON)

        Returns a single JSON object as a string (not pretty-printed).

        Returns:
            JSONL string (single JSON object)

        Example:
            ```python
            fmt = ResponseFormatter(resp.flat)
            jsonl_str = fmt.to_jsonl()
            print(jsonl_str)
            ```
        """
        return json.dumps(self.data, ensure_ascii=False)

    def _format_sv(self, delimiter: str) -> str:
        """
        Convert response to separated values format with custom delimiter

        Internal helper method for converting response values to a string
        with specified delimiter (e.g., ",", "\t", " ").

        Args:
            delimiter: String to use as separator between values

        Returns:
            Separated values string (one line)
        """
        values = []
        for value in self.data.values():
            # Convert to string, handling None and special cases
            if value is None:
                values.append("")
            elif isinstance(value, bool):
                values.append(str(value).lower())
            else:
                values.append(str(value))

        return delimiter.join(values)

    def to_csv(self) -> str:
        """
        Convert response to CSV format (values only, no header)

        Returns CSV-formatted values separated by commas.
        For consistency with the `read` command, outputs only values
        without column headers. Use `to_csv_with_header()` if headers
        are needed.

        Returns:
            CSV string with values only (one line)

        Example:
            ```python
            fmt = ResponseFormatter(response)
            csv_str = fmt.to_csv()
            print(csv_str)
            ```
        """
        return self._format_sv(",")

    def to_ssv(self) -> str:
        """
        Convert response to SSV format (space-separated values)

        Returns SSV-formatted values separated by spaces.
        For consistency with CSV, outputs only values without column headers.

        Returns:
            SSV string with values only (one line)

        Example:
            ```python
            fmt = ResponseFormatter(response)
            ssv_str = fmt.to_ssv()
            print(ssv_str)
            ```
        """
        return self._format_sv(" ")

    def to_tsv(self) -> str:
        """
        Convert response to TSV format (tab-separated values)

        Returns TSV-formatted values separated by tabs.
        For consistency with CSV, outputs only values without column headers.

        Returns:
            TSV string with values only (one line)

        Example:
            ```python
            fmt = ResponseFormatter(response)
            tsv_str = fmt.to_tsv()
            print(tsv_str)
            ```
        """
        return self._format_sv("\t")

    def to_ltsv(self) -> str:
        """
        Convert response to LTSV format (labeled tab-separated values)

        Returns LTSV-formatted output with key=value pairs separated by tabs.
        LTSV is useful for structured logging and easy parsing.

        Returns:
            LTSV string with key=value pairs (one line)

        Example:
            ```python
            fmt = ResponseFormatter(resp.flat)
            ltsv_str = fmt.to_ltsv()
            print(ltsv_str)
            ```
        """
        pairs = []
        for key, value in self.data.items():
            # Convert to string, handling None and special cases
            if value is None:
                value_str = ""
            elif isinstance(value, bool):
                value_str = str(value).lower()
            else:
                value_str = str(value)

            pairs.append(f"{key}={value_str}")

        return "\t".join(pairs)

    def to_json_pretty(self) -> str:
        """
        Convert response to pretty-printed JSON format

        Returns indented JSON string suitable for human reading.

        Returns:
            Pretty-printed JSON string

        Example:
            ```python
            fmt = ResponseFormatter(resp.flat)
            json_str = fmt.to_json_pretty()
            print(json_str)
            ```
        """
        return json.dumps(self.data, indent=2, ensure_ascii=False)

    def display(
        self,
        format: Literal["table", "jsonl", "json", "csv", "ssv", "tsv", "ltsv"]
        = "jsonl",
    ) -> None:
        """
        Display response in specified format

        Convenience method for displaying formatted output to console.

        Args:
            format: Output format ("table", "jsonl", "json", "csv", "ssv", "tsv", or "ltsv")
                - "jsonl": Single-line JSON (default)
                - "table": Rich formatted table
                - "json": Pretty-printed JSON with syntax highlighting
                - "csv": CSV values only
                - "ssv": Space-separated values
                - "tsv": Tab-separated values
                - "ltsv": Labeled tab-separated values (key=value pairs)

        Raises:
            ValueError: If format is not recognized

        Example:
            ```python
            fmt = ResponseFormatter(response)
            fmt.display()           # JSONL (default)
            fmt.display("table")    # Rich formatted table
            fmt.display("json")     # pretty-printed JSON
            fmt.display("csv")      # CSV format
            fmt.display("ssv")      # space-separated values
            fmt.display("tsv")      # tab-separated values
            fmt.display("ltsv")     # labeled tab-separated values
            ```
        """
        logger.debug(
            "Formatting response for display",
            extra={"format": format, "field_count": len(self.data)}
        )

        if format == "table":
            table = self.to_table()
            self.console.print(table)

        elif format == "jsonl":
            jsonl_str = self.to_jsonl()
            self.console.print(jsonl_str, soft_wrap=True)

        elif format == "json":
            json_str = self.to_json_pretty()
            syntax = Syntax(
                json_str,
                "json",
                theme="monokai",
                line_numbers=False,
            )
            self.console.print(syntax)

        elif format == "csv":
            csv_str = self.to_csv()
            self.console.print(csv_str, soft_wrap=True)

        elif format == "ssv":
            ssv_str = self.to_ssv()
            self.console.print(ssv_str, soft_wrap=True)

        elif format == "tsv":
            tsv_str = self.to_tsv()
            self.console.print(tsv_str, soft_wrap=True)

        elif format == "ltsv":
            ltsv_str = self.to_ltsv()
            self.console.print(ltsv_str, soft_wrap=True)

        else:
            logger.warning(
                "Unknown format for display",
                extra={"format": format, "supported": ["table", "jsonl", "json", "csv", "ssv", "tsv", "ltsv"]}
            )
            raise ValueError(
                f"Unknown format: {format}. "
                "Supported formats: table, jsonl, json, csv, ssv, tsv, ltsv"
            )

__init__(response, console=None)

Initialize ResponseFormatter

Parameters:

Name	Type	Description	Default
response	DeviceResponse	DeviceResponse object to format	required
console	Console | None	Optional Rich Console instance for output	None

Source code in src/kazunoko/formatter.py

def __init__(
    self,
    response: DeviceResponse,
    console: Console | None = None,
) -> None:
    """
    Initialize ResponseFormatter

    Args:
        response: DeviceResponse object to format
        console: Optional Rich Console instance for output
    """
    self.data = response.model_dump()
    self.console = console if console is not None else Console()

display(format='jsonl')

Display response in specified format

Convenience method for displaying formatted output to console.

Parameters:

Name	Type	Description	Default
format	Literal['table', 'jsonl', 'json', 'csv', 'ssv', 'tsv', 'ltsv']	Output format ("table", "jsonl", "json", "csv", "ssv", "tsv", or "ltsv") - "jsonl": Single-line JSON (default) - "table": Rich formatted table - "json": Pretty-printed JSON with syntax highlighting - "csv": CSV values only - "ssv": Space-separated values - "tsv": Tab-separated values - "ltsv": Labeled tab-separated values (key=value pairs)	'jsonl'

Raises:

Type	Description
ValueError	If format is not recognized

Example

fmt = ResponseFormatter(response)
fmt.display()           # JSONL (default)
fmt.display("table")    # Rich formatted table
fmt.display("json")     # pretty-printed JSON
fmt.display("csv")      # CSV format
fmt.display("ssv")      # space-separated values
fmt.display("tsv")      # tab-separated values
fmt.display("ltsv")     # labeled tab-separated values

Source code in src/kazunoko/formatter.py

def display(
    self,
    format: Literal["table", "jsonl", "json", "csv", "ssv", "tsv", "ltsv"]
    = "jsonl",
) -> None:
    """
    Display response in specified format

    Convenience method for displaying formatted output to console.

    Args:
        format: Output format ("table", "jsonl", "json", "csv", "ssv", "tsv", or "ltsv")
            - "jsonl": Single-line JSON (default)
            - "table": Rich formatted table
            - "json": Pretty-printed JSON with syntax highlighting
            - "csv": CSV values only
            - "ssv": Space-separated values
            - "tsv": Tab-separated values
            - "ltsv": Labeled tab-separated values (key=value pairs)

    Raises:
        ValueError: If format is not recognized

    Example:
        ```python
        fmt = ResponseFormatter(response)
        fmt.display()           # JSONL (default)
        fmt.display("table")    # Rich formatted table
        fmt.display("json")     # pretty-printed JSON
        fmt.display("csv")      # CSV format
        fmt.display("ssv")      # space-separated values
        fmt.display("tsv")      # tab-separated values
        fmt.display("ltsv")     # labeled tab-separated values
        ```
    """
    logger.debug(
        "Formatting response for display",
        extra={"format": format, "field_count": len(self.data)}
    )

    if format == "table":
        table = self.to_table()
        self.console.print(table)

    elif format == "jsonl":
        jsonl_str = self.to_jsonl()
        self.console.print(jsonl_str, soft_wrap=True)

    elif format == "json":
        json_str = self.to_json_pretty()
        syntax = Syntax(
            json_str,
            "json",
            theme="monokai",
            line_numbers=False,
        )
        self.console.print(syntax)

    elif format == "csv":
        csv_str = self.to_csv()
        self.console.print(csv_str, soft_wrap=True)

    elif format == "ssv":
        ssv_str = self.to_ssv()
        self.console.print(ssv_str, soft_wrap=True)

    elif format == "tsv":
        tsv_str = self.to_tsv()
        self.console.print(tsv_str, soft_wrap=True)

    elif format == "ltsv":
        ltsv_str = self.to_ltsv()
        self.console.print(ltsv_str, soft_wrap=True)

    else:
        logger.warning(
            "Unknown format for display",
            extra={"format": format, "supported": ["table", "jsonl", "json", "csv", "ssv", "tsv", "ltsv"]}
        )
        raise ValueError(
            f"Unknown format: {format}. "
            "Supported formats: table, jsonl, json, csv, ssv, tsv, ltsv"
        )

to_csv()

Convert response to CSV format (values only, no header)

Returns CSV-formatted values separated by commas. For consistency with the read command, outputs only values without column headers. Use to_csv_with_header() if headers are needed.

Returns:

Type	Description
str	CSV string with values only (one line)

Example

fmt = ResponseFormatter(response)
csv_str = fmt.to_csv()
print(csv_str)

Source code in src/kazunoko/formatter.py

def to_csv(self) -> str:
    """
    Convert response to CSV format (values only, no header)

    Returns CSV-formatted values separated by commas.
    For consistency with the `read` command, outputs only values
    without column headers. Use `to_csv_with_header()` if headers
    are needed.

    Returns:
        CSV string with values only (one line)

    Example:
        ```python
        fmt = ResponseFormatter(response)
        csv_str = fmt.to_csv()
        print(csv_str)
        ```
    """
    return self._format_sv(",")

to_json_pretty()

Convert response to pretty-printed JSON format

Returns indented JSON string suitable for human reading.

Returns:

Type	Description
str	Pretty-printed JSON string

Example

fmt = ResponseFormatter(resp.flat)
json_str = fmt.to_json_pretty()
print(json_str)

Source code in src/kazunoko/formatter.py

def to_json_pretty(self) -> str:
    """
    Convert response to pretty-printed JSON format

    Returns indented JSON string suitable for human reading.

    Returns:
        Pretty-printed JSON string

    Example:
        ```python
        fmt = ResponseFormatter(resp.flat)
        json_str = fmt.to_json_pretty()
        print(json_str)
        ```
    """
    return json.dumps(self.data, indent=2, ensure_ascii=False)

to_jsonl()

Convert response to JSONL format (single-line JSON)

Returns a single JSON object as a string (not pretty-printed).

Returns:

Type	Description
str	JSONL string (single JSON object)

Example

fmt = ResponseFormatter(resp.flat)
jsonl_str = fmt.to_jsonl()
print(jsonl_str)

Source code in src/kazunoko/formatter.py

def to_jsonl(self) -> str:
    """
    Convert response to JSONL format (single-line JSON)

    Returns a single JSON object as a string (not pretty-printed).

    Returns:
        JSONL string (single JSON object)

    Example:
        ```python
        fmt = ResponseFormatter(resp.flat)
        jsonl_str = fmt.to_jsonl()
        print(jsonl_str)
        ```
    """
    return json.dumps(self.data, ensure_ascii=False)

to_ltsv()

Convert response to LTSV format (labeled tab-separated values)

Returns LTSV-formatted output with key=value pairs separated by tabs. LTSV is useful for structured logging and easy parsing.

Returns:

Type	Description
str	LTSV string with key=value pairs (one line)

Example

fmt = ResponseFormatter(resp.flat)
ltsv_str = fmt.to_ltsv()
print(ltsv_str)

Source code in src/kazunoko/formatter.py

def to_ltsv(self) -> str:
    """
    Convert response to LTSV format (labeled tab-separated values)

    Returns LTSV-formatted output with key=value pairs separated by tabs.
    LTSV is useful for structured logging and easy parsing.

    Returns:
        LTSV string with key=value pairs (one line)

    Example:
        ```python
        fmt = ResponseFormatter(resp.flat)
        ltsv_str = fmt.to_ltsv()
        print(ltsv_str)
        ```
    """
    pairs = []
    for key, value in self.data.items():
        # Convert to string, handling None and special cases
        if value is None:
            value_str = ""
        elif isinstance(value, bool):
            value_str = str(value).lower()
        else:
            value_str = str(value)

        pairs.append(f"{key}={value_str}")

    return "\t".join(pairs)

to_ssv()

Convert response to SSV format (space-separated values)

Returns SSV-formatted values separated by spaces. For consistency with CSV, outputs only values without column headers.

Returns:

Type	Description
str	SSV string with values only (one line)

Example

fmt = ResponseFormatter(response)
ssv_str = fmt.to_ssv()
print(ssv_str)

Source code in src/kazunoko/formatter.py

def to_ssv(self) -> str:
    """
    Convert response to SSV format (space-separated values)

    Returns SSV-formatted values separated by spaces.
    For consistency with CSV, outputs only values without column headers.

    Returns:
        SSV string with values only (one line)

    Example:
        ```python
        fmt = ResponseFormatter(response)
        ssv_str = fmt.to_ssv()
        print(ssv_str)
        ```
    """
    return self._format_sv(" ")

to_table()

Convert response to Rich Table format

Creates a formatted table with field names and values.

Returns:

Type	Description
Table	Rich Table object ready for display

Example

fmt = ResponseFormatter(resp.flat)
table = fmt.to_table()
console.print(table)

Source code in src/kazunoko/formatter.py

def to_table(self) -> Table:
    """
    Convert response to Rich Table format

    Creates a formatted table with field names and values.

    Returns:
        Rich Table object ready for display

    Example:
        ```python
        fmt = ResponseFormatter(resp.flat)
        table = fmt.to_table()
        console.print(table)
        ```
    """
    table = Table(title="Device Response")
    table.add_column("Field", style="cyan")
    table.add_column("Value", style="green")

    for key, value in self.data.items():
        table.add_row(key, str(value))

    return table

to_tsv()

Convert response to TSV format (tab-separated values)

Returns TSV-formatted values separated by tabs. For consistency with CSV, outputs only values without column headers.

Returns:

Type	Description
str	TSV string with values only (one line)

Example

fmt = ResponseFormatter(response)
tsv_str = fmt.to_tsv()
print(tsv_str)

Source code in src/kazunoko/formatter.py

def to_tsv(self) -> str:
    """
    Convert response to TSV format (tab-separated values)

    Returns TSV-formatted values separated by tabs.
    For consistency with CSV, outputs only values without column headers.

    Returns:
        TSV string with values only (one line)

    Example:
        ```python
        fmt = ResponseFormatter(response)
        tsv_str = fmt.to_tsv()
        print(tsv_str)
        ```
    """
    return self._format_sv("\t")