gamesheet_sdk.admin.roster.players module

Player roster operations.

gamesheet_sdk.admin.roster.players.get_player(session, season_id, player_id)

Get a single player by ID.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401.

Parameters:

• session (Session) – An authenticated Session.

• season_id (str) – The parent season identifier.

• player_id (str) – The player identifier to retrieve.

Returns:

The requested Player model instance.

Return type:

Player

Raises:

• AuthenticationError – If the server returns 401.

• GameSheetError – For any other non-2xx response.

gamesheet_sdk.admin.roster.players.list_players(session, season_id)

Return every player in the specified season.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier whose players to list. :type season_id: str :returns: A list of Player, in the order the server returned them. The list may be empty if the

season has no players.

Return type:

list[Player]

gamesheet_sdk.admin.roster.players.list_team_players(session, season_id, team_id)

Return every player for the specified team.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier whose players to list. :type team_id: str :returns: A list of Player, in the order the server returned them. The list may be empty if the

team has no players.

Return type:

list[Player]

gamesheet_sdk.admin.roster.players.create_player(session, season_id, first_name, last_name, *, external_id=None, jersey=None, position=None, status=None, designation=None, team_id=None, biography=None, height=None, weight=None, shot_hand=None, birthdate=None, hometown=None, country=None, province=None, drafted_by=None, committed_to=None, photo_path=None)

Create a new player in the specified season.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier to create the player in. :type season_id: str :param first_name: Player’s first name. :type first_name: str :param last_name: Player’s last name. :type last_name: str :param external_id: Optional external identifier for the player. :type external_id: str | None :param jersey: Optional jersey number. :type jersey: str | None :param position: Optional position (Forward, Defence, Goalie, etc.). :type position: str | None :param status: Optional status (Regular, Affiliated, etc.). :type status: str | None :param designation: Optional designation (Captain, Alternate Captain, etc.). :type designation: str | None :param team_id: Optional team identifier to associate the player with. :type team_id: str | None :param biography: Optional biography text. :type biography: str | None :param height: Optional height (e.g., “6’2"”). :type height: str | None :param weight: Optional weight (e.g., “185”). :type weight: str | None :param shot_hand: Optional shooting hand (left, right). :type shot_hand: str | None :param birthdate: Optional birthdate (ISO format: YYYY-MM-DD). :type birthdate: str | None :param hometown: Optional hometown. :type hometown: str | None :param country: Optional country code (e.g., “US”, “CA”). :type country: str | None :param province: Optional province/state. :type province: str | None :param drafted_by: Optional drafted by team name. :type drafted_by: str | None :param committed_to: Optional committed to institution. :type committed_to: str | None :param photo_path: Optional path to a local photo image file. :type photo_path: str | None :returns: The newly created Player model instance. :rtype: Player :raises AuthenticationError: If the server returns 401. :raises GameSheetError: For any other non-2xx response, or if photo upload fails.

Return type:

Player

gamesheet_sdk.admin.roster.players.get_team_player(session, season_id, team_id, player_id)

Get a single player from a team’s roster.

This function retrieves team roster metadata (number, position, status, etc.) that is only available in the team context, unlike get_player() which fetches from the season-level players endpoint without roster metadata. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier. :type team_id: str :param player_id: The player identifier to retrieve. :type player_id: str :returns: The Player with team roster metadata populated. :rtype: Player :raises GameSheetError: If the player is not found on the team’s roster.

Return type:

Player

gamesheet_sdk.admin.roster.players.create_team_player(session, season_id, team_id, first_name, last_name, *, external_id=None, jersey=None, position=None, status=None, designation=None, biography=None, height=None, weight=None, shot_hand=None, birthdate=None, hometown=None, country=None, province=None, drafted_by=None, committed_to=None, photo_path=None)

Create a new player and add to the specified team’s roster.

This function performs two operations: (1) creates the player at the season level, (2) updates the team’s roster to include the new player with position and other metadata. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier to add the player to. :type team_id: str :param first_name: Player’s first name. :type first_name: str :param last_name: Player’s last name. :type last_name: str :param external_id: Optional external identifier for the player. :type external_id: str | None :param jersey: Optional jersey number. :type jersey: str | None :param position: Optional position (Forward, Defence, Goalie, etc.). :type position: str | None :param status: Optional status (Regular, Affiliated, etc.). :type status: str | None :param designation: Optional designation (Captain, Alternate Captain, etc.). :type designation: str | None :param biography: Optional biography text. :type biography: str | None :param height: Optional height (e.g., “6’2"”). :type height: str | None :param weight: Optional weight (e.g., “185”). :type weight: str | None :param shot_hand: Optional shooting hand (left, right). :type shot_hand: str | None :param birthdate: Optional birthdate (ISO format: YYYY-MM-DD). :type birthdate: str | None :param hometown: Optional hometown. :type hometown: str | None :param country: Optional country code (e.g., “US”, “CA”). :type country: str | None :param province: Optional province/state. :type province: str | None :param drafted_by: Optional drafted by team name. :type drafted_by: str | None :param committed_to: Optional committed to institution. :type committed_to: str | None :param photo_path: Optional path to a local photo image file. :type photo_path: str | None :returns: The newly created Player model instance with roster metadata populated. :rtype: Player :raises AuthenticationError: If the server returns 401. :raises GameSheetError: For any other non-2xx response, or if photo upload fails.

Return type:

Player

gamesheet_sdk.admin.roster.players.update_player(session, season_id, player_id, *, first_name=None, last_name=None, external_id=None, biography=None, height=None, weight=None, shot_hand=None, birthdate=None, hometown=None, country=None, province=None, drafted_by=None, committed_to=None, photo_path=None, remove_photo=False)

Update an existing player in the specified season.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. At least one field must be provided for update. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier containing the player. :type season_id: str :param player_id: The player identifier to update. :type player_id: str :param first_name: Optional updated first name. :type first_name: str | None :param last_name: Optional updated last name. :type last_name: str | None :param external_id: Optional updated external identifier. :type external_id: str | None :param biography: Optional updated biography text. :type biography: str | None :param height: Optional updated height (e.g., “6’2"”). :type height: str | None :param weight: Optional updated weight (e.g., “185”). :type weight: str | None :param shot_hand: Optional updated shooting hand (left, right). :type shot_hand: str | None :param birthdate: Optional updated birthdate (ISO format: YYYY-MM-DD). :type birthdate: str | None :param hometown: Optional updated hometown. :type hometown: str | None :param country: Optional updated country code (e.g., “US”, “CA”). :type country: str | None :param province: Optional updated province/state. :type province: str | None :param drafted_by: Optional updated drafted by team name. :type drafted_by: str | None :param committed_to: Optional updated committed to institution. :type committed_to: str | None :param photo_path: Optional path to a new photo image file. :type photo_path: str | None :param remove_photo: If True, remove the player’s photo. :type remove_photo: bool :returns: The updated Player. :rtype: Player :raises ValueError: If no fields are provided for update or both photo_path and remove_photo are set.

Return type:

Player

gamesheet_sdk.admin.roster.players.update_team_player(session, season_id, team_id, player_id, *, first_name=None, last_name=None, external_id=None, biography=None, height=None, weight=None, shot_hand=None, birthdate=None, hometown=None, country=None, province=None, drafted_by=None, committed_to=None, photo_path=None, remove_photo=False)

Update a player for a specific team.

This function updates the player at the season level. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier. :type team_id: str :param player_id: The player identifier to update. :type player_id: str :param first_name: Optional updated first name. :type first_name: str | None :param last_name: Optional updated last name. :type last_name: str | None :param external_id: Optional updated external identifier. :type external_id: str | None :param biography: Optional updated biography text. :type biography: str | None :param height: Optional updated height (e.g., “6’2"”). :type height: str | None :param weight: Optional updated weight (e.g., “185”). :type weight: str | None :param shot_hand: Optional updated shooting hand (left, right). :type shot_hand: str | None :param birthdate: Optional updated birthdate (ISO format: YYYY-MM-DD). :type birthdate: str | None :param hometown: Optional updated hometown. :type hometown: str | None :param country: Optional updated country code (e.g., “US”, “CA”). :type country: str | None :param province: Optional updated province/state. :type province: str | None :param drafted_by: Optional updated drafted by team name. :type drafted_by: str | None :param committed_to: Optional updated committed to institution. :type committed_to: str | None :param photo_path: Optional path to a new photo image file. :type photo_path: str | None :param remove_photo: If True, remove the player’s photo. :type remove_photo: bool :returns: The updated Player. :rtype: Player :raises ValueError: If no fields are provided for update or both photo_path and remove_photo are set.

Return type:

Player

gamesheet_sdk.admin.roster.players.delete_player(session, season_id, player_id)

Delete a player from the specified season.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier containing the player. :type season_id: str :param player_id: The player identifier to delete. :type player_id: str

gamesheet_sdk.admin.roster.players.unassign_player(session, season_id, player_id, team_id)

Unassign a player from a team’s roster.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param player_id: The player identifier to unassign. :type player_id: str :param team_id: The team identifier to unassign the player from. :type team_id: str :raises GameSheetError: If the player is not assigned to the team.

gamesheet_sdk.admin.roster.players.delete_team_player(session, season_id, team_id, player_id)

Delete a player from a team’s roster and the season.

This function performs two operations: (1) removes the player from the team’s roster, (2) deletes the player at the season level. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier. :type team_id: str :param player_id: The player identifier to delete. :type player_id: str

gamesheet_sdk.admin.roster.players.assign_player(session, season_id, player_id, team_id, *, jersey=None, position=None, status=None, designation=None)

Assign an existing player to a team’s roster.

The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401.

Parameters:

• session (Session) – An authenticated Session.

• season_id (str) – The season identifier.

• player_id (str) – The player identifier to assign.

• team_id (str) – The team identifier to assign the player to.

• jersey (str | None) – Optional jersey number.

• position (str | None) – Optional position (Forward, Defence, Goalie, etc.).

• status (str | None) – Optional status (Regular, Affiliated, etc.).

• designation (str | None) – Optional designation (Captain, Alternate Captain, etc.).

Returns:

The Player with roster metadata populated.

Return type:

Player

Raises:

• GameSheetError – If the player is already assigned to the team.

• AuthenticationError – If the server returns 401.

gamesheet_sdk.admin.roster.players.assign_team_player(session, season_id, team_id, player_id, *, jersey=None, position=None, status=None, designation=None)

Assign an existing player to a team’s roster (team-scoped alias).

This is an alias for assign_player() provided for consistency with the team-scoped command structure. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier to assign the player to. :type team_id: str :param player_id: The player identifier to assign. :type player_id: str :param jersey: Optional jersey number. :type jersey: str | None :param position: Optional position (Forward, Defence, Goalie, etc.). :type position: str | None :param status: Optional status (Regular, Affiliated, etc.). :type status: str | None :param designation: Optional designation (Captain, Alternate Captain, etc.). :type designation: str | None :returns: The Player with roster metadata populated. :rtype: Player :raises GameSheetError: If the player is already assigned to the team. :raises AuthenticationError: If the server returns 401.

Return type:

Player

gamesheet_sdk.admin.roster.players.unassign_team_player(session, season_id, team_id, player_id)

Unassign a player from a team’s roster (team-scoped alias).

This is an alias for unassign_player() provided for consistency with the team-scoped command structure. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param team_id: The team identifier to unassign the player from. :type team_id: str :param player_id: The player identifier to unassign. :type player_id: str

gamesheet_sdk.admin.roster.players.get_player_penalty_report(session, season_id, player_id)

Fetch penalty report for a player.

First retrieves the player to get their external_id, then fetches the penalty report from the BFF API. The supplied Session must already carry a bearer token (e.g. via Session.set_bearer_token()); the call is otherwise unauthenticated and will 401. :param session: An authenticated Session. :type session: Session :param season_id: The season identifier. :type season_id: str :param player_id: The player identifier. :type player_id: str :returns: Penalty report data including player_games, player_penalties, rostered_players, and

season_players.

Return type:

dict[str, Any]