gamesheet_sdk.common.output

Multi-format rendering of tabular data for CLI workflows.

Every SDK workflow that produces a list of rows (associations, leagues, teams, …) flows through render() to get a string. Supported formats fall into two groups. Data formats (machine-friendly, not via tabulate): json, yaml, csv, tsv. Tabulate formats (human-readable or markup- embeddable; every tablefmt value tabulate accepts): plain, simple, grid, fancy_grid, pipe, orgtbl, rst, mediawiki, html, latex, latex_raw, latex_booktabs, latex_longtable. The default format is simple. write_output() complements render() by writing the rendered text to a file path (when one is given) or to stdout (with optional rich-driven syntax highlighting when stdout is a TTY and the format is json or yaml).

Functions

render(rows[, fmt, columns])	Render rows as a string in the requested format.
write_output(text, path, *, fmt)	Write text to path or to stdout.

gamesheet_sdk.common.output.render(rows, fmt='simple', *, columns=None)

Render rows as a string in the requested format.

Parameters:

• rows (list[dict[str, Any]]) – A list of mappings – each becomes one row.

• fmt (str) – One of ALL_FORMATS. Defaults to DEFAULT_FORMAT ("simple").

• columns (list[str] | None) – Restrict and order the column set. If None and rows is non-empty, the first row’s keys are used in their natural order.

Returns:

Rendered string in the requested format.

Return type:

str

Raises:

ValueError – If fmt is not in ALL_FORMATS.

Example usage:

from gamesheet_sdk.common.output import render

rows = [{"id": 123, "name": "Example"}, {"id": 456, "name": "Another"}]

# Simple table format
print(render(rows, fmt="simple"))
# Output:
#   id   name
# ---  -------
# 123  Example
# 456  Another

# JSON format
print(render(rows, fmt="json"))
# Output:
# [
#     {
#         "id": 123,
#         "name": "Example"
#     },
#     {
#         "id": 456,
#         "name": "Another"
#     }
# ]

# CSV format
print(render(rows, fmt="csv"))
# Output:
# id,name
# 123,Example
# 456,Another

gamesheet_sdk.common.output.write_output(text, path, *, fmt)

Write text to path or to stdout.

When path is None and stdout is a TTY, JSON and YAML output is syntax-highlighted via rich.syntax.Syntax. Other formats and any non-TTY destination receive text verbatim with a trailing newline if it does not already have one.

File output example:

>>> from gamesheet_sdk.common.output import render, write_output
>>> rows = [{"id": 123, "name": "Example"}]
>>> text = render(rows, fmt="json")
>>> write_output(text, "output.json", fmt="json")
# Writes to output.json with trailing newline

TTY stdout example (JSON/YAML only):

>>> from gamesheet_sdk.common.output import write_output
>>> write_output(text, None, fmt="json")
# Syntax-highlighted output to terminal if stdout is a TTY

Non-TTY / other formats:

>>> from gamesheet_sdk.common.output import write_output
>>> write_output(text, None, fmt="csv")
# Plain text to stdout with trailing newline

Parameters:

• text (str) – Rendered output string to write.

• path (str | Path | None) – Destination file path (str or pathlib.Path), or None for stdout.

• fmt (str) – Format name (e.g. "json", "yaml", "csv"); controls syntax highlighting on TTY stdout.