Utilities

Utility functions for working with Nexar models.

sort_players_by_rank(players, *, descending=True, ranked_queue_type=Queue.RANKED_SOLO_5x5) async

Return a list of Player objects sorted by their ranked queue rank.

This function will automatically fetch league entries for each player if not already loaded.

Parameters:

Name	Type	Description	Default
players	Sequence[Player]	Sequence of Player objects	required
descending	bool	If True (default), highest rank first. If False, lowest first.	True
ranked_queue_type	Queue	QueueID.RANKED_SOLO_5x5 or RANKED_FLEX_SR	RANKED_SOLO_5x5

Returns:

Type	Description
list[Player]	List of Player objects sorted by rank (unranked players last).

Example

from nexar.utils import sort_players_by_rank
# Sort by flex queue rank (lowest first)
sorted_players = await sort_players_by_rank(players, descending=False, queue_type=QueueId.RANKED_FLEX_SR)

Source code in nexar/utils.py

async def sort_players_by_rank(
    players: Sequence[Player],
    *,
    descending: bool = True,
    ranked_queue_type: Queue = Queue.RANKED_SOLO_5x5,
) -> list[Player]:
    """
    Return a list of Player objects sorted by their ranked queue rank.

    This function will automatically fetch league entries for each player if not already loaded.

    Args:
        players: Sequence of Player objects
        descending: If True (default), highest rank first. If False, lowest first.
        ranked_queue_type: QueueID.RANKED_SOLO_5x5 or RANKED_FLEX_SR

    Returns:
        List of Player objects sorted by rank (unranked players last).

    Example:
        ```
        from nexar.utils import sort_players_by_rank
        # Sort by flex queue rank (lowest first)
        sorted_players = await sort_players_by_rank(players, descending=False, queue_type=QueueId.RANKED_FLEX_SR)
        ```

    """
    from nexar.models.league import LeagueEntry

    async def get_league_entry(player: Player) -> LeagueEntry | None:
        """Get the league entry for the specified queue type."""
        if ranked_queue_type == Queue.RANKED_SOLO_5x5:
            return await player.get_solo_rank()
        if ranked_queue_type == Queue.RANKED_FLEX_SR:
            return await player.get_flex_rank()

        msg = f"Invalid queue_type: {ranked_queue_type}. Must be QueueId.RANKED_SOLO_5x5 or QueueId.RANKED_FLEX_SR."
        raise ValueError(msg)

    # Create list of (player, league_entry) tuples for sorting
    players_with_ranks = []
    for player in players:
        league_entry = await get_league_entry(player)
        players_with_ranks.append((player, league_entry))

    # Separate ranked and unranked players
    ranked_players = [(player, league_entry) for player, league_entry in players_with_ranks if league_entry is not None]
    unranked_players = [player for player, league_entry in players_with_ranks if league_entry is None]

    # Sort ranked players by their league entry (LeagueEntry objects are directly comparable)
    ranked_players.sort(key=lambda x: x[1], reverse=descending)

    # Combine: ranked players first, then unranked players
    return [player for player, _ in ranked_players] + unranked_players

team_total_percentage(participants, target_participant, stat_selector)

Calculate the percentage of a specific stat for a participant relative to their team's total for that stat.

Parameters:

Name	Type	Description	Default
participants	ParticipantList	List of all participants in the match.	required
target_participant	Participant	The participant for whom to calculate the percentage.	required
stat_selector	Callable[[Participant], int | float]	Lambda expression that takes a Participant and returns the specific stat to calculate	required

Returns:

Type	Description
float	The percentage of the stat for the target participant relative to their team's total for that stat.

Example

from nexar.utils import team_total_percentage
# Calculate the percentage of total team damage dealt by a participant
total_damage = team_total_percentage(
    participants,
    target_participant,
    lambda p: p.total_damage_dealt_to_champions,
)

Source code in nexar/utils.py

def team_total_percentage(
    participants: ParticipantList,
    target_participant: Participant,
    stat_selector: Callable[[Participant], int | float],
) -> float:
    """
    Calculate the percentage of a specific stat for a participant relative to their team's total for that stat.

    Args:
        participants: List of all participants in the match.
        target_participant: The participant for whom to calculate the percentage.
        stat_selector: Lambda expression that takes a Participant and returns the specific stat to calculate

    Returns:
        The percentage of the stat for the target participant relative to their team's total for that stat.

    Example:
        ```
        from nexar.utils import team_total_percentage
        # Calculate the percentage of total team damage dealt by a participant
        total_damage = team_total_percentage(
            participants,
            target_participant,
            lambda p: p.total_damage_dealt_to_champions,
        )
        ```

    """
    total_stat_by_team = sum([stat_selector(p) for p in participants.by_team(target_participant.team_id)])
    if total_stat_by_team == 0:
        return 0.0
    return stat_selector(target_participant) / total_stat_by_team * 100