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:

  1. An interface for pulling data from the Riot API.

  2. A type system of classes for holding and working with the data pulled from Riot.

  3. 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).

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).

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
class cassiopeia._configuration.settings.Settings(settings)[source]

Bases: object

clear_sinks(type: Optional[Type[T]] = None)[source]
expire_sinks(type: Optional[Type[T]] = None)[source]
pipeline
plugins
set_riot_api_key(key)[source]
version_from_match
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'
from_match_naming_scheme()[source]
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'
static from_region(region)[source]
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'
from_league_naming_scheme()[source]
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'
from_id()[source]
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.Rank(tier: Tier, division: Division)[source]

Bases: object

class cassiopeia.data.Region(value)[source]

Bases: Enum

An enumeration.

brazil = 'BR'
continent
default_locale
europe_north_east = 'EUNE'
europe_west = 'EUW'
static from_platform(platform)[source]
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'
from_match_naming_scheme()[source]
none = 'NONE'
solo = 'SOLO'
class cassiopeia.data.Side(value)[source]

Bases: Enum

An enumeration.

blue = 100
red = 200
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]
get_lane() Lane[source]
get_side() Side[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'
class cassiopeia.data.Tower(value)[source]

Bases: Enum

An enumeration.

BASE = 'BASE_TURRET'
INNER = 'INNER_TURRET'
NEXUS = 'NEXUS_TURRET'
OUTER = 'OUTER_TURRET'
UNDEFINED = 'UNDEFINED_TURRET'
Champions
cassiopeia.get_champions() Champions
cassiopeia.get_champion(region: Optional[Union[Region, str]] = None) Champion
class cassiopeia.Champions(*args, **kwargs)[source]

Bases: CassiopeiaLazyList

append(item)

Append object to the end of the list.

clear()

Remove all items from list.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **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.

insert(index: int, object)

Insert object before index.

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.

load(load_groups: Optional[Set] = None) Champion[source]
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’]

classmethod from_data(data: CoreData, region: Region)[source]
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’]

classmethod from_data(data: CoreData, region: Region)[source]
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.

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
cassiopeia.get_champion_masteries(region: Optional[Union[Region, str]] = None) ChampionMasteries
class cassiopeia.ChampionMasteries(*args, **kwargs)[source]

Bases: CassiopeiaLazyList

append(item)

Append object to the end of the list.

clear()

Remove all items from list.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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
cassiopeia.get_items() 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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **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.

insert(index: int, object)

Insert object before index.

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
class cassiopeia.LanguageStrings(*args, **kwargs)[source]

Bases: CassiopeiaGhost

Searchable by []

locale
platform
region
strings
type
version
Leagues
cassiopeia.Summoner.leagues
cassiopeia.get_challenger_league(region: Optional[Union[Region, str]] = None) ChallengerLeague
cassiopeia.get_master_league(region: Optional[Union[Region, str]] = None) MasterLeague
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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
fives
flex
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
division
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
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.

insert(index: int, object)

Insert object before index.

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
cassiopeia.get_locales() List[str]
class cassiopeia.Locales(*args, **kwargs)[source]

Bases: CassiopeiaLazyList

append(item)

Append object to the end of the list.

clear()

Remove all items from list.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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
cassiopeia.get_maps() 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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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.Map(*args, **kwargs)[source]

Bases: CassiopeiaGhost

Searchable by [‘str’, ‘int’]

id

The map’s ID.

image
locale

The locale for this map.

name
platform
region
sprite
unpurchasable_items
version

The version for this map.

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)
cassiopeia.get_match(region: Optional[Union[Region, str]] = None) Match
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.

contains(item: Any) bool
continent() Continent[source]
copy()

Return a shallow copy of the list.

count

Return number of occurrences of value.

delete(item: Any) None
end_time
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)[source]
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

match_type() MatchType[source]
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() Queue[source]
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
classmethod from_match_reference(ref: MatchReferenceData)[source]
game_type
id
is_remake
kills_heatmap()[source]
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
classmethod from_data(data: CoreData, match: Match)[source]
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
classmethod from_data(data: CoreData, match: Match)[source]
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
champion_transform[source]
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
classmethod from_data(match: Match)[source]
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.Position(**kwargs)[source]

Bases: CassiopeiaObject

location
x
y
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
class cassiopeia.Patch(region: Union[str, Region], name: str, start: Union[Arrow, float], end: Optional[Union[Arrow, float]])[source]

Bases: object

end
classmethod from_date(date: Arrow, region: Union[Region, str]) Patch[source]
classmethod from_str(string: str, region: Union[Region, str]) Patch[source]
classmethod latest(region: Optional[Union[Region, str]] = None) Patch[source]
major
majorminor
minor
name
region
revision
start
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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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
cassiopeia.get_realms() 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
cassiopeia.get_runes() 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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
domination
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **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.

insert(index: int, object)

Insert object before index.

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
class cassiopeia.ShardStatus(*args, **kwargs)[source]

Bases: CassiopeiaGhost

Searchable by []

hostname
locales
name
platform
region
services
slug
Spectator
cassiopeia.Summoner.current_match
cassiopeia.get_current_match(region: Optional[Union[Region, str]] = None) CurrentMatch
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
contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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
classmethod from_data(data: CurrentGameInfoData, summoner: Union[Summoner, str])[source]
id
map
mode
observer_key
participants
platform
queue
red_team
region
teams
type
class cassiopeia.core.spectator.Team(**kwargs)[source]

Bases: CassiopeiaObject

Searchable by []

bans
classmethod from_data(data: CoreData, match: CurrentMatch)[source]
participants
side
class cassiopeia.core.spectator.Participant(**kwargs)[source]

Bases: CassiopeiaObject

Searchable by [‘str’, ‘Summoner’, ‘Champion’]

champion
classmethod from_data(data: CoreData, match: CurrentMatch)[source]
is_bot
runes
side
summoner
summoner_spell_d
summoner_spell_f
team
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.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **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.

insert(index: int, object)

Insert object before index.

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.

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
cassiopeia.get_versions() List[str]
cassiopeia.get_version(region: Optional[Union[Region, str]] = None) Union[None, str]
class cassiopeia.Versions(*args, **kwargs)[source]

Bases: CassiopeiaLazyList

append(item)

Append object to the end of the list.

clear()

Remove all items from list.

contains(item: Any) bool
copy()

Return a shallow copy of the list.

count(object)

Return number of occurrences of value.

delete(item: Any) None
enumerate(item: Any, reverse: bool = False) Generator[Tuple[int, Any], None, None]
extend(iterable)

Extend list by appending elements from the iterable.

filter(function)
find(item: Any, reverse: bool = False) Any
classmethod from_data(*args, **kwargs)
classmethod from_generator(generator: Generator, **kwargs)
index(object, start: int = 0, stop: int = 9223372036854775807)

Return first index of value.

Raises ValueError if the value is not present.

insert(index: int, object)

Insert object before index.

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 DataSources and DataSinks. 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 the plugins/championgg directory.

  • Implement better logging.

Top Level APIs