RiotWatcher Documentation

Transcription

1 RiotWatcher Documentation Release pseudonym117 Jan 29, 2019

2

3 Contents 1 To Start Using it Main API and other topics 7 4 Indices and tables 15 Python Module Index 17 i

4 ii

5 RiotWatcher is a thin wrapper on top of the Riot Games API for League of Legends. All public methods as of 1/7/2019 are supported in full. RiotWatcher by default supports a naive rate limiter. This rate limiter will try to stop you from making too many requests, and in a single threaded test environment does this rather well. In a multithreaded environment, you may still get some 429 errors. 429 errors are currently NOT retried for you. Contents 1

6 2 Contents

7 CHAPTER 1 To Start... To install RiotWatcher: pip install riotwatcher OR: python setup.py install You also need to have an API key from Riot. Get that from here. 3

8 4 Chapter 1. To Start...

9 CHAPTER 2 Using it... All methods return dictionaries representing the json objects described by the official Riot API. Any HTTP errors that are returned by the API are raised as HTTPError exceptions from the Requests library. from riotwatcher import RiotWatcher, ApiError watcher = RiotWatcher('<your-api-key>') my_region = 'na1' me = watcher.summoner.by_name(my_region, 'pseudonym117') print(me) # all objects are returned (by default) as a dict # lets see if i got diamond yet (i probably didnt) my_ranked_stats = watcher.league.positions_by_summoner(my_region, me['id']) print(my_ranked_stats) # Lets some champions static_champ_list = watcher.static_data.champions(my_region) print(static_champ_list) # For Riot's API, the 404 status code indicates that the requested data wasn't found and # should be expected to occur in normal operation, as in the case of a an # invalid summoner name, match ID, etc. # # The 429 status code indicates that the user has sent too many requests # in a given amount of time ("rate limiting"). try: response = watcher.summoner.by_name(my_region, 'this_is_probably_not_anyones_ summoner_name') except ApiError as err: if err.response.status_code == 429: (continues on next page) 5

10 (continued from previous page) print('we should retry in {} seconds.'.format(err.headers['retry-after'])) print('this retry-after is handled by default by the RiotWatcher library') print('future requests wait until the retry-after time passes') elif err.response.status_code == 404: print('summoner with that ridiculous name not found.') else: raise 6 Chapter 2. Using it...

11 CHAPTER 3 Main API and other topics 3.1 riotwatcher package class riotwatcher.riotwatcher(api_key, custom_handler_chain=none, **kwargs) RiotWatcher class is intended to be the main interaction point with the RiotAPI. champion Interface to the Champion Endpoint Return type ChampionApiV3 champion_mastery Interface to the ChampionMastery Endpoint Return type ChampionMasteryApiV4 data_dragon Interface to the DataDragon Endpoint Return type DataDragonApi league Interface to the League Endpoint Return type LeagueApiV4 lol_status Interface to the LoLStatus Endpoint Return type LolStatusApiV3 match Interface to the Match Endpoint Return type MatchApiV4 spectator Interface to the Spectator Endpoint 7

12 Return type SpectatorApiV4 summoner Interface to the Summoner Endpoint Return type SummonerApiV4 third_party_code Interface to the Third Party Code Endpoint Return type ThirdPartyCodeApiV Subpackages riotwatcher.handlers package riotwatcher.handlers.ratelimit package ApplicationRateLimiter class riotwatcher.handlers.ratelimit.applicationratelimiter Bases: riotwatcher.handlers.ratelimit.headerbasedlimiter.headerbasedlimiter HeaderBasedLimiter class riotwatcher.handlers.ratelimit.headerbasedlimiter(limit_header, count_header, friendly_name=none) friendly_name update_limiter(region, endpoint_name, method_name, response) wait_until(region, endpoint_name, method_name) Limits class riotwatcher.handlers.ratelimit.limitcollection update_limits(raw_limits) wait_until() class riotwatcher.handlers.ratelimit.limit count duration limit set_raw_limit(raw_limit) start_time wait_until() 8 Chapter 3. Main API and other topics

13 MethodRateLimiter class riotwatcher.handlers.ratelimit.methodratelimiter Bases: riotwatcher.handlers.ratelimit.headerbasedlimiter.headerbasedlimiter OopsRateLimiter class riotwatcher.handlers.ratelimit.oopsratelimiter friendly_name update_limiter(region, endpoint_name, method_name, response) wait_until(region, endpoint_name, method_name) RateLimitHandler class riotwatcher.handlers.ratelimit.ratelimithandler after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library preview_request(region, endpoint_name, method_name, url, query_params) called before a request is processed. region (string) the region of this request endpoint_name (string) the name of the endpoint being requested method_name (string) the name of the method being requested url the URL that is being requested. query_params dict: the parameters to the url that is being queried, e.g.?key1=val&key2=val2 Submodules riotwatcher.handlers.jsonifyhandler module class riotwatcher.handlers.jsonifyhandler.jsonifyhandler Bases: riotwatcher.handlers.requesthandler.requesthandler 3.1. riotwatcher package 9

14 after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library after_static_request(url, response) Called after a response is received and before it is returned to the user. url The url that was requested response the response received. This is a response from the Requests library riotwatcher.handlers.requesthandler module class riotwatcher.handlers.requesthandler.requesthandler Bases: object after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library after_static_request(url, response) Called after a response is received and before it is returned to the user. url The url that was requested response the response received. This is a response from the Requests library preview_request(region, endpoint_name, method_name, url, query_params) called before a request is processed. region (string) the region of this request endpoint_name (string) the name of the endpoint being requested method_name (string) the name of the method being requested url the URL that is being requested. 10 Chapter 3. Main API and other topics

15 query_params dict: the parameters to the url that is being queried, e.g.?key1=val&key2=val2 preview_static_request(url, query_params) Called before a request to DataDragon is processed url The url that was requested riotwatcher.handlers.throwonerrorhandler module class riotwatcher.handlers.throwonerrorhandler.throwonerrorhandler Bases: riotwatcher.handlers.requesthandler.requesthandler after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library Module contents class riotwatcher.handlers.requesthandler Bases: object after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library after_static_request(url, response) Called after a response is received and before it is returned to the user. url The url that was requested response the response received. This is a response from the Requests library preview_request(region, endpoint_name, method_name, url, query_params) called before a request is processed. region (string) the region of this request 3.1. riotwatcher package 11

16 endpoint_name (string) the name of the endpoint being requested method_name (string) the name of the method being requested url the URL that is being requested. query_params dict: the parameters to the url that is being queried, e.g.?key1=val&key2=val2 preview_static_request(url, query_params) Called before a request to DataDragon is processed url The url that was requested class riotwatcher.handlers.jsonifyhandler Bases: riotwatcher.handlers.requesthandler.requesthandler after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library after_static_request(url, response) Called after a response is received and before it is returned to the user. url The url that was requested response the response received. This is a response from the Requests library class riotwatcher.handlers.throwonerrorhandler Bases: riotwatcher.handlers.requesthandler.requesthandler after_request(region, endpoint_name, method_name, url, response) Called after a response is received and before it is returned to the user. region (string) the region of this request endpoint_name (string) the name of the endpoint that was requested method_name (string) the name of the method that was requested url The url that was requested response the response received. This is a response from the Requests library class riotwatcher.handlers.typecorrectorhandler Bases: riotwatcher.handlers.requesthandler.requesthandler The TypeCorrector class is meant to correct any inconsistencies in the types of objects provided as query parameters. Currently this only involves changing boolean values into strings, as the API only accepts lower case booleans for some reason. 12 Chapter 3. Main API and other topics

17 preview_request(region, endpoint_name, method_name, url, query_params) called before a request is processed. endpoint_name (string) the name of the endpoint being requested method_name (string) the name of the method being requested url the URL that is being requested. query_params dict: the parameters to the url that is being queried, e.g.?key1=val&key2=val2 class riotwatcher.handlers.waitingratelimithandler Bases: riotwatcher.handlers.ratelimit.ratelimithandler.ratelimithandler 3.2 Handler Chain Concept All rate limiting, caching, and data transformation is handled by objects extending the Handlers.RequestHandler class. These are completely user configurable. TODO: add more info about this 3.3 Testing There currently are 2 sets of tests. There are basic unit tests for API related functionality, and there is a full system test, which directly accesses the API. Unit tests can be run with the following command from the RiotWatcher folder: tox Full access API tests should be run by first creating a file named api_key, which should contain a valid API key (no newline), to the folder Riot-Watcher. Then the following command will run the full system test (WARNING: it takes quite some time to run; definitely hits the dev key rate limit): python -m unittest discover -p full_test*.py 3.2. Handler Chain Concept 13

18 14 Chapter 3. Main API and other topics

19 CHAPTER 4 Indices and tables genindex modindex search 15

20 16 Chapter 4. Indices and tables

21 Python Module Index r riotwatcher.handlers, 11 riotwatcher.handlers.jsonifyhandler, 9 riotwatcher.handlers.requesthandler, 10 riotwatcher.handlers.throwonerrorhandler, 11 17

22 18 Python Module Index

23 Index A after_request() (riotwatcher.handlers.jsonifyhandler method), 12 attribute), 8 after_request() (riotwatcher.handlers.jsonifyhandler.jsonifyhandler friendly_name (riotwatcher.handlers.ratelimit.oopsratelimiter method), 9 attribute), 9 after_request() (riotwatcher.handlers.ratelimit.ratelimithandler method), 9 H after_request() (riotwatcher.handlers.requesthandler HeaderBasedLimiter (class in riotwatcher.handlers.ratelimit), 8 method), 11 after_request() (riotwatcher.handlers.requesthandler.requesthandler method), 10 J after_request() (riotwatcher.handlers.throwonerrorhandlerjsonifyhandler (class in riotwatcher.handlers), 12 method), 12 JsonifyHandler (class in riotwatcher.handlers.jsonifyhandler), 9 after_request() (riotwatcher.handlers.throwonerrorhandler.throwonerrorhandler method), 11 after_static_request() (riotwatcher.handlers.jsonifyhandler method), L league (riotwatcher.riotwatcher attribute), 7 12 Limit (class in riotwatcher.handlers.ratelimit), 8 after_static_request() (riotwatcher.handlers.jsonifyhandler.jsonifyhandler limit (riotwatcher.handlers.ratelimit.limit attribute), 8 LimitCollection (class in riotwatcher.handlers.ratelimit), 8 method), 10 after_static_request() (riotwatcher.handlers.requesthandler method), lol_status (riotwatcher.riotwatcher attribute), 7 11 M after_static_request() (riotwatcher.handlers.requesthandler.requesthandler match (riotwatcher.riotwatcher attribute), 7 method), 10 MethodRateLimiter (class in riotwatcher.handlers.ratelimit), 9 ApplicationRateLimiter (class in riotwatcher.handlers.ratelimit), 8 C champion (riotwatcher.riotwatcher attribute), 7 champion_mastery (riotwatcher.riotwatcher attribute), 7 count (riotwatcher.handlers.ratelimit.limit attribute), 8 D data_dragon (riotwatcher.riotwatcher attribute), 7 duration (riotwatcher.handlers.ratelimit.limit attribute), 8 F friendly_name (riotwatcher.handlers.ratelimit.headerbasedlimiter O OopsRateLimiter (class in riotwatcher.handlers.ratelimit), 9 P preview_request() (riotwatcher.handlers.ratelimit.ratelimithandler method), 9 preview_request() (riotwatcher.handlers.requesthandler method), 11 19

24 preview_request() (riotwatcher.handlers.requesthandler.requesthandler wait_until() (riotwatcher.handlers.ratelimit.limit method), 8 method), 10 preview_request() (riotwatcher.handlers.typecorrectorhandler wait_until() (riotwatcher.handlers.ratelimit.limitcollection method), 8 method), 12 preview_static_request() (riotwatcher.handlers.requesthandler wait_until() (riotwatcher.handlers.ratelimit.oopsratelimiter method), 9 WaitingRateLimitHandler (class in riotwatcher.handlers), method), preview_static_request() (riotwatcher.handlers.requesthandler.requesthandler method), 11 R RateLimitHandler (class in riotwatcher.handlers.ratelimit), 9 RequestHandler (class in riotwatcher.handlers), 11 RequestHandler (class in riotwatcher.handlers.requesthandler), 10 RiotWatcher (class in riotwatcher), 7 riotwatcher.handlers (module), 11 riotwatcher.handlers.jsonifyhandler (module), 9 riotwatcher.handlers.requesthandler (module), 10 riotwatcher.handlers.throwonerrorhandler (module), 11 S set_raw_limit() (riotwatcher.handlers.ratelimit.limit method), 8 spectator (riotwatcher.riotwatcher attribute), 7 start_time (riotwatcher.handlers.ratelimit.limit attribute), 8 summoner (riotwatcher.riotwatcher attribute), 8 T third_party_code (riotwatcher.riotwatcher attribute), 8 ThrowOnErrorHandler (class in riotwatcher.handlers), 12 ThrowOnErrorHandler (class in riotwatcher.handlers.throwonerrorhandler), 11 TypeCorrectorHandler (class in riotwatcher.handlers), 12 U update_limiter() (riotwatcher.handlers.ratelimit.headerbasedlimiter method), 8 update_limiter() (riotwatcher.handlers.ratelimit.oopsratelimiter method), 9 update_limits() (riotwatcher.handlers.ratelimit.limitcollection method), 8 W wait_until() (riotwatcher.handlers.ratelimit.headerbasedlimiter method), 8 20 Index