Skip to content

ParticipantList

Bases: list['Participant']

A specialized list for match participants with ergonomic filtering methods.

Extends the built-in list while providing convenient methods for common participant queries and filters.

Source code in nexar/models/match/participant_list.py 
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
class ParticipantList(list["Participant"]):
    """
    A specialized list for match participants with ergonomic filtering methods.

    Extends the built-in list while providing convenient methods for common
    participant queries and filters.
    """

    def by_puuid(self, puuid: str) -> "Participant | None":
        """
        Find a participant by their PUUID.

        Args:
            puuid: The player's universally unique identifier

        Returns:
            The participant with the matching PUUID, or None if not found

        """
        return next((p for p in self if p.puuid == puuid), None)

    def by_champion(self, champion_name: str) -> "ParticipantList":
        """
        Filter participants by champion name.

        Args:
            champion_name: The champion name (case-insensitive)

        Returns:
            A new ParticipantList containing participants playing the specified champion

        """
        return ParticipantList(p for p in self if p.champion_name.lower() == champion_name.lower())

    def by_position(self, position: MatchParticipantPosition) -> "ParticipantList":
        """
        Filter participants by their team position.

        Args:
            position: The position to filter by

        Returns:
            A new ParticipantList containing participants in the specified position

        """
        return ParticipantList(p for p in self if p.team_position == position)

    def by_team(self, team_id: int) -> "ParticipantList":
        """
        Filter participants by team ID.

        Args:
            team_id: The team ID (100 for blue, 200 for red)

        Returns:
            A new ParticipantList containing participants on the specified team

        """
        return ParticipantList(p for p in self if p.team_id == team_id)

    def blue_team(self) -> "ParticipantList":
        """
        Get all participants on the blue team.

        Returns:
            A new ParticipantList containing blue team participants

        """
        return self.by_team(100)

    def red_team(self) -> "ParticipantList":
        """
        Get all participants on the red team.

        Returns:
            A new ParticipantList containing red team participants

        """
        return self.by_team(200)

    def winners(self) -> "ParticipantList":
        """
        Get all participants who won the match.

        Returns:
            A new ParticipantList containing winning participants

        """
        return ParticipantList(p for p in self if p.win)

    def losers(self) -> "ParticipantList":
        """
        Get all participants who lost the match.

        Returns:
            A new ParticipantList containing losing participants

        """
        return ParticipantList(p for p in self if not p.win)

    def team_of(self, puuid: str) -> "ParticipantList":
        """
        Get the team of the participant with the given PUUID.

        Args:
            puuid: The player's universally unique identifier

        Returns:
            A ParticipantList containing all participants on the same team as the specified PUUID.

        Raises:
            ValueError: If no participant with the given PUUID is found.

        """
        participant = self.by_puuid(puuid)
        if participant is None:
            msg = f"No participant found with PUUID: {puuid}"
            raise ValueError(msg)
        return self.by_team(participant.team_id)

    def filter(self, predicate: Callable[["Participant"], bool]) -> "ParticipantList":
        """
        Filter participants using a custom predicate function.

        Args:
            predicate: A function that takes a Participant and returns True/False

        Returns:
            A new ParticipantList containing participants that match the predicate

        """
        return ParticipantList(p for p in self if predicate(p))

    def sort_by(
        self,
        key: Callable[["Participant"], Any],
        *,
        reverse: bool = False,
    ) -> "ParticipantList":
        """
        Sort participants by a custom key function.

        Args:
            key: A function that takes a Participant and returns a sortable value
            reverse: Whether to sort in descending order

        Returns:
            A new ParticipantList with participants sorted by the key

        """
        return ParticipantList(sorted(self, key=key, reverse=reverse))

    def highest_kda(self, count: int = 1) -> "ParticipantList":
        """
        Get participants with the highest KDA ratios.

        Args:
            count: Number of top participants to return

        Returns:
            A new ParticipantList with the highest KDA participants

        """

        def kda_ratio(participant: "Participant") -> float:
            if participant.deaths == 0:
                return float(participant.kills + participant.assists)
            return (participant.kills + participant.assists) / participant.deaths

        return ParticipantList(self.sort_by(kda_ratio, reverse=True)[:count])

    def most_kills(self, count: int = 1) -> "ParticipantList":
        """
        Get participants with the most kills.

        Args:
            count: Number of top participants to return

        Returns:
            A new ParticipantList with the most kills

        """
        return ParticipantList(self.sort_by(lambda p: p.kills, reverse=True)[:count])

    def most_damage(self, count: int = 1) -> "ParticipantList":
        """
        Get participants who dealt the most damage to champions.

        Args:
            count: Number of top participants to return

        Returns:
            A new ParticipantList with the highest damage dealers

        """
        return ParticipantList(self.sort_by(lambda p: p.total_damage_dealt_to_champions, reverse=True)[:count])

    @overload
    def __getitem__(self, key: SupportsIndex) -> "Participant": ...

    @overload
    def __getitem__(self, key: slice) -> "ParticipantList": ...

    def __getitem__(self, key: SupportsIndex | slice) -> "Participant | ParticipantList":
        result = super().__getitem__(key)
        if isinstance(key, slice):
            msg = "Slicing a ParticipantList did not return a list as expected."
            if not isinstance(result, list):
                raise TypeError(msg)
            return ParticipantList(result)
        # Defensive: ensure only a Participant is returned for int
        if not isinstance(result, self._participant_type()):
            msg = "Indexing a ParticipantList did not return a Participant as expected."
            raise TypeError(msg)
        return cast("Participant", result)

    @staticmethod
    def _participant_type() -> type:
        from .participant import Participant

        return Participant

blue_team()

Get all participants on the blue team.

Returns:

Type Description
ParticipantList

A new ParticipantList containing blue team participants
Source code in nexar/models/match/participant_list.py 
72
73
74
75
76
77
78
79
80
def blue_team(self) -> "ParticipantList":
    """
    Get all participants on the blue team.

    Returns:
        A new ParticipantList containing blue team participants

    """
    return self.by_team(100)

by_champion(champion_name)

Filter participants by champion name.

Parameters:

Name Type Description Default
champion_name str

The champion name (case-insensitive)

 required

Returns:

Type Description
ParticipantList

A new ParticipantList containing participants playing the specified champion
Source code in nexar/models/match/participant_list.py 
33
34
35
36
37
38
39
40
41
42
43
44
def by_champion(self, champion_name: str) -> "ParticipantList":
    """
    Filter participants by champion name.

    Args:
        champion_name: The champion name (case-insensitive)

    Returns:
        A new ParticipantList containing participants playing the specified champion

    """
    return ParticipantList(p for p in self if p.champion_name.lower() == champion_name.lower())

by_position(position)

Filter participants by their team position.

Parameters:

Name Type Description Default
position MatchParticipantPosition

The position to filter by

 required

Returns:

Type Description
ParticipantList

A new ParticipantList containing participants in the specified position
Source code in nexar/models/match/participant_list.py 
46
47
48
49
50
51
52
53
54
55
56
57
def by_position(self, position: MatchParticipantPosition) -> "ParticipantList":
    """
    Filter participants by their team position.

    Args:
        position: The position to filter by

    Returns:
        A new ParticipantList containing participants in the specified position

    """
    return ParticipantList(p for p in self if p.team_position == position)

by_puuid(puuid)

Find a participant by their PUUID.

Parameters:

Name Type Description Default
puuid str

The player's universally unique identifier

 required

Returns:

Type Description
Participant | None

The participant with the matching PUUID, or None if not found
Source code in nexar/models/match/participant_list.py 
20
21
22
23
24
25
26
27
28
29
30
31
def by_puuid(self, puuid: str) -> "Participant | None":
    """
    Find a participant by their PUUID.

    Args:
        puuid: The player's universally unique identifier

    Returns:
        The participant with the matching PUUID, or None if not found

    """
    return next((p for p in self if p.puuid == puuid), None)

by_team(team_id)

Filter participants by team ID.

Parameters:

Name Type Description Default
team_id int

The team ID (100 for blue, 200 for red)

 required

Returns:

Type Description
ParticipantList

A new ParticipantList containing participants on the specified team
Source code in nexar/models/match/participant_list.py 
59
60
61
62
63
64
65
66
67
68
69
70
def by_team(self, team_id: int) -> "ParticipantList":
    """
    Filter participants by team ID.

    Args:
        team_id: The team ID (100 for blue, 200 for red)

    Returns:
        A new ParticipantList containing participants on the specified team

    """
    return ParticipantList(p for p in self if p.team_id == team_id)

filter(predicate)

Filter participants using a custom predicate function.

Parameters:

Name Type Description Default
predicate Callable[[Participant], bool]

A function that takes a Participant and returns True/False

 required

Returns:

Type Description
ParticipantList

A new ParticipantList containing participants that match the predicate
Source code in nexar/models/match/participant_list.py 
132
133
134
135
136
137
138
139
140
141
142
143
def filter(self, predicate: Callable[["Participant"], bool]) -> "ParticipantList":
    """
    Filter participants using a custom predicate function.

    Args:
        predicate: A function that takes a Participant and returns True/False

    Returns:
        A new ParticipantList containing participants that match the predicate

    """
    return ParticipantList(p for p in self if predicate(p))

highest_kda(count=1)

Get participants with the highest KDA ratios.

Parameters:

Name Type Description Default
count int

Number of top participants to return

 1

Returns:

Type Description
ParticipantList

A new ParticipantList with the highest KDA participants
Source code in nexar/models/match/participant_list.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def highest_kda(self, count: int = 1) -> "ParticipantList":
    """
    Get participants with the highest KDA ratios.

    Args:
        count: Number of top participants to return

    Returns:
        A new ParticipantList with the highest KDA participants

    """

    def kda_ratio(participant: "Participant") -> float:
        if participant.deaths == 0:
            return float(participant.kills + participant.assists)
        return (participant.kills + participant.assists) / participant.deaths

    return ParticipantList(self.sort_by(kda_ratio, reverse=True)[:count])

losers()

Get all participants who lost the match.

Returns:

Type Description
ParticipantList

A new ParticipantList containing losing participants
Source code in nexar/models/match/participant_list.py 
102
103
104
105
106
107
108
109
110
def losers(self) -> "ParticipantList":
    """
    Get all participants who lost the match.

    Returns:
        A new ParticipantList containing losing participants

    """
    return ParticipantList(p for p in self if not p.win)

most_damage(count=1)

Get participants who dealt the most damage to champions.

Parameters:

Name Type Description Default
count int

Number of top participants to return

 1

Returns:

Type Description
ParticipantList

A new ParticipantList with the highest damage dealers
Source code in nexar/models/match/participant_list.py 
196
197
198
199
200
201
202
203
204
205
206
207
def most_damage(self, count: int = 1) -> "ParticipantList":
    """
    Get participants who dealt the most damage to champions.

    Args:
        count: Number of top participants to return

    Returns:
        A new ParticipantList with the highest damage dealers

    """
    return ParticipantList(self.sort_by(lambda p: p.total_damage_dealt_to_champions, reverse=True)[:count])

most_kills(count=1)

Get participants with the most kills.

Parameters:

Name Type Description Default
count int

Number of top participants to return

 1

Returns:

Type Description
ParticipantList

A new ParticipantList with the most kills
Source code in nexar/models/match/participant_list.py 
183
184
185
186
187
188
189
190
191
192
193
194
def most_kills(self, count: int = 1) -> "ParticipantList":
    """
    Get participants with the most kills.

    Args:
        count: Number of top participants to return

    Returns:
        A new ParticipantList with the most kills

    """
    return ParticipantList(self.sort_by(lambda p: p.kills, reverse=True)[:count])

red_team()

Get all participants on the red team.

Returns:

Type Description
ParticipantList

A new ParticipantList containing red team participants
Source code in nexar/models/match/participant_list.py 
82
83
84
85
86
87
88
89
90
def red_team(self) -> "ParticipantList":
    """
    Get all participants on the red team.

    Returns:
        A new ParticipantList containing red team participants

    """
    return self.by_team(200)

sort_by(key, *, reverse=False)

Sort participants by a custom key function.

Parameters:

Name Type Description Default
key Callable[[Participant], Any]

A function that takes a Participant and returns a sortable value

 required
reverse bool

Whether to sort in descending order

 False

Returns:

Type Description
ParticipantList

A new ParticipantList with participants sorted by the key
Source code in nexar/models/match/participant_list.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def sort_by(
    self,
    key: Callable[["Participant"], Any],
    *,
    reverse: bool = False,
) -> "ParticipantList":
    """
    Sort participants by a custom key function.

    Args:
        key: A function that takes a Participant and returns a sortable value
        reverse: Whether to sort in descending order

    Returns:
        A new ParticipantList with participants sorted by the key

    """
    return ParticipantList(sorted(self, key=key, reverse=reverse))

team_of(puuid)

Get the team of the participant with the given PUUID.

Parameters:

Name Type Description Default
puuid str

The player's universally unique identifier

 required

Returns:

Type Description
ParticipantList

A ParticipantList containing all participants on the same team as the specified PUUID.

Raises:

Type Description
ValueError

If no participant with the given PUUID is found.
Source code in nexar/models/match/participant_list.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def team_of(self, puuid: str) -> "ParticipantList":
    """
    Get the team of the participant with the given PUUID.

    Args:
        puuid: The player's universally unique identifier

    Returns:
        A ParticipantList containing all participants on the same team as the specified PUUID.

    Raises:
        ValueError: If no participant with the given PUUID is found.

    """
    participant = self.by_puuid(puuid)
    if participant is None:
        msg = f"No participant found with PUUID: {puuid}"
        raise ValueError(msg)
    return self.by_team(participant.team_id)

winners()

Get all participants who won the match.

Returns:

Type Description
ParticipantList

A new ParticipantList containing winning participants
Source code in nexar/models/match/participant_list.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
def winners(self) -> "ParticipantList":
    """
    Get all participants who won the match.

    Returns:
        A new ParticipantList containing winning participants

    """
    return ParticipantList(p for p in self if p.win)