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

• 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

class cassiopeia._configuration.settings.Settings(settings)

Bases: object

clear_sinks(type: Optional[Type[T]] = None)

expire_sinks(type: Optional[Type[T]] = None)

pipeline

plugins

set_riot_api_key(key)

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)

Bases: Enum

An enumeration.

americas = 'AMERICAS'

asia = 'ASIA'

europe = 'EUROPE'

sea = 'SEA'

class cassiopeia.data.Division(value)

Bases: Enum

An enumeration.

four = 'IV'

one = 'I'

three = 'III'

two = 'II'

class cassiopeia.data.GameMode(value)

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)

Bases: Enum

An enumeration.

custom = 'CUSTOM_GAME'

matched = 'MATCHED_GAME'

tutorial = 'TUTORIAL_GAME'

class cassiopeia.data.Key(value)

Bases: Enum

An enumeration.

E = 'E'

Q = 'Q'

R = 'R'

W = 'W'

class cassiopeia.data.Lane(value)

Bases: Enum

An enumeration.

bot_lane = 'BOT_LANE'

from_match_naming_scheme()

jungle = 'JUNGLE'

mid_lane = 'MID_LANE'

top_lane = 'TOP_LANE'

utility = 'UTILITY'

class cassiopeia.data.MasteryTree(value)

Bases: Enum

An enumeration.

cunning = 'Cunning'

ferocity = 'Ferocity'

resolve = 'Resolve'

class cassiopeia.data.MatchType(value)

Bases: Enum

An enumeration.

normal = 'normal'

ranked = 'ranked'

tourney = 'tourney'

tutorial = 'tutorial'

class cassiopeia.data.Platform(value)

Bases: Enum

An enumeration.

brazil = 'BR1'

continent

default_locale

europe_north_east = 'EUN1'

europe_west = 'EUW1'

static from_region(region)

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)

Bases: Enum

An enumeration.

apex = 'APEX'

bottom = 'BOTTOM'

from_league_naming_scheme()

jungle = 'JUNGLE'

middle = 'MIDDLE'

none = 'NONE'

top = 'TOP'

utility = 'UTILITY'

class cassiopeia.data.Queue(value)

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

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)

Bases: object

class cassiopeia.data.Region(value)

Bases: Enum

An enumeration.

brazil = 'BR'

continent

default_locale

europe_north_east = 'EUNE'

europe_west = 'EUW'

static from_platform(platform)

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)

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)

Bases: Enum

An enumeration.

duo = 'DUO'

duo_carry = 'DUO_CARRY'

duo_support = 'DUO_SUPPORT'

from_match_naming_scheme()

none = 'NONE'

solo = 'SOLO'

class cassiopeia.data.Side(value)

Bases: Enum

An enumeration.

blue = 100

red = 200

class cassiopeia.data.SummonersRiftArea(value)

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

get_lane() → Lane

get_side() → Side

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)

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)

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)

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)

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

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)

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)

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)

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)

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)

Bases: CassiopeiaObject

Searchable by [‘str’, ‘Item’, ‘GameMode’]

classmethod from_data(data: CoreData, region: Region)

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)

Bases: CassiopeiaObject

Searchable by [‘str’, ‘Item’]

classmethod from_data(data: CoreData, region: Region)

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)

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)

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)

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)

Bases: CassiopeiaLazyList

class cassiopeia_championgg.core.ChampionGGMatchup(*args, **kwargs)

Bases: CassiopeiaGhost

Searchable by [‘str’]

elo

enemy

me

nmatches

patch

region

winrate

class cassiopeia_championgg.core.ChampionGGMatchupStats(data, id)

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)

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)

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)

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)

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)

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)

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)

Bases: CassiopeiaGhost

Searchable by [‘str’, ‘Queue’, ‘Tier’]

entries

id

name

platform

queue

region

tier

class cassiopeia.core.ChallengerLeague(*args, **kwargs)

Bases: League

entries

id

name

platform

queue

region

tier

class cassiopeia.core.MasterLeague(*args, **kwargs)

Bases: CassiopeiaGhost

entries

id

name

platform

queue

region

tier

class cassiopeia.core.league.LeagueSummonerEntries(*args, **kwargs)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

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)

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

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

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)

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)

game_type

id

is_remake

kills_heatmap()

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)

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)

inhibitor_kills

participants

rift_herald_kills

side

tower_kills

win

class cassiopeia.core.match.Participant(**kwargs)

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)

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)

Bases: CassiopeiaObject

Searchable by [‘str’, ‘Item’]

assists

baron_kills

bounty_level

champion_experience

champion_transform

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)

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

Bases: object

champion_assists

champion_deaths

champion_kills

events

frames

classmethod from_data(match: Match)

class cassiopeia.core.match.Timeline(*args, **kwargs)

Bases: CassiopeiaGhost

continent

first_tower_fallen

frame_interval

frames

id

platform

region

class cassiopeia.core.match.Frame(**kwargs)

Bases: CassiopeiaObject

events

participant_frames

timestamp

class cassiopeia.core.match.ParticipantFrame(**kwargs)

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)

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)

Bases: CassiopeiaObject

location

x

y

class cassiopeia.core.match.CumulativeTimeline(id: int, participant_timeline: ParticipantTimeline)

Bases: object

class cassiopeia.core.match.ParticipantState(id: int, time: timedelta, participant_timeline: ParticipantTimeline)

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

Bases: object

end

classmethod from_date(date: Arrow, region: Union[Region, str]) → Patch

classmethod from_str(string: str, region: Union[Region, str]) → Patch

classmethod latest(region: Optional[Union[Region, str]] = None) → Patch

major

majorminor

minor

name

region

revision

start

Profile Icons

cassiopeia.Summoner.profile_icon

cassiopeia.get_profile_icons() → ProfileIcons

class cassiopeia.ProfileIcons(*args, **kwargs)

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)

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)

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)

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)

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)

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

cassiopeia.get_featured_matches() → FeaturedMatches

class cassiopeia.FeaturedMatches(*args, **kwargs)

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)

Bases: CassiopeiaGhost

Searchable by []

blue_team

creation

duration

exists

classmethod from_data(data: CurrentGameInfoData, summoner: Union[Summoner, str])

id

map

mode

observer_key

participants

platform

queue

red_team

region

teams

type

class cassiopeia.core.spectator.Team(**kwargs)

Bases: CassiopeiaObject

Searchable by []

bans

classmethod from_data(data: CoreData, match: CurrentMatch)

participants

side

class cassiopeia.core.spectator.Participant(**kwargs)

Bases: CassiopeiaObject

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

champion

classmethod from_data(data: CoreData, match: CurrentMatch)

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)

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)

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)

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)

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

cassiopeia.get_versions() → List[str]

cassiopeia.get_version(region: Optional[Union[Region, str]] = None) → Union[None, str]

class cassiopeia.Versions(*args, **kwargs)

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

• Settings

• Data and Enums

• Champions

• Champion Masteries

• Items

• Language Strings

• Leagues

• Locales

• Maps

• Matches

• Patch

• Profile Icons

• Realms

• Runes

• Status

• Spectator

• Summoners

• Summoner Spells

• Versions

Index and Search

• Index