gamesheet_sdk.common.cli.game_options module

The unified game option set shared by gamesheet-admin games and gamesheet-teams schedule games.

The two command trees drive different backends — a JSON:API season schedule for admin, the teams gateway’s /api/schedule-game for teams — but expose one option vocabulary, so a command line written for either CLI runs unchanged on the other.

The two backends disagree on how a game’s two teams are named. admin names them absolutely, as --home-team-id / --visitor-team-id and their divisions. teams names them relative to “my” team, as --team-id / --opposing-team-id plus a side flag — --home / --visitor, spelled --away on update — saying which side that team is on.

Both spellings are accepted by both CLIs. resolve_game_sides() translates whichever was given into GameSides, which carries the absolute pair plus the home_flag each backend needs. These are therefore equivalent everywhere:

--home-team-id 10 --visitor-team-id 20
--team-id 10 --opposing-team-id 20 --home
--team-id 20 --opposing-team-id 10 --visitor

Naming the same side twice with different values is a usage error.

class gamesheet_sdk.common.cli.game_options.GameArgs

Bases: object

A typed view over the unified game option set.

The game commands take **params rather than three dozen named parameters, and turn it into one of these. Every field is optional at this level; create enforces its own requirements via GameSides.require() and click’s required=.

sides

The resolved home/visitor pair.

Type:

GameSides

times

The raw start/end/duration inputs.

Type:

GameTimeArgs

season_id

--season-id.

Type:

str | None

game_id

--game-id / -g / --id.

Type:

str | None

number

--number / --game-number.

Type:

str | None

game_type

--game-type.

Type:

str | None

location

--location.

Type:

str | None

scorekeeper_name

--scorekeeper-name.

Type:

str | None

scorekeeper_phone

--scorekeeper-phone.

Type:

str | None

broadcaster

--broadcaster / --broadcast-provider.

Type:

str | None

time_zone_name

--time-zone-name / --timezone.

Type:

str | None

time_zone_offset

--time-zone-offset.

Type:

int | None

home_label

--home-label; admin-only.

Type:

str | None

visitor_label

--visitor-label; admin-only.

Type:

str | None

output_format

--format / -F.

Type:

str

output_path

--output / -o.

Type:

str | None

columns_spec

--columns / -c.

Type:

str | None

sides: GameSides

times: GameTimeArgs

season_id: str | None

game_id: str | None

number: str | None

game_type: str | None

location: str | None

scorekeeper_name: str | None

scorekeeper_phone: str | None

broadcaster: str | None

time_zone_name: str | None

time_zone_offset: int | None

home_label: str | None

visitor_label: str | None

output_format: str

output_path: str | None

columns_spec: str | None

__init__(sides, times, season_id, game_id, number, game_type, location, scorekeeper_name, scorekeeper_phone, broadcaster, time_zone_name, time_zone_offset, home_label, visitor_label, output_format, output_path, columns_spec)

class gamesheet_sdk.common.cli.game_options.GameSides

Bases: object

A game’s two teams, held absolutely, plus which side is the acting team.

home_team_id

Home team identifier.

Type:

str | None

home_division_id

Home team’s division identifier.

Type:

str | None

visitor_team_id

Visitor team identifier.

Type:

str | None

visitor_division_id

Visitor team’s division identifier.

Type:

str | None

home_flag

Whether the acting team (--team-id) is the home team.

Type:

bool

home_team_id: str | None

home_division_id: str | None

visitor_team_id: str | None

visitor_division_id: str | None

home_flag: bool

property team_id: str | None

The acting team’s identifier.

Returns:

str | None – home_team_id when the acting team is home, else visitor_team_id.

property division_id: str | None

The acting team’s division identifier.

Returns:

str | None – home_division_id when the acting team is home, else visitor_division_id.

property opposing_team_id: str | None

The opposing team’s identifier.

Returns:

str | None – visitor_team_id when the acting team is home, else home_team_id.

property opposing_division_id: str | None

The opposing team’s division identifier.

Returns:

str | None – visitor_division_id when the acting team is home, else home_division_id.

require()

Narrow to a RequiredGameSides, rejecting any side left unspecified.

Returns:

RequiredGameSides – The same sides with every identifier known to be present.

Return type:

RequiredGameSides

__init__(home_team_id, home_division_id, visitor_team_id, visitor_division_id, home_flag)

class gamesheet_sdk.common.cli.game_options.GameTimeArgs

Bases: object

The seven start/end/duration inputs, straight off the command line.

start_datetime

--start-datetime / --start-date-time / --start.

Type:

str | None

start_date

--start-date / --date.

Type:

str | None

start_time

--start-time.

Type:

str | None

end_datetime

--end-datetime / --end-date-time / --end.

Type:

str | None

end_date

--end-date.

Type:

str | None

end_time

--end-time.

Type:

str | None

duration

--duration, in any accepted spelling.

Type:

str | None

start_datetime: str | None

start_date: str | None

start_time: str | None

end_datetime: str | None

end_date: str | None

end_time: str | None

duration: str | None

__init__(start_datetime, start_date, start_time, end_datetime, end_date, end_time, duration)

class gamesheet_sdk.common.cli.game_options.RequiredGameSides

Bases: object

A fully specified pair of sides, as create needs.

home_team_id

Home team identifier.

Type:

str

home_division_id

Home team’s division identifier.

Type:

str

visitor_team_id

Visitor team identifier.

Type:

str

visitor_division_id

Visitor team’s division identifier.

Type:

str

home_flag

Whether the acting team (--team-id) is the home team.

Type:

bool

home_team_id: str

home_division_id: str

visitor_team_id: str

visitor_division_id: str

home_flag: bool

property team_id: str

The acting team’s identifier.

Returns:

str – home_team_id when the acting team is home, else visitor_team_id.

property division_id: str

The acting team’s division identifier.

Returns:

str – home_division_id when the acting team is home, else visitor_division_id.

property opposing_team_id: str

The opposing team’s identifier.

Returns:

str – visitor_team_id when the acting team is home, else home_team_id.

property opposing_division_id: str

The opposing team’s division identifier.

Returns:

str – visitor_division_id when the acting team is home, else home_division_id.

__init__(home_team_id, home_division_id, visitor_team_id, visitor_division_id, home_flag)

gamesheet_sdk.common.cli.game_options.explicit_side_flag(params)

Return the side the user actually named, or None if they named none.

update sends home_flag to the teams gateway only when it was explicitly given, so an update that does not mention a side leaves the game’s existing side alone.

Parameters:

params (Mapping[str, Any]) – The command’s collected parameters.

Returns:

bool | None – True for --home, False for --visitor/--away, None for neither.

Return type:

bool | None

gamesheet_sdk.common.cli.game_options.game_detail_options(*, required)

Build the decorator adding the non-time, non-side game options.

Parameters:

required (bool) – Whether --game-type and --number are mandatory, as they are on create.

Returns:

Callable[[F], F] – The option decorator.

Return type:

Callable[[F], F]

gamesheet_sdk.common.cli.game_options.game_id_option(func)

Add the --game-id option under all three accepted spellings.

Parameters:

func (F) – The command function to decorate.

Returns:

F – The decorated command function.

Return type:

F

gamesheet_sdk.common.cli.game_options.game_side_options(func)

Add both spellings of the home/visitor team and division options.

Requiredness is enforced by resolve_game_sides(), not by click, because each side has two accepted spellings and click can only require one option at a time.

Parameters:

func (F) – The command function to decorate.

Returns:

F – The decorated command function.

Return type:

F

gamesheet_sdk.common.cli.game_options.game_time_options(func)

Add the seven start/end/duration options both CLIs accept.

Parameters:

func (F) – The command function to decorate.

Returns:

F – The decorated command function.

Return type:

F

gamesheet_sdk.common.cli.game_options.parse_game_args(params)

Turn a game command’s collected click parameters into a GameArgs.

Parameters:

params (Mapping[str, Any]) – The command’s collected parameters.

Returns:

GameArgs – The typed view.

Return type:

GameArgs

gamesheet_sdk.common.cli.game_options.requiredness(*, required)

Build the required/default keyword pair for an option.

Gotcha worth preserving: click 8.4.2 silently ignores required=True when default=None is also passed explicitly — the option simply arrives as None and the body runs. Passing no default at all is not the same thing as passing default=None, even though click’s implicit default is None. So a required option must omit the key entirely.

Parameters:

required (bool) – Whether the option is mandatory.

Returns:

dict[str, Any] – Keyword arguments to splat into click.option().

Return type:

dict[str, Any]

gamesheet_sdk.common.cli.game_options.resolve_game_sides(*, home_team_id, home_division_id, visitor_team_id, visitor_division_id, team_id, division_id, opposing_team_id, opposing_division_id, home_flag, away_flag=False, default_home=True)

Translate whichever team-naming spelling was used into a single GameSides.

Parameters:

• home_team_id (str | None) – --home-team-id.

• home_division_id (str | None) – --home-division-id.

• visitor_team_id (str | None) – --visitor-team-id.

• visitor_division_id (str | None) – --visitor-division-id.

• team_id (str | None) – --team-id, the acting team.

• division_id (str | None) – --division-id, the acting team’s division.

• opposing_team_id (str | None) – --opposing-team-id.

• opposing_division_id (str | None) – --opposing-division-id / --opposing-division.

• home_flag (bool | None) – --home / --visitor.

• away_flag (bool) – --away, an alias for --visitor.

• default_home (bool) – Which side to assume when no side flag was given.

Returns:

GameSides – The resolved sides.

Return type:

GameSides

gamesheet_sdk.common.cli.game_options.resolve_side_flag(*, home_flag, away_flag, default=True)

Collapse --home/--visitor and the --away alias into one boolean.

Parameters:

• home_flag (bool | None) – True for --home, False for --visitor, None if neither.

• away_flag (bool) – Whether --away was given.

• default (bool) – Value to use when neither flag was given. create leaves this at True; update passes the game’s current side so the absolute option names keep their meaning.

Returns:

bool – Whether the acting team is the home team.

Raises:

UsageError – If --home and --away are both given.

Return type:

bool

gamesheet_sdk.common.cli.game_options.season_id_option(*, required)

Build the --season-id decorator.

Parameters:

required (bool) – Whether the option is mandatory. gamesheet-admin passes False because the value may instead come from the games group.

Returns:

Callable[[F], F] – The option decorator.

Return type:

Callable[[F], F]

gamesheet_sdk.common.cli.game_options.sides_from_params(params, *, default_home=True)

Collect and resolve the side options out of the raw click params.

Parameters:

• params (Mapping[str, Any]) – The command’s collected parameters.

• default_home (bool) – Which side to assume when no side flag was given.

Returns:

GameSides – The resolved sides.

Return type:

GameSides

gamesheet_sdk.common.cli.game_options.warn_unsupported_options(cli_name, ignored)

Warn on stderr for options this backend cannot send, then carry on.

The unified option set is deliberately wider than either backend’s payload so that a command line stays portable. Anything the receiving backend has no field for is dropped with a warning rather than an error, and the exit status is unaffected.

Parameters:

• cli_name (str) – The CLI the caller is running as, e.g. 'gamesheet-teams'.

• ignored (Mapping[str, object]) – Option name to supplied value. Falsy values are not reported.