# Copyright (c) 2026 bdperkin
# SPDX-License-Identifier: MIT
"""Common CLI option decorators."""
from __future__ import annotations
from collections.abc import Callable
from typing import TypeVar
import rich_click as click
from rich_click import Choice, Path
from gamesheet_sdk.common.output import ALL_FORMATS, DEFAULT_FORMAT
F = TypeVar("F", bound=Callable[..., object])
[docs]
def common_output_options(func: F) -> F:
"""Add standard --format and --output options to command.
:param func: The Click command function to decorate
:type func: F
:returns: The decorated function with --format and --output options
:rtype: F
"""
func = click.option(
"--format",
"-F",
"output_format",
type=Choice(list(ALL_FORMATS), case_sensitive=False),
default=DEFAULT_FORMAT,
show_default=True,
help=(
"Output format. Data formats: json, yaml, csv, tsv. Human-readable "
"tabulate formats: plain, simple, grid, fancy_grid, pipe, orgtbl, "
"rst, mediawiki, html, latex, latex_raw, latex_booktabs, latex_longtable."
),
)(func)
func = click.option(
"--output",
"-o",
"output_path",
type=Path(dir_okay=False, writable=True),
default=None,
help="Write to this file instead of stdout.",
)(func)
return func
[docs]
def list_columns_option(func: F) -> F:
"""Add --columns option for list commands.
:param func: The Click command function to decorate
:type func: F
:returns: The decorated function with --columns option
:rtype: F
"""
return click.option(
"--columns",
"-c",
"columns_spec",
default=None,
help="Comma-separated list of column names to include (default: all columns the API returns).",
)(func)
[docs]
def get_fields_option(func: F) -> F:
"""Add --fields option for get commands.
:param func: The Click command function to decorate
:type func: F
:returns: The decorated function with --fields option
:rtype: F
"""
return click.option(
"--fields",
"-f",
"fields_spec",
default=None,
help="Comma-separated list of field names to include (default: all fields the API returns).",
)(func)
[docs]
def team_update_options(func: F) -> F:
"""Add common team update options.
:param func: The Click command function to decorate
:type func: F
:returns: The decorated function with team update options
:rtype: F
"""
func = click.option(
"--title",
type=str,
default=None,
help="New team name/title.",
)(func)
func = click.option(
"--division-id",
type=str,
default=None,
help="New division ID.",
)(func)
func = click.option(
"--external-id",
type=str,
default=None,
help="New external identifier.",
)(func)
func = click.option(
"--logo",
"logo_path",
type=Path(exists=True, dir_okay=False),
help="Path to a new logo image file.",
)(func)
func = click.option(
"--remove-logo",
is_flag=True,
default=False,
help="Remove the team's logo.",
)(func)
return func
[docs]
def team_create_options(func: F) -> F:
"""Add common team create options.
:param func: The Click command function to decorate
:type func: F
:returns: The decorated function with team create options
:rtype: F
"""
func = click.option(
"--external-id",
type=str,
default=None,
help="Optional external identifier for the team.",
)(func)
func = click.option(
"--logo",
"logo_path",
type=Path(exists=True, dir_okay=False),
help="Optional path to a local logo image file.",
)(func)
return func