Skip to content

Client

Documentation related to the default and async client the package provides.

Client for interacting with the Marvel Rivals API.

This client allows for fetching hero data from the Marvel Rivals API.

Parameters:

Name Type Description Default
api_key str

The API key to authenticate requests to the Marvel Rivals API.

 required

Attributes:

Name Type Description
client Client

The HTTP client used for making requests.
Source code in marvelrivalsapi\client.py 
 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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
@define
class MarvelRivalsClient:
    """
    Client for interacting with the Marvel Rivals API.

    This client allows for fetching hero data from the Marvel Rivals API.

    Parameters
    ----------
    api_key : str
        The API key to authenticate requests to the Marvel Rivals API.

    Attributes
    ----------
    client : httpx.Client
        The HTTP client used for making requests.
    """

    api_key: str
    client: httpx.Client = field(init=False)

    def __attrs_post_init__(self) -> None:
        self.client = httpx.Client(headers={"x-api-key": self.api_key})

    def throw(self, res: httpx.Response) -> None:
        raise MarvelRivalsAPIError(res)

    @typing.overload
    def get_hero(self, hero: str | Heroes, *, error: bool) -> Hero: ...

    @typing.overload
    def get_hero(self, hero: str | Heroes) -> Hero | None: ...

    def get_hero(self, hero: str | Heroes, *, error: bool = False) -> Hero | None:
        """
        Get a hero by name or ID.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve.
        error : bool | None
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        Hero | None
            The hero if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> hero = client.get_hero("Spider-Man")
        >>> if hero:
        ...     print(hero.name)
        """
        response = self.client.get(
            Endpoints.GET_HERO(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            return Hero.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    def get_all_heroes(self, *, error: bool) -> list[Hero]: ...

    @typing.overload
    def get_all_heroes(
        self,
    ) -> list[Hero] | None: ...

    def get_all_heroes(self, *, error: bool = False) -> list[Hero] | None:
        """
        Get all available heroes.

        Parameters
        ----------
        error : bool | None
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        list[Hero] | None
            A list of all heroes if successful, None if the request fails and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> heroes = client.get_all_heroes()
        >>> if heroes:
        ...     for hero in heroes:
        ...         print(hero.name)
        """
        response = self.client.get(Endpoints.ALL_HEROES())
        if response.status_code == 200:
            return [Hero.from_dict(hero) for hero in response.json()]
        return None if not error else self.throw(response)

    @typing.overload
    def get_hero_stat(self, hero: str | Heroes, *, error: bool) -> HeroStat: ...

    @typing.overload
    def get_hero_stat(self, hero: str | Heroes) -> HeroStat | None: ...

    def get_hero_stat(
        self, hero: str | Heroes, *, error: bool = False
    ) -> HeroStat | None:
        """
        Get hero stats by name or ID.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve stats for.
        error : bool | None
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        dict[str, typing.Any] | None
            The hero stats if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> stats = client.get_hero_stat("spider-man")
        >>> if stats:
        ...     print(stats)
        """
        response = self.client.get(
            Endpoints.HERO_STATS(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            print(response.json())
            return HeroStat.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str, *, error: bool
    ) -> HeroLeaderboard: ...

    @typing.overload
    def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str
    ) -> HeroLeaderboard | None: ...

    @typing.overload
    def get_hero_leaderboard(
        self, hero: str | Heroes, *, error: bool
    ) -> HeroLeaderboard: ...

    @typing.overload
    def get_hero_leaderboard(self, hero: str | Heroes) -> HeroLeaderboard | None: ...

    def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str = "pc", *, error: bool = False
    ) -> HeroLeaderboard | None:
        """
        Get hero leaderboard by name or ID.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve stats for.
        error : bool | None
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        dict[HeroLeaderboard] | None
            The hero stats if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> stats = client.get_hero_leaderboard("spider-man")
        >>> if stats:
        ...     print(stats)
        """
        response = self.client.get(
            Endpoints.HERO_LEADERBOARD(
                hero.value if isinstance(hero, Heroes) else hero, platform
            )
        )
        if response.status_code == 200:
            return HeroLeaderboard.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    def get_hero_costumes(
        self, hero: str | Heroes, *, error: bool
    ) -> list[Costume]: ...

    @typing.overload
    def get_hero_costumes(self, hero: str | Heroes) -> list[Costume] | None: ...

    def get_hero_costumes(
        self, hero: str | Heroes, *, error: bool = False
    ) -> list[Costume] | None:
        """
        Get all costumes for a specific hero.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve costumes for.
        error : bool | None
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        list[Costume] | None
            A list of all costumes for the specified hero if successful,
            None if the request fails and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> costumes = client.get_hero_costumes("spider-man")
        >>> if costumes:
        ...     for costume in costumes:
        ...         print(costume.name)
        """
        response = self.client.get(
            Endpoints.ALL_COSTUMES(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            return [Costume.from_dict(costume) for costume in response.json()]
        return None if not error else self.throw(response)

    @typing.overload
    def get_costume(
        self, hero: str | Heroes, costume_id: str, *, error: bool
    ) -> Costume: ...

    @typing.overload
    def get_costume(self, hero: str | Heroes, costume_id: str) -> Costume | None: ...

    def get_costume(
        self, hero: str | Heroes, costume_id: str, *, error: bool = False
    ) -> Costume | None:
        """
        Get a specific costume for a hero.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve the costume for.
        costume_id : str
            The ID of the costume to retrieve.

        Returns
        -------
        Costume | None
            The costume if found, None if not found.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> client = MarvelRivalsClient("your-api-key")
        >>> costume = client.get_costume("squirrel girl", "Cheerful Dragoness")
        ... if costume:
        ...     print(costume.name)
        """
        response = self.client.get(
            Endpoints.GET_COSTUME(
                hero.value if isinstance(hero, Heroes) else hero, costume_id
            )
        )
        if response.status_code == 200:
            return CostumePremiumWrapper.from_dict(response.json())
        return None if not error else self.throw(response)

get_all_heroes(*, error=False) 

get_all_heroes(*, error: bool) -> list[Hero]

get_all_heroes() -> list[Hero] | None

Get all available heroes.

Parameters:

Name Type Description Default
error bool | None

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
list[Hero] | None

A list of all heroes if successful, None if the request fails and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> heroes = client.get_all_heroes()
>>> if heroes:
...     for hero in heroes:
...         print(hero.name)
Source code in marvelrivalsapi\client.py 
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
def get_all_heroes(self, *, error: bool = False) -> list[Hero] | None:
    """
    Get all available heroes.

    Parameters
    ----------
    error : bool | None
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    list[Hero] | None
        A list of all heroes if successful, None if the request fails and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> heroes = client.get_all_heroes()
    >>> if heroes:
    ...     for hero in heroes:
    ...         print(hero.name)
    """
    response = self.client.get(Endpoints.ALL_HEROES())
    if response.status_code == 200:
        return [Hero.from_dict(hero) for hero in response.json()]
    return None if not error else self.throw(response)

get_costume(hero, costume_id, *, error=False) 

get_costume(
    hero: str | Heroes, costume_id: str, *, error: bool
) -> Costume

get_costume(
    hero: str | Heroes, costume_id: str
) -> Costume | None

Get a specific costume for a hero.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve the costume for.

 required
costume_id str

The ID of the costume to retrieve.

 required

Returns:

Type Description
Costume | None

The costume if found, None if not found.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> costume = client.get_costume("squirrel girl", "Cheerful Dragoness")
... if costume:
...     print(costume.name)
Source code in marvelrivalsapi\client.py 
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
def get_costume(
    self, hero: str | Heroes, costume_id: str, *, error: bool = False
) -> Costume | None:
    """
    Get a specific costume for a hero.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve the costume for.
    costume_id : str
        The ID of the costume to retrieve.

    Returns
    -------
    Costume | None
        The costume if found, None if not found.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> costume = client.get_costume("squirrel girl", "Cheerful Dragoness")
    ... if costume:
    ...     print(costume.name)
    """
    response = self.client.get(
        Endpoints.GET_COSTUME(
            hero.value if isinstance(hero, Heroes) else hero, costume_id
        )
    )
    if response.status_code == 200:
        return CostumePremiumWrapper.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero(hero, *, error=False) 

get_hero(hero: str | Heroes, *, error: bool) -> Hero

get_hero(hero: str | Heroes) -> Hero | None

Get a hero by name or ID.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve.

 required
error bool | None

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
Hero | None

The hero if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> hero = client.get_hero("Spider-Man")
>>> if hero:
...     print(hero.name)
Source code in marvelrivalsapi\client.py 
 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
def get_hero(self, hero: str | Heroes, *, error: bool = False) -> Hero | None:
    """
    Get a hero by name or ID.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve.
    error : bool | None
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    Hero | None
        The hero if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> hero = client.get_hero("Spider-Man")
    >>> if hero:
    ...     print(hero.name)
    """
    response = self.client.get(
        Endpoints.GET_HERO(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        return Hero.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero_costumes(hero, *, error=False) 

get_hero_costumes(
    hero: str | Heroes, *, error: bool
) -> list[Costume]

get_hero_costumes(
    hero: str | Heroes,
) -> list[Costume] | None

Get all costumes for a specific hero.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve costumes for.

 required
error bool | None

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
list[Costume] | None

A list of all costumes for the specified hero if successful, None if the request fails and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> costumes = client.get_hero_costumes("spider-man")
>>> if costumes:
...     for costume in costumes:
...         print(costume.name)
Source code in marvelrivalsapi\client.py 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
def get_hero_costumes(
    self, hero: str | Heroes, *, error: bool = False
) -> list[Costume] | None:
    """
    Get all costumes for a specific hero.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve costumes for.
    error : bool | None
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    list[Costume] | None
        A list of all costumes for the specified hero if successful,
        None if the request fails and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> costumes = client.get_hero_costumes("spider-man")
    >>> if costumes:
    ...     for costume in costumes:
    ...         print(costume.name)
    """
    response = self.client.get(
        Endpoints.ALL_COSTUMES(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        return [Costume.from_dict(costume) for costume in response.json()]
    return None if not error else self.throw(response)

get_hero_leaderboard(hero, platform='pc', *, error=False) 

get_hero_leaderboard(
    hero: str | Heroes, platform: str, *, error: bool
) -> HeroLeaderboard

get_hero_leaderboard(
    hero: str | Heroes, platform: str
) -> HeroLeaderboard | None

get_hero_leaderboard(
    hero: str | Heroes, *, error: bool
) -> HeroLeaderboard

get_hero_leaderboard(
    hero: str | Heroes,
) -> HeroLeaderboard | None

Get hero leaderboard by name or ID.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve stats for.

 required
error bool | None

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
dict[HeroLeaderboard] | None

The hero stats if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> stats = client.get_hero_leaderboard("spider-man")
>>> if stats:
...     print(stats)
Source code in marvelrivalsapi\client.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
def get_hero_leaderboard(
    self, hero: str | Heroes, platform: str = "pc", *, error: bool = False
) -> HeroLeaderboard | None:
    """
    Get hero leaderboard by name or ID.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve stats for.
    error : bool | None
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    dict[HeroLeaderboard] | None
        The hero stats if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> stats = client.get_hero_leaderboard("spider-man")
    >>> if stats:
    ...     print(stats)
    """
    response = self.client.get(
        Endpoints.HERO_LEADERBOARD(
            hero.value if isinstance(hero, Heroes) else hero, platform
        )
    )
    if response.status_code == 200:
        return HeroLeaderboard.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero_stat(hero, *, error=False) 

get_hero_stat(
    hero: str | Heroes, *, error: bool
) -> HeroStat

get_hero_stat(hero: str | Heroes) -> HeroStat | None

Get hero stats by name or ID.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve stats for.

 required
error bool | None

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
dict[str, Any] | None

The hero stats if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> client = MarvelRivalsClient("your-api-key")
>>> stats = client.get_hero_stat("spider-man")
>>> if stats:
...     print(stats)
Source code in marvelrivalsapi\client.py 
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
def get_hero_stat(
    self, hero: str | Heroes, *, error: bool = False
) -> HeroStat | None:
    """
    Get hero stats by name or ID.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve stats for.
    error : bool | None
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    dict[str, typing.Any] | None
        The hero stats if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> client = MarvelRivalsClient("your-api-key")
    >>> stats = client.get_hero_stat("spider-man")
    >>> if stats:
    ...     print(stats)
    """
    response = self.client.get(
        Endpoints.HERO_STATS(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        print(response.json())
        return HeroStat.from_dict(response.json())
    return None if not error else self.throw(response)

Asynchronous client for interacting with the Marvel Rivals API.

This client allows for fetching hero data from the Marvel Rivals API using asynchronous HTTP requests.

Parameters:

Name Type Description Default
api_key str

The API key to authenticate requests to the Marvel Rivals API.

 required

Attributes:

Name Type Description
client AsyncClient

The HTTP client used for making asynchronous requests.

Examples:

>>> import asyncio
>>> from marvelrivalsapi import AsyncMarvelRivalsClient
>>>
>>> async def main():
...     client = AsyncMarvelRivalsClient("your-api-key")
...     hero = await client.get_hero("spider-man")
...     print(hero.name)
...     await client.close()
>>>
>>> asyncio.run(main())
Source code in marvelrivalsapi\async_client.py 
 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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
@define
class AsyncMarvelRivalsClient:
    """
    Asynchronous client for interacting with the Marvel Rivals API.

    This client allows for fetching hero data from the Marvel Rivals API
    using asynchronous HTTP requests.

    Parameters
    ----------
    api_key : str
        The API key to authenticate requests to the Marvel Rivals API.

    Attributes
    ----------
    client : httpx.AsyncClient
        The HTTP client used for making asynchronous requests.

    Examples
    --------
    >>> import asyncio
    >>> from marvelrivalsapi import AsyncMarvelRivalsClient
    >>>
    >>> async def main():
    ...     client = AsyncMarvelRivalsClient("your-api-key")
    ...     hero = await client.get_hero("spider-man")
    ...     print(hero.name)
    ...     await client.close()
    >>>
    >>> asyncio.run(main())
    """

    api_key: str
    client: httpx.AsyncClient = field(init=False)

    def __attrs_post_init__(self) -> None:
        self.client = httpx.AsyncClient(headers={"x-api-key": self.api_key})

    def throw(self, res: httpx.Response) -> None:
        raise MarvelRivalsAPIError(res)

    @typing.overload
    async def get_hero(self, hero: str | Heroes, *, error: bool) -> Hero: ...

    @typing.overload
    async def get_hero(self, hero: str | Heroes) -> Hero | None: ...

    async def get_hero(self, hero: str | Heroes, *, error: bool = False) -> Hero | None:
        """
        Get a hero by name or ID asynchronously.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve.
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        Hero | None
            The hero if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     hero = await client.get_hero("spider-man")
        ...     if hero:
        ...         print(hero.name)
        """
        response = await self.client.get(
            Endpoints.GET_HERO(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            return Hero.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    async def get_all_heroes(self, *, error: bool) -> list[Hero]: ...

    @typing.overload
    async def get_all_heroes(self) -> list[Hero] | None: ...

    async def get_all_heroes(self, *, error: bool = False) -> list[Hero] | None:
        """
        Get all available heroes asynchronously.

        Parameters
        ----------
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        list[Hero] | None
            A list of all heroes if successful, None if the request fails and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     heroes = await client.get_all_heroes()
        ...     if heroes:
        ...         for hero in heroes:
        ...             print(hero.name)
        """
        response = await self.client.get(Endpoints.ALL_HEROES())
        if response.status_code == 200:
            return [Hero.from_dict(hero) for hero in response.json()]
        return None if not error else self.throw(response)

    @typing.overload
    async def get_hero_stats(self, hero: str | Heroes, *, error: bool) -> HeroStat: ...

    @typing.overload
    async def get_hero_stats(self, hero: str | Heroes) -> HeroStat | None: ...

    async def get_hero_stats(
        self, hero: str | Heroes, *, error: bool = False
    ) -> HeroStat | None:
        """
        Get statistics for a specific hero asynchronously.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve stats for.
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        HeroStat | None
            The hero statistics if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     stats = await client.get_hero_stats("Spider-Man")
        ...     if stats:
        ...         print(f"Win rate: {stats.win_rate:.2%}")
        """
        response = await self.client.get(
            Endpoints.HERO_STATS(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            return HeroStat.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    async def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str, *, error: bool
    ) -> HeroLeaderboard: ...

    @typing.overload
    async def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str
    ) -> HeroLeaderboard | None: ...

    @typing.overload
    async def get_hero_leaderboard(
        self, hero: str | Heroes, *, error: bool
    ) -> HeroLeaderboard: ...

    @typing.overload
    async def get_hero_leaderboard(
        self, hero: str | Heroes
    ) -> HeroLeaderboard | None: ...

    async def get_hero_leaderboard(
        self, hero: str | Heroes, platform: str = "pc", *, error: bool = False
    ) -> HeroLeaderboard | None:
        """
        Get the leaderboard for a specific hero and platform asynchronously.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve the leaderboard for.
        platform : str
            The platform to filter the leaderboard by.
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        HeroLeaderboard | None
            The leaderboard data if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     leaderboard = await client.get_hero_leaderboard("spider-man")
        ...     if leaderboard:
        ...         for entry in leaderboard.entries:
        ...             print(f"{entry.name}: {entry.score}")
        """
        response = await self.client.get(
            Endpoints.HERO_LEADERBOARD(
                hero.value if isinstance(hero, Heroes) else hero, platform
            )
        )
        if response.status_code == 200:
            return HeroLeaderboard.from_dict(response.json())
        return None if not error else self.throw(response)

    @typing.overload
    async def get_hero_costumes(
        self, hero: str | Heroes, *, error: bool
    ) -> list[Costume]: ...

    @typing.overload
    async def get_hero_costumes(self, hero: str | Heroes) -> list[Costume] | None: ...

    async def get_hero_costumes(
        self, hero: str | Heroes, *, error: bool = False
    ) -> list[Costume] | None:
        """
        Get all costumes for a specific hero asynchronously.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve costumes for.
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        list[Costume] | None
            A list of costumes if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     costumes = await client.get_hero_costumes("spider-man")
        ...     if costumes:
        ...         for costume in costumes:
        ...             print(costume.name)
        """
        response = await self.client.get(
            Endpoints.ALL_COSTUMES(hero.value if isinstance(hero, Heroes) else hero)
        )
        if response.status_code == 200:
            return [Costume.from_dict(costume) for costume in response.json()]
        return None if not error else self.throw(response)

    @typing.overload
    async def get_costume(
        self, hero: str | Heroes, costume_id: str, *, error: bool
    ) -> Costume: ...

    @typing.overload
    async def get_costume(
        self, hero: str | Heroes, costume_id: str
    ) -> Costume | None: ...

    async def get_costume(
        self, hero: str | Heroes, costume_id: str, *, error: bool = False
    ) -> Costume | None:
        """
        Get a specific costume for a hero asynchronously.

        Parameters
        ----------
        hero : str | Heroes
            The hero name or ID to retrieve the costume for.
        costume_id : str
            The ID of the costume to retrieve.
        error : bool
            If True, raises an error on failure instead of returning None.
            Default is False.

        Returns
        -------
        Costume | None
            The costume if found, None if not found and error is False.

        Raises
        ------
        MarvelRivalsAPIError
            When the API request fails and error is True.

        Examples
        --------
        >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
        ...     costume = await client.get_costume("squirrel girl", "Cheerful Dragoness")
        ...     if costume:
        ...         print(costume.name)
        """
        response = await self.client.get(
            Endpoints.GET_COSTUME(
                hero.value if isinstance(hero, Heroes) else hero, costume_id
            )
        )
        if response.status_code == 200:
            return CostumePremiumWrapper.from_dict(response.json())
        return None if not error else self.throw(response)

    async def close(self) -> None:
        """
        Close the HTTP client session.

        This method should be called when the client is no longer needed to
        properly clean up resources.

        Examples
        --------
        >>> async def main():
        ...     client = AsyncMarvelRivalsClient("your-api-key")
        ...     # Use the client...
        ...     await client.close()
        """
        await self.client.aclose()

    async def __aenter__(self) -> AsyncMarvelRivalsClient:
        return self

    async def __aexit__(self, *args: typing.Any) -> None:
        await self.close()

close() async

Close the HTTP client session.

This method should be called when the client is no longer needed to properly clean up resources.

Examples:

>>> async def main():
...     client = AsyncMarvelRivalsClient("your-api-key")
...     # Use the client...
...     await client.close()
Source code in marvelrivalsapi\async_client.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
async def close(self) -> None:
    """
    Close the HTTP client session.

    This method should be called when the client is no longer needed to
    properly clean up resources.

    Examples
    --------
    >>> async def main():
    ...     client = AsyncMarvelRivalsClient("your-api-key")
    ...     # Use the client...
    ...     await client.close()
    """
    await self.client.aclose()

get_all_heroes(*, error=False) async 

get_all_heroes(*, error: bool) -> list[Hero]

get_all_heroes() -> list[Hero] | None

Get all available heroes asynchronously.

Parameters:

Name Type Description Default
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
list[Hero] | None

A list of all heroes if successful, None if the request fails and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     heroes = await client.get_all_heroes()
...     if heroes:
...         for hero in heroes:
...             print(hero.name)
Source code in marvelrivalsapi\async_client.py 
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
async def get_all_heroes(self, *, error: bool = False) -> list[Hero] | None:
    """
    Get all available heroes asynchronously.

    Parameters
    ----------
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    list[Hero] | None
        A list of all heroes if successful, None if the request fails and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     heroes = await client.get_all_heroes()
    ...     if heroes:
    ...         for hero in heroes:
    ...             print(hero.name)
    """
    response = await self.client.get(Endpoints.ALL_HEROES())
    if response.status_code == 200:
        return [Hero.from_dict(hero) for hero in response.json()]
    return None if not error else self.throw(response)

get_costume(hero, costume_id, *, error=False) async 

get_costume(
    hero: str | Heroes, costume_id: str, *, error: bool
) -> Costume

get_costume(
    hero: str | Heroes, costume_id: str
) -> Costume | None

Get a specific costume for a hero asynchronously.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve the costume for.

 required
costume_id str

The ID of the costume to retrieve.

 required
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
Costume | None

The costume if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     costume = await client.get_costume("squirrel girl", "Cheerful Dragoness")
...     if costume:
...         print(costume.name)
Source code in marvelrivalsapi\async_client.py 
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
async def get_costume(
    self, hero: str | Heroes, costume_id: str, *, error: bool = False
) -> Costume | None:
    """
    Get a specific costume for a hero asynchronously.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve the costume for.
    costume_id : str
        The ID of the costume to retrieve.
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    Costume | None
        The costume if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     costume = await client.get_costume("squirrel girl", "Cheerful Dragoness")
    ...     if costume:
    ...         print(costume.name)
    """
    response = await self.client.get(
        Endpoints.GET_COSTUME(
            hero.value if isinstance(hero, Heroes) else hero, costume_id
        )
    )
    if response.status_code == 200:
        return CostumePremiumWrapper.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero(hero, *, error=False) async 

get_hero(hero: str | Heroes, *, error: bool) -> Hero

get_hero(hero: str | Heroes) -> Hero | None

Get a hero by name or ID asynchronously.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve.

 required
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
Hero | None

The hero if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     hero = await client.get_hero("spider-man")
...     if hero:
...         print(hero.name)
Source code in marvelrivalsapi\async_client.py 
 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
async def get_hero(self, hero: str | Heroes, *, error: bool = False) -> Hero | None:
    """
    Get a hero by name or ID asynchronously.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve.
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    Hero | None
        The hero if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     hero = await client.get_hero("spider-man")
    ...     if hero:
    ...         print(hero.name)
    """
    response = await self.client.get(
        Endpoints.GET_HERO(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        return Hero.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero_costumes(hero, *, error=False) async 

get_hero_costumes(
    hero: str | Heroes, *, error: bool
) -> list[Costume]

get_hero_costumes(
    hero: str | Heroes,
) -> list[Costume] | None

Get all costumes for a specific hero asynchronously.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve costumes for.

 required
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
list[Costume] | None

A list of costumes if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     costumes = await client.get_hero_costumes("spider-man")
...     if costumes:
...         for costume in costumes:
...             print(costume.name)
Source code in marvelrivalsapi\async_client.py 
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
async def get_hero_costumes(
    self, hero: str | Heroes, *, error: bool = False
) -> list[Costume] | None:
    """
    Get all costumes for a specific hero asynchronously.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve costumes for.
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    list[Costume] | None
        A list of costumes if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     costumes = await client.get_hero_costumes("spider-man")
    ...     if costumes:
    ...         for costume in costumes:
    ...             print(costume.name)
    """
    response = await self.client.get(
        Endpoints.ALL_COSTUMES(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        return [Costume.from_dict(costume) for costume in response.json()]
    return None if not error else self.throw(response)

get_hero_leaderboard(hero, platform='pc', *, error=False) async 

get_hero_leaderboard(
    hero: str | Heroes, platform: str, *, error: bool
) -> HeroLeaderboard

get_hero_leaderboard(
    hero: str | Heroes, platform: str
) -> HeroLeaderboard | None

get_hero_leaderboard(
    hero: str | Heroes, *, error: bool
) -> HeroLeaderboard

get_hero_leaderboard(
    hero: str | Heroes,
) -> HeroLeaderboard | None

Get the leaderboard for a specific hero and platform asynchronously.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve the leaderboard for.

 required
platform str

The platform to filter the leaderboard by.

 'pc'
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
HeroLeaderboard | None

The leaderboard data if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     leaderboard = await client.get_hero_leaderboard("spider-man")
...     if leaderboard:
...         for entry in leaderboard.entries:
...             print(f"{entry.name}: {entry.score}")
Source code in marvelrivalsapi\async_client.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
async def get_hero_leaderboard(
    self, hero: str | Heroes, platform: str = "pc", *, error: bool = False
) -> HeroLeaderboard | None:
    """
    Get the leaderboard for a specific hero and platform asynchronously.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve the leaderboard for.
    platform : str
        The platform to filter the leaderboard by.
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    HeroLeaderboard | None
        The leaderboard data if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     leaderboard = await client.get_hero_leaderboard("spider-man")
    ...     if leaderboard:
    ...         for entry in leaderboard.entries:
    ...             print(f"{entry.name}: {entry.score}")
    """
    response = await self.client.get(
        Endpoints.HERO_LEADERBOARD(
            hero.value if isinstance(hero, Heroes) else hero, platform
        )
    )
    if response.status_code == 200:
        return HeroLeaderboard.from_dict(response.json())
    return None if not error else self.throw(response)

get_hero_stats(hero, *, error=False) async 

get_hero_stats(
    hero: str | Heroes, *, error: bool
) -> HeroStat

get_hero_stats(hero: str | Heroes) -> HeroStat | None

Get statistics for a specific hero asynchronously.

Parameters:

Name Type Description Default
hero str | Heroes

The hero name or ID to retrieve stats for.

 required
error bool

If True, raises an error on failure instead of returning None. Default is False.

 False

Returns:

Type Description
HeroStat | None

The hero statistics if found, None if not found and error is False.

Raises:

Type Description
MarvelRivalsAPIError

When the API request fails and error is True.

Examples:

>>> async with AsyncMarvelRivalsClient("your-api-key") as client:
...     stats = await client.get_hero_stats("Spider-Man")
...     if stats:
...         print(f"Win rate: {stats.win_rate:.2%}")
Source code in marvelrivalsapi\async_client.py 
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
async def get_hero_stats(
    self, hero: str | Heroes, *, error: bool = False
) -> HeroStat | None:
    """
    Get statistics for a specific hero asynchronously.

    Parameters
    ----------
    hero : str | Heroes
        The hero name or ID to retrieve stats for.
    error : bool
        If True, raises an error on failure instead of returning None.
        Default is False.

    Returns
    -------
    HeroStat | None
        The hero statistics if found, None if not found and error is False.

    Raises
    ------
    MarvelRivalsAPIError
        When the API request fails and error is True.

    Examples
    --------
    >>> async with AsyncMarvelRivalsClient("your-api-key") as client:
    ...     stats = await client.get_hero_stats("Spider-Man")
    ...     if stats:
    ...         print(f"Win rate: {stats.win_rate:.2%}")
    """
    response = await self.client.get(
        Endpoints.HERO_STATS(hero.value if isinstance(hero, Heroes) else hero)
    )
    if response.status_code == 200:
        return HeroStat.from_dict(response.json())
    return None if not error else self.throw(response)