PaladinsAPI¶
-
class
arez.
PaladinsAPI
(dev_id, auth_key, *, cache=True, initialize=False, loop=None)[source]¶ The main Paladins API.
Inherits from
DataCache
.Note
You can request your developer ID and authorization key here.
Note
In addition to the exceptions specified for each method, each API request can result in the following exceptions being raised:
Unavailable
The API is currently unavailable.
LimitReached
Your daily limit of requests has been reached.
HTTPException
Fetching the information requested failed due to connection or API problems.
- Parameters
auth_key (str) – Your developer’s authentication key (authKey).
cache (bool) –
When set to
False
, this disables the data cache. This makes most objects returned from the API beCacheObject
instead of their respective data-rich counterparts.Defaults to
True
.initialize (Union[bool, Language]) –
When set to
True
, it launches a task that will initialize the cache with the default (English) language.Can be set to a
Language
instance, in which case that language will be set as default first, before initializing.Defaults to
False
, where no initialization occurs.loop (Optional[asyncio.AbstractEventLoop]) –
The event loop you want to use for this API.
Default loop is used when not provided.
-
await
close
()[source]¶ Closes the underlying API connection, and stops the server status checking loop (see
register_status_callback
).Attempting to make a request after the connection is closed will result in a
RuntimeError
.
-
await
get_data_used
()[source]¶ Allows you to check API usage statistics.
- Returns
An object describing API usage.
- Return type
-
await
get_server_status
(*, force_refresh=False)[source]¶ Fetches the server status.
To preserve requests, the status returned is cached once every minute. Use the
force_refresh
parameter to override this behavior.Uses up one request each time the cache is refreshed.
-
register_status_callback
(callback, check_interval=datetime.timedelta(seconds=180), recheck_interval=datetime.timedelta(seconds=60))[source]¶ Registers a callback function, that will periodically check the status of the servers, every
check_interval
specified. If the status changes, the callback function will then be called with the new status (and optionally the previous one) passed as the arguments, like so:callback(after)
orcallback(before, after)
.This can be used to easily setup server status monitoring and notifications systems:
api: arez.PaladinsAPI # wrapper instance async def notify(after: arez.ServerStatus): # do anything when the status changes - in this case, just print a message print(f"Current server status: {after.status}") api.register_status_callback(notify)
Note
The checking loop will call
get_server_status
withforce_refresh
set toTrue
, to handle the refreshing. To avoid wasting request, it’s recommended to use intervals at least 1 minute long, and not setforce_refresh
toTrue
anywhere else in your code, relying on the cached status being refreshed by the loop.The callback is wrapped inside a task, to prevent it from delaying the checking loop. Please make sure that it’s execution time is shorter than the check / recheck intervals, otherwise you may end up with two callbacks running at once.
Any exceptions raised by the callback function, will be logged by the library’s logger, and ultimately ignored otherwise. If you’d be interested in those, try either catching and processing those yourself (within the callback), or hooking up a logger handler and setting the logger to at least
ERROR
level.
- Parameters
callback (Union[None, Callable[[ServerStatus], Any], Callable[[ServerStatus, ServerStatus], Any]]) –
The callback function you want to register. This can be either a normal function or an async one, accepting either
1
or2
positional arguments, with any return type.Passing a new callback function, while one is already running, will overwrite the previous one and reset the timer.
Passing
None
removes the callback and stops the checking loop.check_interval (timedelta) –
The length of the interval used between Operational (all servers up, no limited access, not including PTS) server status checks.
The default check interval is 3 minutes.
recheck_interval (timedelta) –
The length of the interval used between non-Operational (at least one server is down, or limited access, not including PTS) server status checks.
The default recheck interval is 1 minute.
- Raises
TypeError – The callback passed was not a function.
ValueError – The callback passed had an incorrect number (or types) of its parameters.
-
await
get_champion_info
(language=None, *, force_refresh=False, cache=None)[source]¶ Fetches the champions, talents, cards, shop items and skins information.
To preserve requests, the information returned is cached once every 12 hours. Use the
force_refresh
parameter to override this behavior.Uses up three requests each time the cache is refreshed, per language.
- Parameters
language (Optional[Language]) –
The
Language
you want to fetch the information in.Default language is used if not provided.
force_refresh (bool) –
Bypasses the cache, forcing a fetch and returning a new object.
Defaults to
False
.cache (Optional[bool]) –
Lets you decide if the received information should be cached or not.
Setting this to
True
forces the object to be cached, even when the cache is disabled.Setting this to
False
will never cache the object.Default behavior (
None
) follows the cache existence setting.
- Returns
An object containing all champions, cards, talents, shop items and skins information, in the chosen language.
- Return type
- Raises
NotFound – The champion information wasn’t available on the server.
-
wrap_player
(player_id, player_name='', platform=0, private=False)[source]¶ Wraps player ID, Name and Platform into a
PartialPlayer
object.Warning
Note that since there is no input validation, there’s no guarantee an object created this way will return any meaningful results when it’s methods are used. This method is here purely for those who’d like to store player objects in something like a database, offering the possibility of re-wrapping the stored data back into a valid player object.
This should not be used to fetch stats for players based on their ID - use
get_player
for this purpose instead.- Parameters
player_id (int) – The player ID you want to get the object for.
player_name (str) –
The player Name you want the object to have.
Defaults to an empty string.
The platform you want the object to have.
Defaults to
Platform.Unknown
.private (bool) –
A boolean flag indicating if this profile should be considered private or not.
Defaults to
False
.
- Returns
The wrapped player object.
- Return type
-
await
get_player
(player, *, return_private=False)[source]¶ Fetches a Player object for the given player ID or player name.
Only players with
Platform.PC
,Platform.Steam
andPlatform.Discord
platforms (PC players) will be returned when using this method with player name as input. For player ID inputs, players from all platforms will be returned.Uses up a single request.
- Parameters
player (Union[int, str]) – Player ID or player name of the player you want to get object for.
return_private (bool) –
When set to
True
and the requested profile is determined private, this method will return aPartialPlayer
object with the player ID and privacy flag set.When set to
False
, thePrivate
exception will be raised instead.Defaults to
False
.
- Returns
An object containing stats information about the player requested.
PartialPlayer
objects are only returned for private profiles and appropriate arguments used.- Return type
Union[Player, PartialPlayer]
- Raises
-
await
get_players
(player_ids, *, return_private=False)[source]¶ Fetches multiple players in a batch, and returns their list. Removes duplicates.
Uses up a single request for every multiple of 20 unique player IDs passed.
- Parameters
player_ids (Iterable[int]) – An iterable of player IDs you want to fetch.
return_private (bool) –
When set to
True
and one of the requested profiles is determined private, this method will return aPartialPlayer
object with the player ID and privacy flag set.When set to
False
, private profiles are omitted from the output list.Defaults to
False
.
- Returns
A list of players requested.
PartialPlayer
objects are only returned for private profiles and appropriate arguments used. Some players might not be included in the output if they weren’t found, or their profile was private.- Return type
List[Union[Player, PartialPlayer]]
-
await
search_players
(player_name, platform=None, *, return_private=True, exact=True)[source]¶ Fetches all players whose name matches the name specified. The search is fuzzy - player name capitalisation doesn’t matter.
Uses up a single request.
Note
Searching on all platforms will limit the number of players returned to ~500. Specifying a particular platform does not have this limitation.
- Parameters
player_name (str) – Player name you want to search for.
platform (Optional[Platform]) –
Platform you want to limit the search to.
Specifying
None
will search on all platforms.Defaults to
None
.return_private (bool) –
When set to
True
and one of the requested profiles is determined private, this method will return aPartialPlayer
object with the player ID and privacy flag set.When set to
False
, private profiles are omitted from the output list.Defaults to
True
.exact (bool) –
When set to
True
, only players whose name matches exactly the name provided, will be returned.When set to
False
, exact matches will be returned first, followed by players whose name starts with the privided string.Defaults to
True
.Warning
Settings this to
False
will limit the number of players returned to ~500.
- Returns
A list of players whose name (and optionally platform) matches the specified name.
Note that some of them might be set as private, unless appropriate input parameters were used.
- Return type
List[PartialPlayer]
- Raises
NotFound – There was no player for the given name (and optional platform) found.
-
await
get_from_platform
(platform_id, platform)[source]¶ Fetches a PartialPlayer linked with the platform ID specified.
Note
This method doesn’t set the
PartialPlayer.name
attribute, meaning that it will remain as an empty string. This is a limitation of the Hi-Rez API, not the library.Uses up a single request.
- Parameters
- Returns
The player this platform ID is linked to.
- Return type
- Raises
NotFound – The linked profile doesn’t exist / couldn’t be found.
-
get_entry
(language=None)¶ Returns a cache entry for the given language specified.
Note
This method can return
None
or stale data if the entry hasn’t been fetched yet, or haven’t been updated in a while.Consider using the
get_champion_info
method from the main API instead.- Parameters
language (Optional[Language]) –
The
Language
you want to get the entry in.Default language is used if not provided.
- Returns
The cache entry you requested.
None
is returned if the entry for the language specified hasn’t been fetched yet.- Return type
Optional[CacheEntry]
-
await
get_match
(match_id, language=None, *, expand_players=False)[source]¶ Fetches a match for the given Match ID.
Uses up a single request.
- Parameters
match_id (int) – Match ID you want to get a match for.
language (Optional[Language]) –
The
Language
you want to fetch the information in.Default language is used if not provided.
expand_players (bool) –
When set to
True
, partial player objects in the returned match object will automatically be expanded into fullPlayer
objects, if possible.Uses an addtional request to do the expansion.
Defaults to
False
.
- Returns
A match for the ID specified.
- Return type
- Raises
NotFound – The match wasn’t available on the server. This can happen if the match is older than 30 days, or is currently in progress.
-
await
initialize
(*, language=None)¶ Initializes the data cache, by pre-fetching and storing the
CacheEntry
for the default language currently set.Note
This will both, force the champion information fetching, as well as cache the resulting object.
-
await
request
(method_name, /, *data)¶ Makes a direct request to the HiRez API.
For all methods available (and their parameters), please see Hi-Rez API docs.
- Parameters
- Returns
A raw server’s response as a string, list or a dictionary (depending on the endpoint).
- Return type
- Raises
HTTPException – Whenever it was impossible to fetch the data in a reliable manner. Check the
HTTPException.cause
attribute for the original exception (and reason) that lead to this.Unauthorized – When the developer’s ID (devId) or the developer’s authentication key (authKey) are deemed invalid.
Unavailable – When the Hi-Rez API switches to emergency mode, and no data could be returned at this time.
LimitReached – Your daily limit of requests has been reached.
-
set_default_language
(language)¶ Sets the default language used by the cache in places where one is not provided by the user.
The default language set is
Language.English
.- Parameters
language (Language) – The new default language you want to set.
-
await
get_matches
(match_ids, language=None, *, expand_players=False)[source]¶ Fetches multiple matches in a batch, for the given Match IDs. Removes duplicates.
Uses up a single request for every multiple of 10 unique match IDs passed.
- Parameters
match_ids (Iterable[int]) – An iterable of Match IDs you want to fetch.
language (Optional[Language]) –
The
Language
you want to fetch the information in.Default language is used if not provided.
expand_players (bool) –
When set to
True
, partial player objects in the returned match objects will automatically be expanded into fullPlayer
objects, if possible.Uses an addtional request for every 20 unique players to do the expansion.
Defaults to
False
.
- Returns
A list of the available matches requested.
Some of the matches can be not present if they weren’t available on the server.
- Return type
List[Match]
-
async for ... in
get_matches_for_queue
(queue, *, start, end, language=None, reverse=False, local_time=False, expand_players=False)[source]¶ Creates an async generator that lets you iterate over all matches played in a particular queue, between the timestamps provided.
Uses up a single request for every:
multiple of 10 matches fetched, according to the following points
1 day worth of matches fetched, between midnights
1 hour worth of matches fetched, between round hours
10 minutes worth of matches fetched, between round 10 minutes intervals
Depending on the timestamps provided, the longest possible fetching interval is used.
Note
To avoid wasting requests, it’s recommended to invoke this generator with timestamps representing at least 10 minutes long interval, rounded to the nearest multiple of 10 minutes. Being more granular will still work, and only return matches that fit within the interval specified though.
Note
Both naive and aware objects are supported for the timestamps. Aware objects will be internally converted to UTC according to their timezone. Naive objects are assumed to represent UTC time already, unless the
local_time
argument is used.- Parameters
queue (Queue) – The
Queue
you want to fetch the matches for.language (Optional[Language]) –
The
Language
you want to fetch the information in.Default language is used if not provided.
start (datetime.datetime) – A timestamp indicating the starting point of a time slice you want to fetch the matches in.
end (datetime.datetime) – A timestamp indicating the ending point of a time slice you want to fetch the matches in.
reverse (bool) –
Reverses the order of the matches being returned.
Defaults to
False
.local_time (bool) –
When set to
True
, the timestamps provided are assumed to represent the local system time (in your local timezone), and will be converted to UTC before processing.When set to
False
, the timestamps provided are assumed to already represent UTC and no conversion will occur.Defaults to
False
.expand_players (bool) –
When set to
True
, partial player objects in the returned match object will automatically be expanded into fullPlayer
objects, if possible.Uses an addtional request for every 20 unique players to do the expansion.
Defaults to
False
.
- Returns
An async generator yielding matches played in the queue specified, between the timestamps specified.
- Return type
-
await
get_bounty
(*, language=None)[source]¶ Returns a 2-item tuple denoting the (active, past) bounty store items, sorted by their expiration time.
- Parameters
language (Optional[Language]) –
The
Language
you want to fetch the information in.Default language is used if not provided.
- Returns
An tuple containing a list of active bounty store items, followed by a list of items that have already expired.
- Return type
Tuple[List[BountyItem], List[BountyItem]]
- Raises
NotFound – No bounty items were returned. This can happen if the bounty store is unavailable for a long time.