Cassiopeia Documentation¶
What is Cassiopeia?¶
Cassiopeia (which we fondly call Cass) is a framework for pulling and working with data from the Riot API. Cass differentiates itself from other API wrappers by taking a page from one of Cassiopeia’s quotes, “I’ll take care of everything.” Our main goal is to make your life (and ours) as developers easy.
Cass is composed of three key pieces:
An interface for pulling data from the Riot API.
A type system of classes for holding and working with the data pulled from Riot.
Caches and databases to temporarily and permanently store that data.
Together, these three pieces provide the user experience we desire. Scroll down for a quick example of how Cass works, what Cass does for you as a user, and information about contributing.
Why use Cass?¶
An excellent user interface that makes working with data from the Riot API easy and fun.
“Perfect” rate limiting.
Guaranteed optimal usage of your API key.
Built in caching and (coming) the ability to easily hook into a database for offline storage of data.
Extendability to non-Riot data. Because Cass is a framework and not just an API wrapper, you can integrate your own data sources into your project. Cass already supports Data Dragon and the
champion.gg
API in addition to the Riot API.Dynamic settings so you can configure Cass for your specific use case.
An Example¶
We will quickly and efficiently look up the champion masteries for the summoner “Kalturi” (one of the developers) and print the champions he is best at. If you just want a quick look at how the interface looks, feel free to just read these three lines and skip the explanation. The explanation explains how the three bullet points above fit together and allow this code to be run.
kalturi = Summoner(name="Kalturi")
good_with = kalturi.champion_masteries.filter(lambda cm: cm.level >= 6)
print([cm.champion.name for cm in good_with])
# At the time of writing this, this prints:
["Vel'Koz", 'Blitzcrank', 'Braum', 'Lulu', 'Sejuani']
The above three lines are relatively concise code, and if you know what lambdas and list comprehensions are then it will likely be readable. However, there is a deceptive amount of logic in these three lines, so let’s break it down. (If you don’t understand everything immediately, don’t worry, that’s why you’re using Cass. You don’t have to understand how everything works behinds the scenes, you just get to write good code.)
kalturi = Summoner(name="Kalturi")
First, we create a summoner with a name
and id
. Note that creating kalturi
doesn’t trigger a call to the Riot API – it merely instantiates a Summoner
object with a name and id.
... = kalturi.champion_masteries ...
Next we ask for the champion masteries for kalturi
by running kalturi.champion_masteries
. This creates an un-instantiated list which will contain champion masteries if any item in it is accessed.
good_with = kalturi.champion_masteries.filter(lambda cm: cm.level >= 6)
Third, the .filter
method is called on the list of champion masteries. filter
is a python built-in that operates on a list and filters the items in it based on some criteria. That criteria is defined py the lambda
function we pass in.
A lambda is a quick way of defining functions in-line without using the def
statement. In this case, lambda cm:
takes in an object and assigns it to the variable cm
, then it returns cm.level > 6
. So this lambda
will return True
for any champion mastery whose mastery level is greater than or equal to 6
.
The .filter(lambda cm: cm.level > 6)
therefore operates on the list of champion masteries. When the list is iterated over, the champion masteries are queried. This requires a summoner id, which is pulled from kalturi.id
, and the Riot API is queried for Kalturi’s champion masteries. With the champion mastery data pulled, .filter
then filters the list looking for all champion masteries with mastery level 6 or higher.
print([cm.champion.name for cm in good_with])
Finally, the third line prints a list of the champion names for those champions.
Together these three lines illustrate the concise user interface that Cass provides, the way in which the data can be used, when the data is pulled (queried).
Django web Framework¶
There is an integration of cassiopeia to the popular python web framework Django made by Mori(Paaksing), this integration is aimed to fix most issues/conflicts related to co-ocurrence of cassiopeia and Django. In this integration will give you better tools for building your Django/DRF based app, you will have the ability to use any production tested cache backends that Django’s cache framework supports.
New in v2.0: A new datastore called Omnistone is introduced in response to issue #1 of this repo, this is a refined version of Cache that automatically deletes expired objects when MAX_ENTRIES is hit, then culls the datastore according to the CULL_FRECUENCY given. The culling strategy used is the same as Django Cache Framework, which is LRU culling (Least Recently Used).
Link to django-cassiopeia [repository](https://github.com/paaksing/django-cassiopeia) (If you love using it, make sure to star!).
Link to django-cassiopeia [documentations](https://paaksing.github.io/django-cassiopeia/) (Production Release v2.0).
If you have any issues or feature requests with django-cassiopeia, tag Mori in our discord server, or fire an issue in the repository.
Unfortunately, we currently don’t have an integration to Flask and any contribution is welcome.
Contributing¶
Contributions are welcome and we have an entire page devoted to ways in which you can help us with Cass.
Overview¶
Using Cassiopeia¶
Objects that hold data from the Riot API can be created using two different interfaces. The top-level cassiopeia
module contains methods to query for objects using method calls, as well as class constructors to create objects directly.
Example usage of the two interfaces:
import cassiopeia as cass
kalturi = cass.get_summoner(name="Kalturi", region="NA")
from cassiopeia import Summoner
kalturi = Summoner(name="Kalturi", region="NA")
Also note that many types can be pulled from Summoner
objects. This is the preferred way to interact with these types. They are listed below:
from cassiopeia import Summoner
kalturi = Summoner(name="Kalturi", region="NA")
kalturi.champion_masteries
kalturi.match_history
kalturi.current_match
kalturi.leagues
Django web Framework¶
There is an integration of cassiopeia to the popular python web framework Django made by Mori(Paaksing), this integration is aimed to fix most issues/conflicts related to co-ocurrence of cassiopeia and Django. In this integration will give you better tools for building your Django/DRF based app, you will have the ability to use any production tested cache backends that Django’s cache framework supports.
New in v2.0: A new datastore called Omnistone is introduced in response to issue #1 of this repo, this is a refined version of Cache that automatically deletes expired objects when MAX_ENTRIES is hit, then culls the datastore according to the CULL_FRECUENCY given. The culling strategy used is the same as Django Cache Framework, which is LRU culling (Least Recently Used).
Link to django-cassiopeia [repository](https://github.com/paaksing/django-cassiopeia) (If you love using it, make sure to star!).
Link to django-cassiopeia [documentations](https://paaksing.github.io/django-cassiopeia/) (Production Release v2.0).
If you have any issues or feature requests with django-cassiopeia, tag Mori in our discord server, or fire an issue in the repository.
Unfortunately, we currently don’t have an integration to Flask and any contribution is welcome.
Methods and Class Constructors¶
See the links below for the method and class names for each type.
Settings¶
Data and Enums¶
These data are available as enums (constants) and can be used to interact with many of the objects and methods in Cass.
- class cassiopeia.data.Continent(value)[source]¶
Bases:
Enum
An enumeration.
- americas = 'AMERICAS'¶
- asia = 'ASIA'¶
- europe = 'EUROPE'¶
- sea = 'SEA'¶
- class cassiopeia.data.Division(value)[source]¶
Bases:
Enum
An enumeration.
- four = 'IV'¶
- one = 'I'¶
- three = 'III'¶
- two = 'II'¶
- class cassiopeia.data.GameMode(value)[source]¶
Bases:
Enum
An enumeration.
- all_random_summoners_rift = 'ARSR'¶
- all_random_urf_snow = 'SNOWURF'¶
- aram = 'ARAM'¶
- ascension = 'ASCENSION'¶
- assassinate = 'ASSASSINATE'¶
- classic = 'CLASSIC'¶
- dark_star = 'DARKSTAR'¶
- dominion = 'ODIN'¶
- doom_bots = 'DOOMBOTSTEEMO'¶
- nexus_blitz = 'NEXUSBLITZ'¶
- nexus_siege = 'SIEGE'¶
- odyssey = 'ODYSSEY'¶
- one_for_all = 'ONEFORALL'¶
- overcharge = 'OVERCHARGE'¶
- poro_king = 'KINGPORO'¶
- practice_tool = 'PRACTICETOOL'¶
- project = 'PROJECT'¶
- showdown = 'FIRSTBLOOD'¶
- star_guardian = 'STARGUARDIAN'¶
- tutorial = 'TUTORIAL'¶
- tutorial_1 = 'TUTORIAL_MODULE_1'¶
- tutorial_2 = 'TUTORIAL_MODULE_2'¶
- tutorial_3 = 'TUTORIAL_MODULE_3'¶
- urf = 'URF'¶
- utlbook = 'ULTBOOK'¶
- class cassiopeia.data.GameType(value)[source]¶
Bases:
Enum
An enumeration.
- custom = 'CUSTOM_GAME'¶
- matched = 'MATCHED_GAME'¶
- tutorial = 'TUTORIAL_GAME'¶
- class cassiopeia.data.Key(value)[source]¶
Bases:
Enum
An enumeration.
- E = 'E'¶
- Q = 'Q'¶
- R = 'R'¶
- W = 'W'¶
- class cassiopeia.data.Lane(value)[source]¶
Bases:
Enum
An enumeration.
- bot_lane = 'BOT_LANE'¶
- jungle = 'JUNGLE'¶
- mid_lane = 'MID_LANE'¶
- top_lane = 'TOP_LANE'¶
- utility = 'UTILITY'¶
- class cassiopeia.data.MasteryTree(value)[source]¶
Bases:
Enum
An enumeration.
- cunning = 'Cunning'¶
- ferocity = 'Ferocity'¶
- resolve = 'Resolve'¶
- class cassiopeia.data.MatchType(value)[source]¶
Bases:
Enum
An enumeration.
- normal = 'normal'¶
- ranked = 'ranked'¶
- tourney = 'tourney'¶
- tutorial = 'tutorial'¶
- class cassiopeia.data.Platform(value)[source]¶
Bases:
Enum
An enumeration.
- brazil = 'BR1'¶
- continent¶
- default_locale¶
- europe_north_east = 'EUN1'¶
- europe_west = 'EUW1'¶
- japan = 'JP1'¶
- korea = 'KR'¶
- latin_america_north = 'LA1'¶
- latin_america_south = 'LA2'¶
- north_america = 'NA1'¶
- oceania = 'OC1'¶
- region¶
- russia = 'RU'¶
- turkey = 'TR1'¶
- class cassiopeia.data.Position(value)[source]¶
Bases:
Enum
An enumeration.
- apex = 'APEX'¶
- bottom = 'BOTTOM'¶
- jungle = 'JUNGLE'¶
- middle = 'MIDDLE'¶
- none = 'NONE'¶
- top = 'TOP'¶
- utility = 'UTILITY'¶
- class cassiopeia.data.Queue(value)[source]¶
Bases:
Enum
An enumeration.
- all_random_summoners_rift = 'ARSR_5x5'¶
- all_random_urf = 'ARURF_5X5'¶
- all_random_urf_snow = 'SNOWURF'¶
- aram = 'ARAM'¶
- aram_butchers_bridge = 'BILGEWATER_ARAM_5x5'¶
- ascension = 'ASCENSION_5x5'¶
- black_market_brawlers = 'BILGEWATER_5x5'¶
- blind_fives = 'NORMAL_5V5_BLIND_PICK'¶
- blind_threes = 'NORMAL_3X3_BLIND_PICK'¶
- blood_hunt_assassin = 'ASSASSINATE_5x5'¶
- clash = 'CLASH'¶
- coop_ai_beginner_fives = 'BOT_5X5_BEGINNER'¶
- coop_ai_beginner_threes = 'BOT_3X3_BEGINNER'¶
- coop_ai_intermediate_fives = 'BOT_5X5_INTERMEDIATE'¶
- coop_ai_intermediate_threes = 'BOT_3X3_INTERMEDIATE'¶
- coop_ai_intro_fives = 'BOT_5X5_INTRO'¶
- coop_ai_intro_threes = 'BOT_3X3_INTRO'¶
- custom = 'CUSTOM'¶
- dark_star = 'DARKSTAR_3x3'¶
- definitely_not_dominion = 'DEFINITELY_NOT_DOMINION_5x5'¶
- deprecated_all_random_urf = 'ARURF_5X5'¶
- deprecated_aram = 'ARAM_5x5'¶
- deprecated_blind_dominion = 'ODIN_5x5_BLIND'¶
- deprecated_blind_fives = 'NORMAL_5x5_BLIND'¶
- deprecated_blind_threes = 'NORMAL_3x3'¶
- deprecated_coop_ai_beginner_fives = 'BOT_5x5_BEGINNER_DEPRECATED'¶
- deprecated_coop_ai_dominion = 'BOT_ODIN_5x5'¶
- deprecated_coop_ai_fives = 'BOT_5x5'¶
- deprecated_coop_ai_intermediate_fives = 'BOT_5x5_INTERMEDIATE_DEPRECATED'¶
- deprecated_coop_ai_intro_fives = 'BOT_5x5_INTRO_DEPRECATED'¶
- deprecated_coop_ai_threes = 'BOT_TT_3x3'¶
- deprecated_doom_bots_rank_1 = 'NIGHTMARE_BOT_5x5_RANK1'¶
- deprecated_doom_bots_rank_2 = 'NIGHTMARE_BOT_5x5_RANK2'¶
- deprecated_doom_bots_rank_5 = 'NIGHTMARE_BOT_5x5_RANK5'¶
- deprecated_draft_dominion = 'ODIN_5x5_DRAFT'¶
- deprecated_draft_fives = 'NORMAL_5x5_DRAFT'¶
- deprecated_nexus_blitz = 'NEXUS_BLITZ'¶
- deprecated_nexus_siege = 'SIEGE'¶
- deprecated_poro_king = 'KING_PORO_5x5'¶
- deprecated_ranked_fives = 'TEAM_BUILDER_DRAFT_RANKED_5x5'¶
- deprecated_ranked_flex_threes = 'RANKED_FLEX_TT_DEPRECATED'¶
- deprecated_ranked_premade_fives = 'RANKED_PREMADE_5x5'¶
- deprecated_ranked_premade_threes = 'RANKED_PREMADE_3x3'¶
- deprecated_ranked_solo_fives = 'CLASSIC'¶
- deprecated_ranked_team_fives = 'RANKED_TEAM_5x5'¶
- deprecated_ranked_team_threes = 'RANKED_TEAM_3x3'¶
- deprecated_team_builder_fives = 'GROUP_FINDER_5x5'¶
- doom_bots = 'NIGHTMARE_BOT_5X5'¶
- doom_bots_difficult = 'NIGHTMARE_BOT_5X5_VOTE'¶
- guardian_invasion_normal = 'INVASION_NORMAL'¶
- guardian_invasion_onslaught = 'INVASION_ONSLAUGHT'¶
- hexakill_summoners_rift = 'SR_6x6'¶
- hexakill_twisted_treeline = 'HEXAKILL'¶
- id¶
- mirror_mode_fives = 'ONEFORALL_MIRRORMODE_5x5'¶
- nemesis_draft = 'COUNTER_PICK'¶
- nexus_blitz = 'NEXUS_BLITZ'¶
- nexus_siege = 'NEXUS_SIEGE'¶
- normal_draft_fives = 'TEAM_BUILDER_DRAFT_UNRANKED_5x5'¶
- normal_tft = 'NORMAL_TFT'¶
- odyssey_cadet = 'ODYSSEY_CADET'¶
- odyssey_captain = 'ODYSSEY_CAPTAIN'¶
- odyssey_crewmember = 'ODYSSEY_CREWMEMBER'¶
- odyssey_intro = 'ODYSSEY_INTRO'¶
- odyssey_onslaught = 'ODYSSEY_ONSLAUGHT'¶
- one_for_all = 'ONEFORALL_5x5'¶
- one_for_all_rapid = 'ONEFORALL_RAPID_5x5'¶
- overcharge = 'OVERCHARGE'¶
- poro_king = 'KINGPORO'¶
- project = 'PROJECT'¶
- ranked_flex_fives = 'RANKED_FLEX_SR'¶
- ranked_flex_threes = 'RANKED_FLEX_TT'¶
- ranked_solo_fives = 'RANKED_SOLO_5x5'¶
- ranked_tft = 'RANKED_TFT'¶
- ranked_tft_double_up = 'RANKED_TFT_DOUBLE_UP'¶
- ranked_tft_pairs = 'RANKED_TFT_PAIRS'¶
- showdown_1v1 = 'FIRSTBLOOD_1x1'¶
- showdown_2v2 = 'FIRSTBLOOD_2x2'¶
- tutorial1 = 'TUTORIAL_1'¶
- tutorial2 = 'TUTORIAL_2'¶
- tutorial3 = 'TUTORIAL_3'¶
- ultimate_spellbook = 'ULTIMATE_SPELLBOOK'¶
- urf = 'URF_5x5'¶
- urf_coop_ai = 'BOT_URF_5x5'¶
- class cassiopeia.data.Region(value)[source]¶
Bases:
Enum
An enumeration.
- brazil = 'BR'¶
- continent¶
- default_locale¶
- europe_north_east = 'EUNE'¶
- europe_west = 'EUW'¶
- japan = 'JP'¶
- korea = 'KR'¶
- latin_america_north = 'LAN'¶
- latin_america_south = 'LAS'¶
- north_america = 'NA'¶
- oceania = 'OCE'¶
- platform¶
- russia = 'RU'¶
- timezone¶
- turkey = 'TR'¶
- class cassiopeia.data.Resource(value)[source]¶
Bases:
Enum
An enumeration.
- blood_well = 'Blood Well'¶
- courage = 'Courage'¶
- crimson_rush = 'Crimson Rush'¶
- energy = 'Energy'¶
- ferocity = 'Ferocity'¶
- flow = 'Flow'¶
- fury = 'Fury'¶
- heat = 'Heat'¶
- mana = 'Mana'¶
- no_cost = 'No Cost'¶
- none = 'None'¶
- rage = 'Rage'¶
- shield = 'Shield'¶
- class cassiopeia.data.Role(value)[source]¶
Bases:
Enum
An enumeration.
- duo = 'DUO'¶
- duo_carry = 'DUO_CARRY'¶
- duo_support = 'DUO_SUPPORT'¶
- none = 'NONE'¶
- solo = 'SOLO'¶
- class cassiopeia.data.SummonersRiftArea(value)[source]¶
Bases:
Enum
An enumeration.
- bot_lane_blue = 'BOT_LANE_BLUE'¶
- bot_lane_purple = 'BOT_LANE_PURPLE'¶
- bot_lane_red = 'BOT_LANE_RED'¶
- static from_position(position: Position) SummonersRiftArea [source]¶
- jungle_bot_blue = 'JUNGLE_BOT_BLUE'¶
- jungle_bot_red = 'JUNGLE_BOT_RED'¶
- jungle_top_blue = 'JUNGLE_TOP_BLUE'¶
- jungle_top_red = 'JUNGLE_TOP_RED'¶
- mid_lane_blue = 'MID_LANE_BLUE'¶
- mid_lane_purple = 'MID_LANE_PURPLE'¶
- mid_lane_red = 'MID_LANE_RED'¶
- nexus_blue = 'NEXUS_BLUE'¶
- nexus_red = 'NEXUS_RED'¶
- none = 'NONE'¶
- river_bot = 'RIVER_BOT'¶
- river_top = 'RIVER_TOP'¶
- top_lane_blue = 'TOP_LANE_BLUE'¶
- top_lane_purple = 'TOP_LANE_PURPLE'¶
- top_lane_red = 'TOP_LANE_RED'¶
- class cassiopeia.data.Tier(value)[source]¶
Bases:
Enum
An enumeration.
- bronze = 'BRONZE'¶
- challenger = 'CHALLENGER'¶
- diamond = 'DIAMOND'¶
- emerald = 'EMERALD'¶
- gold = 'GOLD'¶
- grandmaster = 'GRANDMASTER'¶
- iron = 'IRON'¶
- master = 'MASTER'¶
- platinum = 'PLATINUM'¶
- silver = 'SILVER'¶
- unranked = 'UNRANKED'¶
Champions¶
- class cassiopeia.Champions(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- included_data¶
A set of tags to return additonal information for this champion when it’s loaded.
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- locale¶
The locale for this champion.
- platform¶
The platform for this champion.
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
The region for this champion.
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
The version for this champion.
- class cassiopeia.Champion(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘int’, ‘Region’, ‘Platform’, ‘bool’]
- ally_tips¶
The tips for playing with this champion.
- ban_rates¶
- blurb¶
A short blurb about this champion.
- enemy_tips¶
The tips for playing against this champion.
- free_to_play¶
Whether or not the champion is currently free to play.
- free_to_play_new_players¶
Whether or not the champion is currently free to play for new players.
- id¶
The champion’s ID.
- image¶
The image information for this champion.
- included_data¶
A set of tags to return additonal information for this champion when it’s loaded.
- info¶
Info about this champion.
- key¶
The champion’s key.
- locale¶
The locale for this champion.
- lore¶
The champion’s lore.
- name¶
The champion’s name.
- passive¶
This champion’s passive.
- platform¶
The platform for this champion.
- play_rates¶
- recommended_itemsets¶
The champion’s recommended itemsets.
- region¶
The region for this champion.
- release_date¶
- resource¶
The type of resource this champion uses.
- skins¶
This champion’s skins.
- spells¶
This champion’s spells.
- sprite¶
- stats¶
The champion’s stats.
- tags¶
The tags associated with this champion.
- title¶
The champion’s title.
- version¶
The version for this champion.
- win_rates¶
- class cassiopeia.core.staticdata.champion.Info(**kwargs)[source]¶
Bases:
CassiopeiaObject
- attack¶
How attack-oriented Riot rates this champion.
- defense¶
How defense-oriented Riot rates this champion.
- difficulty¶
How Riot rates the difficulty of this champion.
- magic¶
How magic-oriented Riot rates this champion.
- class cassiopeia.core.staticdata.champion.Stats(**kwargs)[source]¶
Bases:
CassiopeiaObject
- armor¶
- armor_per_level¶
- attack_damage¶
- attack_damage_per_level¶
- attack_range¶
- attack_speed¶
- critical_strike_chance¶
- critical_strike_chance_per_level¶
- health¶
- health_per_level¶
- health_regen¶
- health_regen_per_level¶
- magic_resist¶
- magic_resist_per_level¶
- mana¶
- mana_per_level¶
- mana_regen¶
- mana_regen_per_level¶
- movespeed¶
- percent_attack_speed_per_level¶
- class cassiopeia.core.staticdata.champion.Skin(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘int’]
- champion_key¶
The key for the champion this belongs to.
- id¶
The skin’s ID.
- loading_image¶
The skin’s loading screen image.
- loading_image_url¶
The skin’s loading screen image url.
- name¶
The skin’s name.
- number¶
The skin number.
- splash¶
The skin’s splash art.
- splash_url¶
The skin’s splash art url.
- class cassiopeia.core.staticdata.champion.Passive(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’]
- description¶
The spells’ description.
- image_info¶
The info about the spell’s image, which can be pulled from datadragon.
- name¶
The spell’s name.
- sanitized_description¶
The spell’s sanitized description.
- class cassiopeia.core.staticdata.champion.RecommendedItems(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘Item’, ‘GameMode’]
- item_sets¶
The recommended item sets.
- map¶
The name of the map these recommendations are for.
- mode¶
The game mode these recommendations are for.
- priority¶
Whether this is a priority recommendation.
- title¶
The title of these recommendations.
- type¶
The type of recommendation.
- class cassiopeia.core.staticdata.champion.ItemSet(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘Item’]
- items¶
A dictionary of items mapped to how many of them are recommended.
- rec_math¶
Well, we don’t know what this one is. let us know if you figure it out.
- type¶
The item set’s type (e.g. starting items).
- class cassiopeia.core.staticdata.champion.ChampionSpell(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘Key’]
- alternative_images¶
The alternative images for this spell. These won’t exist after patch NN, when Riot standardized all images.
- cooldowns¶
The cooldowns of this spell (per level).
- costs¶
The resource costs of this spell (per level).
- description¶
The spell’s description.
- effects¶
The level-by-level replacements for {{ e# }} tags in other values.
- effects_by_level¶
The level-up changes, level-by-level.
- image_info¶
The info about the spell’s image, which can be pulled from datadragon.
- key¶
The spell’s key.
- keyboard_key¶
Q, W, E, or R
- keywords¶
The keywords for this spell.
- max_rank¶
The maximum rank this spell can attain.
- name¶
The spell’s name.
- range¶
The maximum range of this spell. self if it has no range.
- resource¶
The resource consumed when using this spell.
- sanitized_description¶
The spell’s sanitized description.
- sanitized_tooltip¶
The spell’s sanitized tooltip.
- tooltip¶
The spell’s tooltip.
- variables¶
Contains spell data.
- class cassiopeia.core.staticdata.champion.SpellVars(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’]
- coefficients¶
The scaling coefficients for this spell.
- dynamic¶
Well, we don’t know what this one is. let us know if you figure it out.
- key¶
Well, we don’t know what this one is. let us know if you figure it out.
- link¶
Stat this spell scales from.
- ranks_with¶
Well, we don’t know what this one is. let us know if you figure it out.
- class cassiopeia_championgg.core.ChampionGGStats(**kwargs)[source]¶
Bases:
CassiopeiaObject
- assists¶
- ban_rate¶
- championgg_metadata¶
- damage_composition¶
- deaths¶
- elo¶
- games_played¶
- gold_earned¶
- id¶
- kills¶
- matchups¶
- minions_killed¶
- neutral_minions_killed_in_enemy_jungle¶
- neutral_minions_killed_in_team_jungle¶
- patch¶
- performance_score¶
- play_rate¶
- play_rate_by_role¶
- role¶
- total_damage_taken¶
- total_healed¶
- wards_killed¶
- win_rate¶
- class cassiopeia_championgg.core.ChampionGGMatchups(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- class cassiopeia_championgg.core.ChampionGGMatchup(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’]
- elo¶
- enemy¶
- me¶
- nmatches¶
- patch¶
- region¶
- winrate¶
- class cassiopeia_championgg.core.ChampionGGMatchupStats(data, id)[source]¶
Bases:
object
- assists¶
- champion¶
- deaths¶
- delta_assists¶
- delta_deaths¶
- delta_gold_earned¶
- delta_killing_sprees¶
- delta_kills¶
- delta_minions_killed¶
- delta_neutral_minions_killed_team_jungle¶
- delta_ten_to_twenty¶
- delta_thirty_to_end¶
- delta_total_damage_dealt_to_champions¶
- delta_twenty_to_thirty¶
- delta_weighted_score¶
- delta_wins¶
- delta_zero_to_ten¶
- gold_earned¶
- id¶
- killing_sprees¶
- kills¶
- minions_killed¶
- neutral_minions_killed_team_jungle¶
- role¶
- thirty_to_end¶
- total_damage_dealt_to_champions¶
- twenty_to_thirty¶
- weighted_score¶
- winrate¶
- wins¶
- zero_to_ten¶
Champion Masteries¶
- cassiopeia.get_champion_mastery(champion: Union[Champion, int, str], region: Optional[Union[Region, str]] = None) ChampionMastery ¶
- class cassiopeia.ChampionMasteries(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- summoner¶
- to_dict()¶
- to_json(**kwargs)¶
- class cassiopeia.ChampionMastery(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘int’, ‘bool’, ‘Arrow’, ‘Champion’, ‘Summoner’]
- champion¶
Champion for this entry.
- chest_granted¶
Is chest granted for this champion or not in current season?
- last_played¶
Last time this champion was played by this player.
- level¶
Champion level for specified player and champion combination.
- platform¶
- points¶
Total number of champion points for this player and champion combination - used to determine champion level.
- points_since_last_level¶
Number of points earned since current level has been achieved. Zero if player reached maximum champion level for this champion.
- points_until_next_level¶
Number of points needed to achieve next level. Zero if player reached maximum champion level for this champion.
- region¶
- summoner¶
Summoner for this entry.
- tokens¶
Number of tokens earned toward next mastery level.
Items¶
- class cassiopeia.Items(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- included_data¶
A set of tags to return additional information for this item when it’s loaded.
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- locale¶
The locale for this item.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
- class cassiopeia.Item(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘int’, ‘Region’, ‘Platform’, ‘Map’]
- builds_from¶
- builds_into¶
- champion¶
- consume_on_full¶
- consumed¶
- description¶
- effect¶
- gold¶
- group¶
- hide¶
- id¶
The item’s ID.
- image¶
The image information for this item.
- in_store¶
- included_data¶
A set of tags to return additonal information for this item when it’s loaded.
- keywords¶
- locale¶
The locale for this item.
- maps¶
- max_stacks¶
- name¶
- plaintext¶
- platform¶
The platform for this item.
- region¶
The region for this item.
- sanitized_description¶
- special_recipe¶
- sprite¶
- stats¶
- tags¶
- tier¶
- version¶
The version for this item.
- class cassiopeia.core.staticdata.item.ItemStats(**kwargs)[source]¶
Bases:
CassiopeiaObject
- ability_power¶
- armor¶
- attack_damage¶
- attack_speed¶
- block¶
- critical_strike_chance¶
- critical_strike_damage¶
- dodge¶
- energy¶
- energy_regen¶
- health¶
- health_regen¶
- life_steal¶
- magic_resist¶
- mana¶
- mana_regen¶
- movespeed¶
- percent_ability_power¶
- percent_armor¶
- percent_attack_damage¶
- percent_attack_speed¶
- percent_block¶
- percent_critical_strike_damage¶
- percent_health¶
- percent_health_regen¶
- percent_magic_resist¶
- percent_mana_regen¶
- percent_movespeed¶
- percent_xp_bonus¶
- spell_vamp¶
- xp_bonus¶
Language Strings¶
- cassiopeia.get_language_strings() LanguageStrings ¶
Leagues¶
- cassiopeia.Summoner.leagues¶
- class cassiopeia.core.league.League(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘Queue’, ‘Tier’]
- entries¶
- id¶
- name¶
- platform¶
- queue¶
- region¶
- tier¶
- class cassiopeia.core.ChallengerLeague(*args, **kwargs)[source]¶
Bases:
League
- entries¶
- id¶
- name¶
- platform¶
- queue¶
- region¶
- tier¶
- class cassiopeia.core.MasterLeague(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
- entries¶
- id¶
- name¶
- platform¶
- queue¶
- region¶
- tier¶
- class cassiopeia.core.league.LeagueSummonerEntries(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- fives¶
- flex¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- threes¶
- to_dict()¶
- to_json(**kwargs)¶
- class cassiopeia.core.league.MiniSeries(**kwargs)[source]¶
Bases:
CassiopeiaObject
- losses¶
- not_played¶
The number of games in the player’s promos that they haven’t played yet.
- progress¶
A list of True/False for the number of games the played in the mini series indicating if the player won or lost.
- wins¶
- wins_required¶
2 or 3 wins will be required for promotion.
- class cassiopeia.core.league.LeagueEntries(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- division¶
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- classmethod from_generator(generator: Generator, region: Optional[Union[Region, str]] = None, queue: Optional[Queue] = None, tier: Optional[Tier] = None, division: Optional[Division] = None, **kwargs)[source]¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- queue¶
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- tier¶
- to_dict()¶
- to_json(**kwargs)¶
- class cassiopeia.core.league.LeagueEntry(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘bool’, ‘Division’, ‘Summoner’, ‘Queue’]
- division¶
- fresh_blood¶
- classmethod from_data(data: LeagueEntryData, loaded_groups: Optional[Set[Type[CoreData]]] = None, league: Optional[League] = None)[source]¶
- hot_streak¶
- inactive¶
- league¶
- league_points¶
- losses¶
- platform¶
The platform for this champion.
- promos¶
- queue¶
- region¶
The region for this champion.
- role¶
- summoner¶
- tier¶
- veteran¶
- wins¶
Locales¶
- class cassiopeia.Locales(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
Maps¶
- class cassiopeia.Maps(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- locale¶
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
Matches¶
- cassiopeia.Summoner.match_history¶
- cassiopeia.get_match_history(puuid: Optional[str] = None, start_time: Optional[Arrow] = None, end_time: Optional[Arrow] = None, queue: Optional[Queue] = None, type: Optional[MatchType] = None, start: Optional[int] = None, count: Optional[int] = None)¶
- class cassiopeia.core.match.MatchHistory(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
The match history for a summoner. By default, this will return the entire match history.
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count¶
Return number of occurrences of value.
- end_time¶
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- start¶
- start_time¶
- to_dict()¶
- to_json(**kwargs)¶
- class cassiopeia.Match(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘Continent’, ‘Queue’, ‘MatchType’, ‘GameMode’, ‘Map’, ‘GameType’, ‘Item’, ‘Patch’, ‘Summoner’, ‘SummonerSpell’]
- blue_team¶
- continent¶
The continent for this match.
- creation¶
- duration¶
- exists¶
- game_type¶
- id¶
- is_remake¶
- map¶
- mode¶
- participants¶
- patch¶
- platform¶
The platform for this match.
- queue¶
- red_team¶
- region¶
The region for this match.
- start¶
- teams¶
- timeline¶
- type¶
- version¶
- class cassiopeia.core.match.Team(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘bool’, ‘Champion’, ‘Summoner’, ‘SummonerSpell’]
- bans¶
- baron_kills¶
- dominion_score¶
- dragon_kills¶
- first_baron¶
- first_blood¶
- first_dragon¶
- first_inhibitor¶
- first_rift_herald¶
- first_tower¶
- inhibitor_kills¶
- participants¶
- rift_herald_kills¶
- side¶
- tower_kills¶
- win¶
- class cassiopeia.core.match.Participant(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘Summoner’, ‘Champion’, ‘Side’, ‘Rune’, ‘SummonerSpell’]
- champion¶
- cumulative_timeline¶
- ended_in_early_surrender¶
- enemy_team¶
- id¶
- individual_position¶
- is_bot¶
- lane¶
- role¶
- runes¶
- side¶
- skill_order¶
- stat_runes¶
- stats¶
- summoner¶
- summoner_spell_d¶
- summoner_spell_f¶
- team¶
- team_position¶
- timeline¶
- version¶
- class cassiopeia.core.match.ParticipantStats(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’, ‘Item’]
- assists¶
- baron_kills¶
- bounty_level¶
- champion_experience¶
- consumables_purchased¶
- damage_dealt_to_buildings¶
- damage_dealt_to_objectives¶
- damage_dealt_to_turrets¶
- damage_self_mitigated¶
- deaths¶
- double_kills¶
- dragon_kills¶
- first_blood_assist¶
- first_blood_kill¶
- first_tower_assist¶
- first_tower_kill¶
- classmethod from_data(data: ParticipantStatsData, match: Match, participant: Participant)[source]¶
- gold_earned¶
- gold_spent¶
- inhibitor_kills¶
- inhibitor_takedowns¶
- inhibitors_lost¶
- items¶
- items_purchased¶
- kda¶
- killing_sprees¶
- kills¶
- largest_critical_strike¶
- largest_killing_spree¶
- largest_multi_kill¶
- level¶
- longest_time_spent_living¶
- magic_damage_dealt¶
- magic_damage_dealt_to_champions¶
- magic_damage_taken¶
- neutral_minions_killed¶
- nexus_kills¶
- nexus_lost¶
- nexus_takedowns¶
- objectives_stolen¶
- objectives_stolen_assists¶
- penta_kills¶
- physical_damage_dealt¶
- physical_damage_dealt_to_champions¶
- physical_damage_taken¶
- quadra_kills¶
- sight_wards_bought¶
- spell_1_casts¶
- spell_2_casts¶
- spell_3_casts¶
- spell_4_casts¶
- summoner_spell_1_casts¶
- summoner_spell_2_casts¶
- time_CCing_others¶
- time_played¶
- total_damage_dealt¶
- total_damage_dealt_to_champions¶
- total_damage_shielded_on_teammates¶
- total_damage_taken¶
- total_heal¶
- total_heals_on_teammates¶
- total_minions_killed¶
- total_time_cc_dealt¶
- total_time_spent_dead¶
- total_units_healed¶
- triple_kills¶
- true_damage_dealt¶
- true_damage_dealt_to_champions¶
- true_damage_taken¶
- turret_kills¶
- turret_takedowns¶
- turrets_lost¶
- unreal_kills¶
- vision_score¶
- vision_wards_bought¶
- vision_wards_placed¶
- wards_killed¶
- wards_placed¶
- win¶
- class cassiopeia.core.match.ParticipantTimeline[source]¶
Bases:
object
- champion_assists¶
- champion_deaths¶
- champion_kills¶
- events¶
- frames¶
- class cassiopeia.core.match.Timeline(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
- continent¶
- first_tower_fallen¶
- frame_interval¶
- frames¶
- id¶
- platform¶
- region¶
- class cassiopeia.core.match.Frame(**kwargs)[source]¶
Bases:
CassiopeiaObject
- events¶
- participant_frames¶
- timestamp¶
- class cassiopeia.core.match.ParticipantFrame(**kwargs)[source]¶
Bases:
CassiopeiaObject
- creep_score¶
- current_gold¶
- dominion_score¶
- experience¶
- gold_earned¶
- level¶
- neutral_minions_killed¶
- participant_id¶
- position¶
- team_score¶
- class cassiopeia.core.match.Event(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’]
- after_id¶
- ascended_type¶
- assisting_participants¶
- before_id¶
- building_type¶
- captured_point¶
- creator_id¶
- item_id¶
- killer_id¶
- lane_type¶
- level_up_type¶
- monster_sub_type¶
- monster_type¶
- participant_id¶
- position¶
- side¶
- skill¶
- timestamp¶
- tower_type¶
- type¶
CHAMPION_KILL, WARD_PLACED, WARD_KILL, BUILDING_KILL, ELITE_MONSTER_KILL, ITEM_PURCHASED, ITEM_SOLD, ITEM_DESTROYED, ITEM_UNDO, SKILL_LEVEL_UP, ASCENDED_EVENT, CAPTURE_POINT, PORO_KING_SUMMON
- Type:
Legal values
- victim_id¶
- ward_type¶
- class cassiopeia.core.match.CumulativeTimeline(id: int, participant_timeline: ParticipantTimeline)[source]¶
Bases:
object
- class cassiopeia.core.match.ParticipantState(id: int, time: timedelta, participant_timeline: ParticipantTimeline)[source]¶
Bases:
object
The state of a participant at a given point in the timeline.
- assists¶
- creep_score¶
- current_gold¶
- deaths¶
- dominion_score¶
- experience¶
- gold_earned¶
- items¶
- kda¶
- kills¶
- level¶
- neutral_minions_killed¶
- objectives¶
Number of objectives assisted in.
- position¶
- skills¶
- team_score¶
Patch¶
Profile Icons¶
- cassiopeia.Summoner.profile_icon¶
- cassiopeia.get_profile_icons() ProfileIcons ¶
- class cassiopeia.ProfileIcons(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- locale¶
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
- class cassiopeia.core.staticdata.profileicon.ProfileIcon(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘int’, ‘str’, ‘Image’]
- id¶
- image¶
- locale¶
The locale for this profile icon.
- name¶
- platform¶
The platform for this profile icon.
- region¶
The region for this profile icon.
- url¶
- version¶
The version for this profile icon.
Realms¶
- class cassiopeia.Realms(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by []
- cdn¶
- css_version¶
- language¶
- latest_data_dragon¶
- latest_versions¶
Latest changed version for each data type listed.
- legacy_mode¶
- locale¶
The locale for this realm.
- max_profile_icon_id¶
- platform¶
The platform for this realm.
- region¶
The region for this realm.
- store¶
- version¶
Runes¶
- class cassiopeia.Runes(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- domination¶
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- included_data¶
A set of tags to return additonal information for this champion when it’s loaded.
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- inspiration¶
- keystones¶
- locale¶
The locale for this champion.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- precision¶
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- resolve¶
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sorcery¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
- class cassiopeia.Rune(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘int’, ‘RunePath’, ‘Region’, ‘Platform’]
- id¶
The rune’s ID.
- image¶
The image information for this rune.
- included_data¶
A set of tags to return additional information for this champion when it’s loaded.
- is_keystone¶
- locale¶
The locale for this rune.
- long_description¶
- name¶
The rune’s name.
- path¶
- platform¶
The platform for this rune.
- region¶
The region for this rune.
- short_description¶
- tier¶
- version¶
The version for this rune.
Status¶
- cassiopeia.get_status() ShardStatus ¶
Spectator¶
- cassiopeia.Summoner.current_match¶
- cassiopeia.get_featured_matches() FeaturedMatches ¶
- class cassiopeia.FeaturedMatches(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- client_refresh_interval¶
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- class cassiopeia.core.spectator.CurrentMatch(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by []
- blue_team¶
- creation¶
- duration¶
- exists¶
- id¶
- map¶
- mode¶
- observer_key¶
- participants¶
- platform¶
- queue¶
- red_team¶
- region¶
- teams¶
- type¶
Summoners¶
- cassiopeia.get_summoner(*, account_id: Optional[str] = None, name: Optional[str] = None, region: Optional[Union[Region, str]] = None) Summoner ¶
- class cassiopeia.Summoner(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’, ‘Region’, ‘Platform’]
- account_id¶
- champion_masteries¶
- current_match¶
- exists¶
- id¶
- league_entries¶
- level¶
- match_history¶
- match_history_uri¶
- name¶
- platform¶
The platform for this summoner.
- profile_icon¶
- puuid¶
- ranks¶
- region¶
The region for this summoner.
- revision_date¶
- sanitized_name¶
- verification_string¶
Summoner Spells¶
- cassiopeia.get_summoner_spells() SummonerSpells ¶
- class cassiopeia.SummonerSpells(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- included_data¶
A set of tags to return additonal information for this champion when it’s loaded.
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- locale¶
The locale for this champion.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
- version¶
- class cassiopeia.SummonerSpell(*args, **kwargs)[source]¶
Bases:
CassiopeiaGhost
Searchable by [‘str’]
- alternative_images¶
The alternative images for this spell. These won’t exist after patch NN, when Riot standardized all images.
- cooldowns¶
The cooldowns of this spell (per level).
- costs¶
The resource costs of this spell (per level).
- description¶
The spell’s description.
- effects¶
The level-by-level replacements for {{ e# }} tags in other values.
- id¶
The spell’s id.
- image¶
- included_data¶
The data to included in the query for this summoner spell.
- key¶
The spell’s key.
- locale¶
The locale for this summoner spell.
- max_rank¶
The maximum rank this spell can attain.
- modes¶
- name¶
The spell’s name.
- platform¶
The platform for this summoner spell.
- range¶
The maximum range of this spell. self if it has no range.
- region¶
The region for this summoner spell.
- resource¶
The resource consumed when using this spell.
- sanitized_description¶
The spell’s sanitized description.
- sanitized_tooltip¶
The spell’s sanitized tooltip.
- sprite¶
- tooltip¶
The spell’s tooltip.
- variables¶
Contains spell data.
- version¶
The version for this summoner spell.
- class cassiopeia.core.staticdata.summonerspell.SpellVars(**kwargs)[source]¶
Bases:
CassiopeiaObject
Searchable by [‘str’]
- coefficients¶
The scaling coefficients for this spell.
- dynamic¶
Well, we don’t know what this one is. let us know if you figure it out.
- key¶
Well, we don’t know what this one is. let us know if you figure it out.
- link¶
Stat this spell scales from.
- ranks_with¶
Well, we don’t know what this one is. let us know if you figure it out.
Versions¶
- class cassiopeia.Versions(*args, **kwargs)[source]¶
Bases:
CassiopeiaLazyList
- append(item)¶
Append object to the end of the list.
- clear()¶
Remove all items from list.
- copy()¶
Return a shallow copy of the list.
- count(object)¶
Return number of occurrences of value.
- extend(iterable)¶
Extend list by appending elements from the iterable.
- filter(function)¶
- classmethod from_data(*args, **kwargs)¶
- index(object, start: int = 0, stop: int = 9223372036854775807)¶
Return first index of value.
Raises ValueError if the value is not present.
- platform¶
- pop(index: int = - 1)¶
Remove and return item at index (default last).
Raises IndexError if list is empty or index is out of range.
- region¶
- remove(object)¶
Remove first occurrence of value.
Raises ValueError if the value is not present.
- reverse()¶
Reverse IN PLACE.
- search(item: Any, streaming: bool = False, reverse: bool = False) Union[SearchableList, Generator[Any, None, None]] ¶
- sort(*, key=None, reverse=False)¶
Sort the list in ascending order and return None.
The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).
If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.
The reverse flag can be set to sort in descending order.
- to_dict()¶
- to_json(**kwargs)¶
Setup¶
Cassiopeia requires Python 3.6 and we highly recommend installing Anaconda with Python 3.6.
Install using pip¶
Simply pip install cassiopeia
to get the latest release. (See the pip install page if you do not have pip
installed.) If you want to pull the most recent version, you can install directly from GitHub using pip install git+https://github.com/meraki-analytics/cassiopeia.git
instead. We may not make a PyPy release (which pip
usually pulls from) for small changes to the code.
PyCurl Issues¶
You may have some issues during installation due to PyCurl. Try the installation first, and if you have issues with pycurl come back and read this section. If Cass installed properly but is throwing certificate errors, skip to the 3rd paragraph.
At the moment PyCurl does not fully support installation with Python 3.6 and many people have had issues. The easiest thing to do (and what we highly recommend) is to install Python 3.6 via Anaconda. Anaconda is a package manager for Python and provides many packages that are difficult to install without Anaconda. If you do not or can’t use Anaconda, you’ll need download and install Curl, then use easy_install
to install PyCurl and link it to the proper Curl libraries. This isn’t much fun, and again we recommend Anaconda to ease the process.
If you successfully installed Cass but it’s throwing a certificate error, you probably just need to pip install certifi
. This should solve any certificate errors.
If you are having more problems, let us know via the Riot API discord server or our Meraki discord server.
Alternative library support¶
In case PyCurl is not installed, Cassiopeia falls back to Requests, this is a direct dependency and the user is not required to install the library manually.
Furthermore, ujson is used instead of Python’s default json module when available. To use ujson in conjunction with Requests, the following patch needs to be applied before running any API requests.
# see https://github.com/psf/requests/issues/1595#issuecomment-504030697 for more details
import requests
import ujson
requests.models.complexjson = ujson
Install from Source¶
If you would like to get Cassiopeia with the most recent updates (even before they have been pushed in an official release), you can clone the repository. Go to Cassiopeia’s Github page and either download the zip or git clone https://github.com/meraki-analytics/cassiopeia
into a directory of your choice.
Next, run pip install -r requirements.txt
in the newly downloaded cassiopeia directory to install the dependencies.
Next, add the newly downloaded cassiopeia source directory to your PYTHONPATH
environment variable. If a PYTHONPATH
environment variable does not exist on your system (which may be true if you have a newly installed version of python), you will need to create it.
On Windows, follow the instructions here. Note that if you need multiple paths on your PYTHONPATH
, you can separate them with a ;
.
On Mac or Linux, add export PYTHONPATH=$PYTHONPATH:<CASSIOPEIA PATH>
to the end of your shell rc file (this should be ~/.bashrc
for most), where <CASSIOPEIA PATH>
is the path of the directory you cloned, or the cassiopeia.zip file you downloaded.
Restart your terminal/IDE.
Google can probably give you more information as well, and note that the path name you add your your PYTHONPATH
should end in .../cassiopeia
.
Setting Your API Key and Other Settings¶
By default, Cass pulls your API key from an environment variable called RIOT_API_KEY
. You can modify this behavior by calling cass.set_riot_api_key(...)
or by creating a your own configuration for Cass (see Settings for more info). However, we encourage new users to use Cass’s default configuration.
To create an environment variable on Windows, follow the directions here. On Linux or Mac, add export RIOT_API_KEY='<YOUR_API_KEY>'
to the end of your shell rc file (this should be ~/.bashrc
for most), where <YOUR_API_KEY>
is your Riot-issued API key. Then restart your terminal/IDE.
Plugins¶
Cass has plugins that enable additional functionality. See Plugins for more information about how to install each plugin.
Settings¶
There are many settings in Cassiopeia that control how the framework works, and more settings will be added as the code is expanded.
Use cass.apply_settings(...)
and pass in a json
filename, a dictionary, or a cassiopeia.Settings
object to set Cass’s parameters. Cass will use its own default settings if you do not run cass.apply_settings
.
The method cass.get_default_config()
will return a dictionary that contains the default settings that Cass uses. You can call this method, modify the returned dictionary, then pass it to cass.apply_settings
to overwrite the default settings.
The most important setting is your Riot API key. It can be set programmatically (which will override the value specified in the settings).
Each setting is explained below, and should be added as separate entries to your settings dictionary/json.
Globals¶
The "default_region"
setting should be set to the string version of the region that the Riot API requires (in all caps), for example "NA"
for North America. This can be set programmatically using cass.set_default_region
.
The "version_from_match"
variable determines which version of the static data for matches is loaded (this includes, for example, the items for each participant). Valid values are "version"
, "patch"
, and "latest"
. If set to "version"
, the static data for the match’s version will be loaded correctly; however, this requires pulling the match data for all matches. If you only want to use match reference data (and will not pull the full data for every match), you should use either "patch"
or "latest"
. "patch"
will make a reasonable attempt to get the match’s correct version based on its creation date (which is provided in the match reference data); however, if you pull a summoner’s full match history, you will pull many versions of the static data, which may take a long time. In addition, the patch dates / times may be slightly off and may depend on the region. For small applications that barely uses the static data, pulling multiple versions of the static data is likely overkill. If that is the case, you should set this variable to "latest"
, in which case the static data for the most recent version will be used; this, however, could result in missing or incorrect data if parts of the static data are accessed that have changed from patch to patch. The default is to use the patch if the match hasn’t yet been loaded, which is a nice compromise between ensuring you, the user, always have correct data while also preventing new users from pulling a massive amount of unnecessary match data. It’s likely that the patch dates aren’t perfect, so be aware of this and please report and inconsistencies.
Below is an example:
{
...,
"global": {
"version_from_match": "patch",
"default_region": null
}
...
}
Data Pipeline¶
This setting is extremely important and therefore has its own page (Data Pipeline). However, our defaults will likely work for you if you’re just getting started.
Riot API¶
The Riot API variable is an attribute of the pipeline
variable, but it has a variety of settings relevant to the Riot API.
The "api_key"
should be set to your Riot API key. You can instead supply an environment variable name that contains your API key (this is recommended so that you can push your settings file to version control without revealing your API key). This variable can be set programmatically via cass.set_riot_api_key
.
The "limit_sharing"
variable specifies what fraction of your API key should be used for your server. This is useful when you have multiple servers that you want to split your API key over. The default (if not set) is 1.0
, and valid values are between 0.0
and 1.0
.
Request Handling¶
The "request_error_handling"
variable specifies how errors returned by the Riot API should be handled. There are three options, each of which has its own set of parameters: "throw"
simply causes the error returned by the Riot API to be thrown to you, the user; "exponential_backoff"
will exponentially backoff; and "retry_from_headers"
will attempt to use the "retry-after"
header in the response to retry after the specified amount of time. The 429
error code can be handled differently depending on which type of rate limiting cause it. See the example below for the specific structure for these settings.
"throw"
takes no arguments.
"exponential_backoff"
takes three arguments: initial_backoff
specifies the initial time to pause before making another request, backoff_factor
specifies what to multiply the initial_backoff
by for each subsequent failure, and max_attempts
specifies the maximum number of calls to make before throwing the error.
"retry_from_headers"
takes one argument: max_attempts
specifies the maximum number of calls to make before throwing the error.
Below is an example, and these settings are the default if any value is not specified:
"RiotAPI": {
"api_key": "RIOT_API_KEY",
"limiting_share": 1.0,
"request_error_handling": {
"404": {
"strategy": "throw"
},
"429": {
"service": {
"strategy": "exponential_backoff",
"initial_backoff": 1.0,
"backoff_factor": 2.0,
"max_attempts": 4
},
"method": {
"strategy": "retry_from_headers",
"max_attempts": 5
},
"application": {
"strategy": "retry_from_headers",
"max_attempts": 5
}
},
"500": {
"strategy": "throw"
},
"503": {
"strategy": "throw"
},
"timeout": {
"strategy": "throw"
}
}
}
An alternative setting for request_error_handling
is below, which will retry 50x errors:
"request_error_handling": {
"404": {
"strategy": "throw"
},
"429": {
"service": {
"strategy": "exponential_backoff",
"initial_backoff": 1.0,
"backoff_factor": 2.0,
"max_attempts": 4
},
"method": {
"strategy": "retry_from_headers",
"max_attempts": 5
},
"application": {
"strategy": "retry_from_headers",
"max_attempts": 5
}
},
"500": {
"strategy": "exponential_backoff",
"initial_backoff": 1.0,
"backoff_factor": 2.0,
"max_attempts": 4
},
"503": {
"strategy": "exponential_backoff",
"initial_backoff": 1.0,
"backoff_factor": 2.0,
"max_attempts": 4
},
"timeout": {
"strategy": "throw"
},
"403": {
"strategy": "throw"
}
}
Logging¶
The "logging"
section defines variables related to logging and print statements.
The "print_calls"
variable should be set to true
or false
and determines whether http calls (e.g. to the Riot API or Data Dragon) are printed. Similarly, the "print_riot_api_key"
variable will print your Riot API key if set to true
.
"core"
and "default"
are two loggers that are currently implemented in Cass, and you can set the logging levels using these variables. Acceptable values are the logging levels for python’s logging module (e.g. "INFO"
and "WARNING"
).
Example:
"logging": {
"print_calls": true,
"print_riot_api_key": false,
"default": "WARNING",
"core": "WARNING"
}
Plugins¶
The "plugins"
section defines which plugins Cassiopeia will use. See Plugins for specifics for each plugin.
How Cass Works¶
There are a few major parts that make Cass work, with minor parts that go along with them. These are discussed below.
Two Interfaces¶
Cass has two interfaces that work nearly identically. Depending on your coding style, you can choose the one that you prefer. One uses .get_...
methods to get objects, while the other prefers constructors to create objects. Both are equally good. As an example, both cass.get_summoner(name="Kalturi", region="NA")
and Summoner(name="Kalturi", region="NA")
work exactly the same.
Settings¶
There are a few settings in Cass that should be modified, and more that can be modified. See Settings for more info.
Ghost Loading¶
A ghost object is an object that can be instantiated without all of its data. It is therefore a shadow of itself, or a ghost. Ghost objects know how to load the rest of their data using what they were given at init. This is what allows you to write kalturi = Summoner(name="Kalturi", region="NA")
followed by kalturi.level
. The latter will trigger a call to the data pipeline (discussed below) to pull the rest of the data for kalturi
by using kalturi.name
.
Most top-level objects in Cass are ghost objects and therefore know how to load their own data.
For developers who are interested, the implementation for ghost objects can be found in our merakicommons
repository on GitHub.
Data Pipeline¶
The data pipeline is the series of caches, databases, and data sources (such as the Riot API) that both provide and store data. Data sources provide data, while data sinks store data; we call both of these “data stores”. Some parts of the data pipeline are only data sources (for example, the Riot API), while others are both data sources and data sinks (for example, caches and databases). The data pipeline is a list of data stores, where the order the data stores specifies how data is pulled and stored (see the next paragraph). Usually faster data stores go at the beginning of the data pipeline.
When data is queried, a query dictionary is constructed containing the information needed to uniquely identify an object in a data source (e.g. a region
and summoner.id
are required when querying for Summoner
objects). This query is passed up the data pipeline through the data sources, and at each data source the data pipeline asks if that source can supply the requested object. If the source can supply the object (for example, if the object is in the database, or if the Riot API can send the object/data), it is returned. If the source does not supply the object, the next data source in the pipeline is queried. If no data source can provide an object for the query, a datapipelines.NotFoundError
is thrown.
After an object is returned by a data source, the object gets passed back down the pipeline. Any data sinks along the way store the object that was returned by the data source. In this way, the cache (which should be at the front of the data pipeline) will store any object that a database or the Riot API returned.
A data pipeline containing an in-memory cache and the Riot API is created by default. The pipeline can be accessed via settings.pipeline
, although users should rarely if ever touch this object after it has been instantiated.
See Data Pipeline for more details.
Searchable Containers¶
Most lists, dictionaries, and sets (all of which are containers) can be searched by most values that make sense. For example, the below line of code finds the first game in which Teemo
was played in the match history of the specified summoner (note that all participants in the match are searched, not just the specific summoner for whom the match history was pulled).
a_teemo_game = Summoner(name="Dabblegamer", region="NA").match_history["Teemo"]
You can also search using objects rather than strings:
all_champions = Champions(region="NA")
teemo = all_champions["Teemo"]
a_teemo_game = Summoner(name="Dabblegamer", region="NA").match_history[teemo]
All matches in a summoner’s match history where Teemo
was in the game can be found by using .search
rather than the [...]
syntax:
# We will truncate the summoner's match history so we don't pull thousands of matches
match_history = Summoner(name="Dabblegamer", region="NA").match_history(begin_time=Patch.from_str("9.1", region="NA").start)
all_teemo_games = match_history.search("Teemo")
You can also index on items in a match. For example:
...match_history["Sightstone"]
will find a game in the summoner’s match history where someone ended the game with a Sightstone (or Ruby Sightstone) in their inventory.
Below is a final (very convenient) snippit that allows you to get your participant in a match:
me = Summoner(name="Kalturi", region="NA")
match = me.match_history[0]
champion_played = match.participants[me].champion
Searchable containers are extremely powerful and are one of the reasons why writing code using Cass is both fun and intuitive.
Match Histories Work Slightly Differently¶
The match history of a summoner is handled slightly differently than most objects in Cass. Most importantly, it is not Cached or stored in databases we create. This is largely because the logic for doing so is non-trivial, and we haven’t implemented it yet – although we hope to. Therefore match histories are requested from the Riot API every time the method is called. You are encouraged to cache the results yourself if you wish.
Match histories are also lazily loaded.
Data Pipeline¶
The data pipeline is a fundamental piece of Cass. It controls the flow of data into and out of an in-memory cache, your databases, the Riot API, and any other data sources/sinks you provide.
The data pipeline consists of a list of DataSource
s and DataSink
s. A DataSource
is any entity that provides data (for example, the Riot API and databases are both data sources). A DataSink
is any entity that stores data (databases are also data sinks). Any entity that is a data sink will almost certainly be a data source as well. We refer to an entity that is both a data source and data sink as a data store.
The data sources and sinks are ordered in the data pipeline, and their order determines the order in which data is requested. Generally speaking, slower data stores / sinks should go towards the end of the pipeline.
For example, if your data pipeline consists of a cache, a database, and the Riot API (in that order), when you ask for a Champion
Cassiopeia will first look in the cache, then in your database, then in the Riot API. If the data is found in the cache, it will be returned and the database and Riot API will not be queried. Similarly, if the data is found in the database, the Riot API will not be queried.
After data is found in a data source, the data propagates back down the data pipeline from whence it came. Any data sink encountered along the way will store that data. So, continuing the above example, if you asked for a Champion
and it was provided by the Riot API, the champion data would be stored in your database, then stored in the cache. A data sink will only store data that it “accepts”. Cass’s built-in data sinks accept all of Cass’s data types.
Each data sink has expiration periods defined for each type of data it accepts. When data is put into a data sink, a clock starts ticking (metaphorically, programmatically this is handled differently). When that clock finishes, the data is expelled from the data sink. Static data should have an infinite expiration period (because it is stored per-version, and the static data for a given version never changes). Other types like CurrentMatch
might have very short expiration periods. Each data sink defines its own default expiration periods, which are documented under the specific data sinks below.
A few notes: 1) Users can force all expired objects in data sinks to be removed using settings.pipeline.expire()
. 2) Individual data sinks handle their own expirations, so if you write a database, you must decide how to handle expirations for data in your database.
Below is an example (which uses more datastores than Cass uses by default):
{
"pipeline": {
"Cache": {},
"SimpleKVDiskStore": {
"package": "cassiopeia_diskstore"
},
"DDragon": {},
"RiotAPI": {
"api_key": "RIOT_API_KEY"
},
"ChampionGG": {
"package": "cassiopeia_championgg",
"api_key": "CHAMPIONGG_KEY" # See api.champion.gg
}
}
In brief, this means that the sequence for looking for data will be: 1) Look in the cache, 2) look in our disk-based database, 3) if it’s static data, get it from data dragon, 4) pull the data from the Riot API, 5) pull the data from ChampionGG.
Defining Components in your Settings¶
The components of the data pipeline are defined explicitly below, and you can choose which you want to use by setting the "pipelines"
attribute in your settings. By default, Cass uses the in-memory cache, data dragon, and the Riot API.
Each component has it’s own set of parameters, also described below.
Settings has an example data pipeline you can use in your settings if you want to modify the defaults.
Components¶
In-Memory Cache¶
The in-memory cache, simply called the cache, is a data store and provides fast read / write storage of data. It is used by including Cache
in the data pipeline settings. If you are constantly creating the same data over and over, the cache is extremely useful. However, if you only using pulling a given piece of data once, it is likely unnecessary.
The cache should be the first element in your pipeline.
It takes one optional parameter (called expirations
), which is a mapping of expiration times (in seconds or datetime.timedelta
if set programmatically) for each data type stored in the cache. Valid type names and their defaults are below (a value of -1
means “do not expire” and 0
means “do not store in the data sink):
ChampionRotationData: datetime.timedelta(hours=6),
Realms: datetime.timedelta(hours=6),
Versions: datetime.timedelta(hours=6),
Champion: datetime.timedelta(days=20),
Rune: datetime.timedelta(days=20),
Item: datetime.timedelta(days=20),
SummonerSpell: datetime.timedelta(days=20),
Map: datetime.timedelta(days=20),
ProfileIcon: datetime.timedelta(days=20),
Locales: datetime.timedelta(days=20),
LanguageStrings: datetime.timedelta(days=20),
SummonerSpells: datetime.timedelta(days=20),
Items: datetime.timedelta(days=20),
Champions: datetime.timedelta(days=20),
Runes: datetime.timedelta(days=20),
Maps: datetime.timedelta(days=20),
ProfileIcons: datetime.timedelta(days=20),
ChampionMastery: datetime.timedelta(days=7),
ChampionMasteries: datetime.timedelta(days=7),
LeagueSummonerEntries: datetime.timedelta(hours=6),
League: datetime.timedelta(hours=6),
ChallengerLeague: datetime.timedelta(hours=6),
MasterLeague: datetime.timedelta(hours=6),
Match: datetime.timedelta(days=3),
Timeline: datetime.timedelta(days=1),
Summoner: datetime.timedelta(days=1),
ShardStatus: datetime.timedelta(hours=1),
CurrentMatch: datetime.timedelta(hours=0.5),
FeaturedMatches: datetime.timedelta(hours=0.5)
TODO: The cache currently does not automatically expire its data, so it’s possible to run out of memory. To prevent this, users can trigger an expiration of all data or all data of one type by using the method settings.pipeline.expire
. We will fix this so that the cache does automatically expire it’s data, but we haven’t gotten to it yet. Using the expire
method is a temporary workaround.
Data Dragon¶
Data Dragon is a data source and provides all of Cass’s static data. This is largely due to the static data rate limits enforced by the Riot API. If you are testing your app and running it repeatedly without a database, you will need to continuously request the static data and will quickly hit the Riot API’s rate limits. Data Dragon provides exactly the same data without some of the niceties that the Riot API provides.
Data Dragon should therefore come before the Riot API in your pipeline, but likely after your databases.
It takes no parameters (i.e. {}
).
Riot API¶
Hopefully you already know what this is. It’s where you’re planning on getting your data, and it’s a data source. It should come after your data bases, and will likely always be the last thing in your data pipeline.
This component can have complicated settings, so see Settings for its parameters.
Kernel¶
Cassiopeia can query a proxy server that mirrors Riot API endpoints. An example of such server is Kernel.
To configure the address and ports of the proxy, use the following configuration within your pipeline:
{
"pipeline": {
...,
"Kernel": {
"server_url": "http://localhost",
"port": 80
}
...
}
}
Simple Disk Database¶
This is a simple filesystem database, and is therefore both a data source and data sink. It is not provided by Cass by default, and needs to be installed separately. See Plugins for more information.
SQLAlchemy Database Support¶
This is a database system that supports all databases that SQLAlchemy supports. It is not provided by Cass by default, and needs to be installed separately. See Plugins for more information.
ChampionGG¶
The ChampionGG plugin has its own data source if it is included. See Plugins.
Unloaded Ghost Store¶
As a user, it’s very likely that you don’t need to worry about what this store does. Cass automatically puts this store in your datapipeline.
The UnloadedGhostStore
provides unloaded ghost objects to the rest of Cass when a new ghost object is created. This allows us to have a single location where all top-level objects are created, which alleviates some complicated issues that crop up when caching core objects and using ghost loading. In general, it should always be in your pipeline.
If you wish to override how Cass inserts it into your pipeline, you can include it in your pipeline and Cass won’t insert it automatically. Normally, it should go immediately after the cache, and if you are not using a cache, it should be the first element in the data pipeline.
Plugins¶
Plugins monkeypatch Cass to provide modified or additional functionality. They are listed below.
The plugins for Cass are stored in two different repositories: cassiopeia-plugins and cassiopeia-datastores. cassiopeia-plugins
contains functionality that modify the behavior of Cass’s objects, while cassiopeia-datastores
provides additional datastores (such as databases). Both of these are called “plugins” in this documentation.
Plugins can be added to Cass by downloading the appropriate plugin and putting it on your PYTHONPATH
environment variable. Then, in your settings file, you specify the name of the module for that plugin (using the package
keyword) as if you were directly importing it into your project. The name of the package specifies the data store that that will be loaded from that package and put on the pipeline.
ChampionGG¶
Install by running pip install cassiopeia-championgg
.
The ChampionGG plugin pulls data from the champion.gg api . This data is accessible via the Champion.championgg
attribute.
To enable this plugin, add the following to your settings’ data pipeline:
"pipeline": {
...,
"ChampionGG": {
"package": "cassiopeia_championgg",
"api_key": "CHAMPIONGG_KEY"
},
...
}
where "CHAMPIONGG_KEY"
is your champion.gg API key or an environment variable that contains it.
Simple KV Disk Store¶
Install by running pip install cassiopeia-diskstore
.
This plugin provides a disk-database. It is especially useful for staticdata, which never changes. It works for all data types except MatchHistory
.
To enable this plugin, add the following to your settings’ data pipeline between the Cache
and DDragon
stores:
"pipeline": {
...,
"SimpleKVDiskStore": {
"package": "cassiopeia_diskstore",
"path": "/absolute/path/to/store/data/"
},
...
}
The "path"
parameter specifies a directory path where the data will be stored. There is also another optional "expirations"
parameter that is left out of the above example for clarity. The "expirations"
parameter is a mapping of type names to expiration periods analogous to those for the cache. The allowed type names and default values are below (a value of -1
means “do not expire” and 0
means “do not store in the data sink):
RealmDto: datetime.timedelta(hours=6),
VersionListDto: datetime.timedelta(hours=6),
ChampionDto: -1,
ChampionListDto: -1,
RuneDto: -1,
RuneListDto: -1,
ItemDto: -1,
ItemListDto: -1,
SummonerSpellDto: -1,
SummonerSpellListDto: -1,
MapDto: -1,
MapListDto: -1,
ProfileIconDetailsDto: -1,
ProfileIconDataDto: -1,
LanguagesDto: -1,
LanguageStringsDto: -1,
ChampionRotationDto: datetime.timedelta(days=1),
ChampionMasteryDto: datetime.timedelta(days=7),
ChampionMasteryListDto: datetime.timedelta(days=7),
ShardStatusDto: datetime.timedelta(hours=1),
Some objects share the same expiration time: FeaturedGamesDto
shares expiration of CurrentGameInfoDto
, ChallengerLeagueListDto
and MasterLeagueListDto
share expiration of LeagueListDto
, ChampionMasteryListDto
shares expiration of ChampionMasteryDto
, and ChampionListDto
shares expiration of ChampionDto
. Only the latter in each category need to be set.
This store only supports the above types (for now).
Contributing¶
Contributions are welcome! If you have idea or opinions on how things can be improved, don’t hesitate to let us know by posting an issue on GitHub or @ing us on the Meraki or Riot API Discord channel. And we always want to hear from our users, even (especially) if it’s just letting us know how you are using Cass.
As a user you get to ignore the details and just use the features of Cass. But as a developer you get to dive into the nitty-gritty and pick apart the implementation that makes everything work. If you don’t want to dive too deep, you can likely contribute even without knowing all the details. You can read more about how Cass works here, and you can find opportunities to help by looking at our issues that are tagged with help-wanted
as well as looking at the list below.
If you have an idea but aren’t sure about it, feel free to @ us on Discord and we can chat.
Things we need help with!¶
We current don’t support the tournament API but need to.
Very few methods / properties have doc strings. While not glorious, it is an incredibly helpful thing to do and you will quickly learning all the pieces of Cass.
In the previous version of Cass, we used regex to pull item stats from tooltips, because the static data is missing a significant number of stats. The old code can be found here and needs to be ported to this version of Cass.
We want to support Redis and Mongo databases in addition to those we already support. To do so, new datasources should be added (along side the Riot API and the in-memory cache) to support these databases. This functionality should be added to our cassiopeia-datastores repository.
We have some very basic tests in place, but a thorough testing of all attributes of all objects would be extremely helpful.
Some data from the champion.gg api is available through Cass (via the
Champion
object). The remaining data should be added as well. You can find the relevant code in theplugins/championgg
directory.Implement better logging.