spells-mtg 0.1.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

spells/__init__.py

@@ -1,5 +1,5 @@
 from spells import columns
 from spells import enums
-from spells.draft_data import summon
+from spells.draft_data import summon, card_df
 
-__all__ = ["summon", "enums", "columns"]
+__all__ = ["summon", "card_df", "enums", "columns"]

spells/cards.py

@@ -21,6 +21,8 @@ class CardAttr(StrEnum):
     TOUGHNESS = ColName.TOUGHNESS
     IS_BONUS_SHEET = ColName.IS_BONUS_SHEET
     IS_DFC = ColName.IS_DFC
+    ORACLE_TEXT = ColName.ORACLE_TEXT
+    CARD_JSON = ColName.CARD_JSON
 
 
 MTG_JSON_TEMPLATE = "https://mtgjson.com/api/v5/{set_code}.json"
@@ -66,6 +68,10 @@ def _extract_value(set_code: str, name: str, card_dict: dict, field: CardAttr):
             return card_dict.get("setCode", set_code) != set_code
         case CardAttr.IS_DFC:
             return len(card_dict.get("otherFaceIds", [])) > 0
+        case CardAttr.ORACLE_TEXT:
+            return card_dict.get("text", "")
+        case CardAttr.CARD_JSON:
+            return card_dict.get("json", "")
 
 
 def card_df(draft_set_code: str, names: list[str]) -> pl.DataFrame:
@@ -81,6 +87,9 @@ def card_df(draft_set_code: str, names: list[str]) -> pl.DataFrame:
             card_data = draft_set_json["data"]["cards"]
 
         card_data.reverse()  # prefer front face for split cards
+        for item in card_data:
+            item["json"] = json.dumps(item)
+
         face_name_cards = [item for item in card_data if "faceName" in item]
         card_data_map.update({item["faceName"]: item for item in face_name_cards})
         card_data_map.update({item["name"]: item for item in card_data})

spells/columns.py

@@ -12,7 +12,7 @@ class ColumnSpec:
     col_type: ColType
     expr: pl.Expr | None = None
     exprMap: Callable[[str], pl.Expr] | None = None
-    views: tuple[View, ...] = ()
+    views: list[View] | None = None
     dependencies: list[str] | None = None
     version: str | None = (
         None  # only needed for user-defined functions with python functions in expr
@@ -49,76 +49,70 @@ _column_specs = [
     ColumnSpec(
         name=ColName.NAME,
         col_type=ColType.GROUP_BY,
-        views=(),
         # handled by internals, derived from both 'pick' and "name mapped" columns
     ),
     ColumnSpec(
         name=ColName.EXPANSION,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
+        views=[View.GAME, View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.EVENT_TYPE,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
+        views=[View.GAME, View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.DRAFT_ID,
-        views=(View.GAME, View.DRAFT),
+        views=[View.GAME, View.DRAFT],
         col_type=ColType.FILTER_ONLY,
     ),
     ColumnSpec(
         name=ColName.DRAFT_TIME,
         col_type=ColType.FILTER_ONLY,
-        views=(View.GAME, View.DRAFT),
+        views=[View.GAME, View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.DRAFT_DATE,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
         expr=pl.col("draft_time").str.to_datetime("%Y-%m-%d %H:%M:%S").dt.date(),
         dependencies=[ColName.DRAFT_TIME],
     ),
     ColumnSpec(
         name=ColName.DRAFT_DAY_OF_WEEK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
         expr=pl.col("draft_time").str.to_datetime("%Y-%m-%d %H:%M:%S").dt.weekday(),
         dependencies=[ColName.DRAFT_TIME],
     ),
     ColumnSpec(
         name=ColName.DRAFT_HOUR,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
         expr=pl.col("draft_time").str.to_datetime("%Y-%m-%d %H:%M:%S").dt.hour(),
         dependencies=[ColName.DRAFT_TIME],
     ),
     ColumnSpec(
         name=ColName.DRAFT_WEEK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
         expr=pl.col("draft_time").str.to_datetime("%Y-%m-%d %H:%M:%S").dt.week(),
         dependencies=[ColName.DRAFT_TIME],
     ),
     ColumnSpec(
         name=ColName.RANK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME, View.DRAFT),
+        views=[View.GAME, View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.USER_N_GAMES_BUCKET,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT, View.GAME),
+        views=[View.DRAFT, View.GAME],
     ),
     ColumnSpec(
         name=ColName.USER_GAME_WIN_RATE_BUCKET,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT, View.GAME),
+        views=[View.DRAFT, View.GAME],
     ),
     ColumnSpec(
         name=ColName.PLAYER_COHORT,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT, View.GAME),
         expr=pl.when(pl.col("user_n_games_bucket") < 100)
         .then(pl.lit("Other"))
         .otherwise(
@@ -135,45 +129,41 @@ _column_specs = [
     ColumnSpec(
         name=ColName.EVENT_MATCH_WINS,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.EVENT_MATCH_WINS_SUM,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
         expr=pl.col(ColName.EVENT_MATCH_WINS),
         dependencies=[ColName.EVENT_MATCH_WINS],
     ),
     ColumnSpec(
         name=ColName.EVENT_MATCH_LOSSES,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.EVENT_MATCH_LOSSES_SUM,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
         expr=pl.col(ColName.EVENT_MATCH_LOSSES),
         dependencies=[ColName.EVENT_MATCH_LOSSES],
     ),
     ColumnSpec(
         name=ColName.EVENT_MATCHES,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
         expr=pl.col("event_match_wins") + pl.col("event_match_losses"),
         dependencies=[ColName.EVENT_MATCH_WINS, ColName.EVENT_MATCH_LOSSES],
     ),
     ColumnSpec(
         name=ColName.EVENT_MATCHES_SUM,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
         expr=pl.col(ColName.EVENT_MATCHES),
         dependencies=[ColName.EVENT_MATCHES],
     ),
     ColumnSpec(
         name=ColName.IS_TROPHY,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
         expr=pl.when(pl.col("event_type") == "Traditional")
         .then(pl.col("event_match_wins") == 3)
         .otherwise(pl.col("event_match_wins") == 7),
@@ -182,45 +172,40 @@ _column_specs = [
     ColumnSpec(
         name=ColName.IS_TROPHY_SUM,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
         expr=pl.col(ColName.IS_TROPHY),
         dependencies=[ColName.IS_TROPHY],
     ),
     ColumnSpec(
         name=ColName.PACK_NUMBER,
         col_type=ColType.FILTER_ONLY,  # use pack_num
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.PACK_NUM,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
         expr=pl.col("pack_number") + 1,
         dependencies=[ColName.PACK_NUMBER],
     ),
     ColumnSpec(
         name=ColName.PICK_NUMBER,
         col_type=ColType.FILTER_ONLY,  # use pick_num
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.PICK_NUM,
         col_type=ColType.GROUP_BY,
-        views=(View.DRAFT,),
         expr=pl.col("pick_number") + 1,
         dependencies=[ColName.PICK_NUMBER],
     ),
     ColumnSpec(
         name=ColName.TAKEN_AT,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
         expr=pl.col(ColName.PICK_NUM),
         dependencies=[ColName.PICK_NUM],
     ),
     ColumnSpec(
         name=ColName.NUM_TAKEN,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
         expr=pl.when(pl.col(ColName.PICK).is_not_null())
         .then(1)
         .otherwise(0),  # a literal returns one row under select alone
@@ -229,27 +214,26 @@ _column_specs = [
     ColumnSpec(
         name=ColName.PICK,
         col_type=ColType.FILTER_ONLY,  # aggregated as "name"
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.PICK_MAINDECK_RATE,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.PICK_SIDEBOARD_IN_RATE,
         col_type=ColType.PICK_SUM,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.PACK_CARD,
         col_type=ColType.NAME_SUM,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.LAST_SEEN,
         col_type=ColType.NAME_SUM,
-        views=(View.DRAFT,),
         exprMap=lambda name: pl.col(f"pack_card_{name}")
         * pl.min_horizontal("pick_num", 8),
         dependencies=[ColName.PACK_CARD, ColName.PICK_NUM],
@@ -257,117 +241,107 @@ _column_specs = [
     ColumnSpec(
         name=ColName.NUM_SEEN,
         col_type=ColType.NAME_SUM,
-        views=(View.DRAFT,),
         exprMap=lambda name: pl.col(f"pack_card_{name}") * (pl.col("pick_num") <= 8),
         dependencies=[ColName.PACK_CARD, ColName.PICK_NUM],
     ),
     ColumnSpec(
         name=ColName.POOL,
         col_type=ColType.NAME_SUM,
-        views=(View.DRAFT,),
+        views=[View.DRAFT],
     ),
     ColumnSpec(
         name=ColName.GAME_TIME,
         col_type=ColType.FILTER_ONLY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.GAME_DATE,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col("game_time").str.to_datetime("%Y-%m-%d %H-%M-%S").dt.date(),
         dependencies=[ColName.GAME_TIME],
     ),
     ColumnSpec(
         name=ColName.GAME_DAY_OF_WEEK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col("game_time").str.to_datetime("%Y-%m-%d %H-%M-%S").dt.weekday(),
         dependencies=[ColName.GAME_TIME],
     ),
     ColumnSpec(
         name=ColName.GAME_HOUR,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col("game_time").str.to_datetime("%Y-%m-%d %H-%M-%S").dt.hour(),
         dependencies=[ColName.GAME_TIME],
     ),
     ColumnSpec(
         name=ColName.GAME_WEEK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col("game_time").str.to_datetime("%Y-%m-%d %H-%M-%S").dt.week(),
         dependencies=[ColName.GAME_TIME],
     ),
     ColumnSpec(
         name=ColName.BUILD_INDEX,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.MATCH_NUMBER,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.GAME_NUMBER,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_GAMES,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.GAME_NUMBER).is_not_null(),
         dependencies=[ColName.GAME_NUMBER],
     ),
     ColumnSpec(
         name=ColName.NUM_MATCHES,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.GAME_NUMBER) == 1,
         dependencies=[ColName.GAME_NUMBER],
     ),
     ColumnSpec(
         name=ColName.NUM_EVENTS,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=(pl.col(ColName.GAME_NUMBER) == 1) & (pl.col(ColName.MATCH_NUMBER) == 1),
         dependencies=[ColName.GAME_NUMBER, ColName.MATCH_NUMBER],
     ),
     ColumnSpec(
         name=ColName.OPP_RANK,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.MAIN_COLORS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_COLORS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col(ColName.MAIN_COLORS).str.len_chars(),
         dependencies=[ColName.MAIN_COLORS],
     ),
     ColumnSpec(
         name=ColName.SPLASH_COLORS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.HAS_SPLASH,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
         expr=pl.col(ColName.SPLASH_COLORS).str.len_chars() > 0,
         dependencies=[ColName.SPLASH_COLORS],
     ),
     ColumnSpec(
         name=ColName.ON_PLAY,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_ON_PLAY,
@@ -378,120 +352,110 @@ _column_specs = [
     ColumnSpec(
         name=ColName.NUM_MULLIGANS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_MULLIGANS_SUM,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.NUM_MULLIGANS),
         dependencies=[ColName.NUM_MULLIGANS],
     ),
     ColumnSpec(
         name=ColName.OPP_NUM_MULLIGANS,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.OPP_NUM_MULLIGANS_SUM,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.OPP_NUM_MULLIGANS),
         dependencies=[ColName.OPP_NUM_MULLIGANS],
     ),
     ColumnSpec(
         name=ColName.OPP_COLORS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_TURNS,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_TURNS_SUM,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.NUM_TURNS),
         dependencies=[ColName.NUM_TURNS],
     ),
     ColumnSpec(
         name=ColName.WON,
         col_type=ColType.GROUP_BY,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.NUM_WON,
         col_type=ColType.GAME_SUM,
-        views=(View.GAME,),
         expr=pl.col(ColName.WON),
         dependencies=[ColName.WON],
     ),
     ColumnSpec(
         name=ColName.OPENING_HAND,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.WON_OPENING_HAND,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(f"opening_hand_{name}") * pl.col(ColName.WON),
         dependencies=[ColName.OPENING_HAND, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.DRAWN,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.WON_DRAWN,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(f"drawn_{name}") * pl.col(ColName.WON),
         dependencies=[ColName.DRAWN, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.TUTORED,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.WON_TUTORED,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(f"tutored_{name}") * pl.col(ColName.WON),
         dependencies=[ColName.TUTORED, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.DECK,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.WON_DECK,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(f"deck_{name}") * pl.col(ColName.WON),
         dependencies=[ColName.DECK, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.SIDEBOARD,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
+        views=[View.GAME],
     ),
     ColumnSpec(
         name=ColName.WON_SIDEBOARD,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(f"sideboard_{name}") * pl.col(ColName.WON),
         dependencies=[ColName.SIDEBOARD, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.NUM_GNS,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.max_horizontal(
             0,
             pl.col(f"deck_{name}")
@@ -509,69 +473,64 @@ _column_specs = [
     ColumnSpec(
         name=ColName.WON_NUM_GNS,
         col_type=ColType.NAME_SUM,
-        views=(View.GAME,),
         exprMap=lambda name: pl.col(ColName.WON) * pl.col(f"num_gns_{name}"),
         dependencies=[ColName.NUM_GNS, ColName.WON],
     ),
     ColumnSpec(
         name=ColName.SET_CODE,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.COLOR,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.RARITY,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.COLOR_IDENTITY,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.CARD_TYPE,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.SUBTYPE,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.MANA_VALUE,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.MANA_COST,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.POWER,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.TOUGHNESS,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.IS_BONUS_SHEET,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
     ),
     ColumnSpec(
         name=ColName.IS_DFC,
         col_type=ColType.CARD_ATTR,
-        views=(View.CARD,),
+    ),
+    ColumnSpec(
+        name=ColName.ORACLE_TEXT,
+        col_type=ColType.CARD_ATTR,
+    ),
+    ColumnSpec(
+        name=ColName.CARD_JSON,
+        col_type=ColType.CARD_ATTR,
     ),
     ColumnSpec(
         name=ColName.PICKED_MATCH_WR,
@@ -594,7 +553,6 @@ _column_specs = [
     ColumnSpec(
         name=ColName.ALSA,
         col_type=ColType.AGG,
-        views=(),
         expr=pl.col(ColName.LAST_SEEN) / pl.col(ColName.NUM_SEEN),
         dependencies=[ColName.LAST_SEEN, ColName.NUM_SEEN],
     ),

spells/draft_data.py

@@ -53,6 +53,23 @@ def _get_names(set_code: str) -> tuple[str, ...]:
 
 
 def _hydrate_col_defs(set_code: str, col_spec_map: dict[str, ColumnSpec]):
+    def get_views(spec: ColumnSpec) -> list[View]:
+        if spec.name == ColName.NAME or spec.col_type == ColType.AGG:
+            return []
+        if spec.col_type == ColType.CARD_ATTR:
+            return [View.CARD]
+        if spec.views is not None:
+            return spec.views
+        assert (
+            spec.dependencies is not None
+        ), f"Col {spec.name} should have dependencies"
+
+        views = []
+        for dep in spec.dependencies:
+            views.extend(get_views(col_spec_map[dep]))
+
+        return list(set(views))
+
     names = _get_names(set_code)
     assert len(names) > 0, "there should be names"
     hydrated = {}
@@ -87,19 +104,21 @@ def _hydrate_col_defs(set_code: str, col_spec_map: dict[str, ColumnSpec]):
                 expr_sig = str(datetime.datetime.now)
 
         dependencies = tuple(spec.dependencies or ())
+        views = get_views(spec)
         signature = str(
             (
                 spec.name,
                 spec.col_type.value,
                 expr_sig,
-                tuple(view.value for view in spec.views),
+                tuple(view.value for view in views),
                 dependencies,
             )
         )
+
         cdef = ColumnDefinition(
             name=spec.name,
             col_type=spec.col_type,
-            views=spec.views,
+            views=tuple(views),
             expr=expr,
             dependencies=dependencies,
             signature=signature,
@@ -246,6 +265,28 @@ def _base_agg_df(
     )
 
 
+def card_df(
+    set_code: str,
+    extensions: list[ColumnSpec] | None = None,
+):
+    col_spec_map = dict(spells.columns.col_spec_map)
+    if extensions is not None:
+        for spec in extensions:
+            col_spec_map[spec.name] = spec
+
+    col_def_map = _hydrate_col_defs(set_code, col_spec_map)
+
+    columns = [ColName.NAME] + [
+        c for c, cdef in col_def_map.items() if cdef.col_type == ColType.CARD_ATTR
+    ]
+    fp = data_file_path(set_code, View.CARD)
+    card_df = pl.read_parquet(fp)
+    select_df = _view_select(
+        card_df, frozenset(columns), col_def_map, is_agg_view=False
+    )
+    return select_df.select(columns)
+
+
 def summon(
     set_code: str,
     columns: list[str] | None = None,

spells/enums.py

@@ -120,6 +120,8 @@ class ColName(StrEnum):
     TOUGHNESS = "toughness"
     IS_BONUS_SHEET = "is_bonus_sheet"
     IS_DFC = "is_dfc"
+    ORACLE_TEXT = "oracle_text"
+    CARD_JSON = "card_json"
     # agg extensions
     PICKED_MATCH_WR = "picked_match_wr"
     TROPHY_RATE = "trophy_rate"

spells/external.py

@@ -268,7 +268,7 @@ def download_data_set(
         mode, "Unzipping and transforming to parquet (this might take a few minutes)..."
     )
     _process_zipped_file(dataset_path, target_path)
-    cache.spells_print(mode, f"File {target_path} written")
+    cache.spells_print(mode, f"Wrote file {target_path}")
     if clear_set_cache:
         cache.clear(set_code)
 

{spells_mtg-0.1.0.dist-info → spells_mtg-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spells-mtg
-Version: 0.1.0
+Version: 0.2.2
 Summary: analaysis of 17Lands.com public datasets
 Author-Email: Joel Barnes <oelarnes@gmail.com>
 License: MIT
@@ -19,16 +19,16 @@ $ spells add DSK
 
 🪄 add ✨ Downloading draft dataset from 17Lands.com
 100% [......................................................................] 250466473 / 250466473
-🪄 add ✨ Unzipping and transforming to parquet...
-🪄 add ✨ File /Users/joel/.local/share/spells/external/DSK/DSK_PremierDraft_draft.parquet written
+🪄 add ✨ Unzipping and transforming to parquet (this might take a few minutes)...
+🪄 add ✨ Wrote file /Users/joel/.local/share/spells/external/DSK/DSK_PremierDraft_draft.parquet
 🪄 clean ✨ No local cache found for set DSK
+🪄 add ✨ Fetching card data from mtgjson.com and writing card parquet file
+🪄 add ✨ Wrote file /Users/joel/.local/share/spells/external/DSK/DSK_card.parquet
 🪄 add ✨ Downloading game dataset from 17Lands.com
 100% [........................................................................] 77145600 / 77145600
-🪄 add ✨ Unzipping and transforming to parquet...
-🪄 add ✨ File /Users/joel/.local/share/spells/external/DSK/DSK_PremierDraft_game.parquet written
+🪄 add ✨ Unzipping and transforming to parquet (this might take a few minutes)...
+🪄 add ✨ Wrote file /Users/joel/.local/share/spells/external/DSK/DSK_PremierDraft_game.parquet
 🪄 clean ✨ No local cache found for set DSK
-🪄 add ✨ Fetching card data from mtgjson.com and writing card parquet file
-🪄 add ✨ Wrote 287 lines to file /Users/joel/.local/share/spells/external/DSK/DSK_card.parquet
 $ ipython
 ```
 
@@ -64,7 +64,7 @@ Wall time: 80.8 ms
 ```
 Coverting to pandas DataFrame is as simple as invoking the chained call `summon(...).to_pandas()`.
 
-Spells is not affiliated with 17Lands. Please review the Usage Guidelines for 17lands data before using Spells, and consider supporting their patreon. Spells is free and open-source; please consider contributing and feel free to make use of the source code under the terms of the MIT license.
+Spells is not affiliated with 17Lands. Please review the [Usage Guidelines](https://www.17lands.com/usage_guidelines) for 17lands data before using Spells, and consider supporting their patreon. Spells is free and open-source; please consider contributing and feel free to make use of the source code under the terms of the MIT license.
 
 ## spells
 
@@ -74,7 +74,7 @@ Spells is not affiliated with 17Lands. Please review the Usage Guidelines for 17
 - Supports calculating the standard aggregations and measures out of the box with no arguments (ALSA, GIH WR, etc)
 - Caches aggregate DataFrames in the local file system automatically for instantaneous reproduction of previous analysis
 - Manages grouping and filtering by built-in and custom columns at the row level
-- Provides 116 explicitly specified, enumerated, documented column definitions
+- Provides 118 explicitly specified, enumerated, documented column definitions
 - Supports "Deck Color Data" aggregations with built-in column definitions.
 - Provides a CLI tool `spells [add|refresh|clean|remove|info] [SET]` to download and manage external files
 - Downloads and manages public datasets from 17Lands
@@ -82,7 +82,8 @@ Spells is not affiliated with 17Lands. Please review the Usage Guidelines for 17
 - Is fully typed, linted, and statically analyzed for support of advanced IDE features
 - Provides optional enums for all base columns and built-in extensions, as well as for custom extension parameters
 - Uses Polars expressions to support second-stage aggregations and beyond like game-weighted z-scores with one call to summon
-- Tested on MacOS, Linux, and Windows
+- Works on MacOS, Linux, and Windows
+- Provides example notebooks to kickstart your exploration
 
 ## summon
 
@@ -133,7 +134,7 @@ Spells is not affiliated with 17Lands. Please review the Usage Guidelines for 17
   - `filter_spec` specifies a row-level filter for the dataset, using an intuitive custom query formulation
     ```python
     >>> from spells.enums import ColName
-    >>> spells.summon('BLB', columns=["game_wr"], group_by=["player_cohort"], filter_spec={'lhs': 'num_mulligans', 'op': '>', 'rhs': 0})
+    >>> spells.summon('BLB', columns=[ColName.GAME_WR], group_by=[ColName.PLAYER_COHORT], filter_spec={'lhs': ColName.NUM_MULLIGANS, 'op': '>', 'rhs': 0})
     shape: (4, 2)
     ┌───────────────┬──────────┐
     │ player_cohort ┆ game_wr  │
@@ -193,6 +194,8 @@ Spells is still in development and could benefit from many new features and impr
 
 If you are new to Python, I recommend using a package manager like poetry, pdm or uv to create a virtual environment and manage your project.
 
+Once Spells is installed, check out the notebooks under [examples](https://github.com/oelarnes/spells/tree/main/examples) for ideas on getting started.
+
 ## Why did you make this? Who is it for?
 
 Earlier this year I developed a card quality metric called [DEq](https://docs.google.com/spreadsheets/d/1n1pfrb5q_2ICYk-vfF3Uwo8t61DJU-5T_DFe0dwk8DY/edit), short for "Estimated Draft Equity", which is designed to estimate the average value of selecting a card in draft relative to a comparable baseline, in order to improve on commonly-used metrics like GIH WR, which has a number of major and minor problems when interpreted as a card quality metric. DEq depends on the daily drops from 17Lands.com and won't be replaced by this static kind of analysis.
@@ -205,7 +208,7 @@ If you're interested in the fruits of my DEq research, or in checking my work, k
 
 ## Performance
 
-Spells provides several features out of the box to optimize performance to the degree possible given its generality.
+Spells provides several features to optimize performance.
 
 ### Parquet Transformation
 
@@ -213,11 +216,11 @@ The most significant optimization used by Spells is the simplest: the csv files
 
 ### Query Optimization
 
-Firstly, it is built on top of Polars, a modern, well-supported DataFrame engine written for performance in Rust that enables declarative query plans and lazy evaluation, allowing for automatic performance optimization in the execution of the query plan. Spells selects only the necessary columns for your analysis using an optimized recursive selection algorithm traversing the dependency tree.
+Spells is built on top of Polars, a modern, well-supported DataFrame engine written for performance in Rust that enables declarative query plans and lazy evaluation, allowing for automatic performance optimization in the execution of the query plan. Spells selects only the necessary columns for your analysis, recursively traversing the dependency tree.
 
 ### Local Caching
 
-Additionally, by default, Spells caches the results of expensive aggregations in the local file system as parquet files, which by default are found under the `data/local` path from the execution directory, which can be configured using the environment variable `SPELLS_PROJECT_DIR`. Query plans which request the same set of first-stage aggregations (sums over base rows) will attempt to locate the aggregate data in the cache before calculating. This guarantees that a repeated call to `summon` returns instantaneously.
+Spells caches the results of expensive aggregations in the local file system as parquet files, which by default are found under the `data/local` path from the execution directory, which can be configured using the environment variable `SPELLS_PROJECT_DIR`. Query plans which request the same set of first-stage aggregations (sums over base rows) will attempt to locate the aggregate data in the cache before calculating. This guarantees that a repeated call to `summon` returns instantaneously.
 
 When refreshing a given set's data files from 17Lands using the provided cli, the cache for that set is automatically cleared. The `spells` CLI gives additional tools for managing the local and external caches.
 
@@ -249,8 +252,8 @@ So that's it, that's what Spells does from a high level. `summon` will hand off
 ## CLI
 
 Spells includes a command-line interface `spells` to manage your external data files and local cache. Spells will download files to an appropriate file location on your system, 
-typically `~/.local/share/spells` on Unix-like platforms and `C:\Users\{Username}\AppData\Local\Spells` on Windows. 
-To use `spells`, make sure Spells in installed in your environment using pip or a package manager, and type `spells help` into your shell, or dive in with `spells add DSK` or your favorite set. If Spells is installed globally using pipx, any local version of Spells will be able to read the managed files.
+typically `~/.local/share/spells` on Unix-like platforms and `C:\Users\{Username}\AppData\Local\Spells` on Windows, or to a location specified by the environment variable `SPELLS_DATA_HOME`.
+To use `spells`, make sure Spells is installed in your environment using pip or a package manager, and type `spells help` into your shell, or dive in with `spells add DSK` or your favorite set. If Spells is installed globally using pipx, any local version of Spells will be able to read the managed files.
 
 ## API
 
@@ -264,6 +267,8 @@ summon(
     group_by: list[str] | None = None,
     filter_spec: dict | None = None,
     extensions: list[str] | None = None,
+    read_cache: bool = True,
+    write_cache: bool = True,
 ) -> polars.DataFrame
 ```
 
@@ -283,13 +288,15 @@ aggregations of non-numeric (or numeric) data types are not supported. If `None`
 
 - extensions: a list of `spells.columns.ColumnSpec` objects, which are appended to the definitions built-in columns described below. A name not in the enum `ColName` can be used in this way if it is the name of a provided extension. Existing names can also be redefined using extensions.
 
+- read_cache/write_cache: Use the local file system to cache and retrieve aggregations to minimize expensive reads of the large datasets. You shouldn't need to touch these arguments unless you are debugging.
+
 ### Enums
 
 ```python
 from spells.enums import ColName, ColType, View
 ```
 
-Recommended to import `ColName` for any usage of `summon`, and to import `ColType` and `View` when defining custom extensions. 
+Recommended to import `ColName` for any usage of `summon`, and to import `ColType` when defining custom extensions. You shouldn't need `VIEW`.
 
 ### ColumnSpec
 
@@ -298,12 +305,12 @@ from spells.columns import ColumnSpec
 
 ColumnSpec(
     name: str,
-    col_type: spells.enums.ColType,
-    views: tuple(spells.enums.View...) = (),
+    col_type: ColType,
     expr: pl.Expr | None = None,
     exprMap: Callable[[str], pl.Expr] | None = None
     dependencies: list[str] | None = None
     version: str | None = None
+    views: list[View] | None = None,
 )
 ```
 
@@ -315,8 +322,6 @@ Used to define extensions in `summon`
 
 - `col_type`: one of the `ColType` enum values, `FILTER_ONLY`, `GROUP_BY`, `PICK_SUM`, `NAME_SUM`, `GAME_SUM`, `CARD_ATTR`, and `AGG`. See documentation for `summon` for usage. All columns except `CARD_ATTR` and `AGG` must be derivable at the individual row level on one or both base views. `CARD_ATTR` must be derivable at the individual row level from the card file. `AGG` can depend on any column present after summing over groups, and can include polars Expression aggregations. Arbitrarily long chains of aggregate dependencies are supported.
 
-- `views`: For a column defined at the row level on a view (see col_types above), the views on which it is supported. All col_types except `AGG` must specify at least one base view. For `CARD_ATTR` columns, `views` must be exactly `(View.CARD,)`.
-
 - `expr`: A polars expression giving the derivation of the column value at the first level where it is defined. For `NAME_SUM` columns the `exprMap` attribute must be used instead. `AGG` columns that depend on `NAME_SUM` columns reference the prefix (`cdef.name`) only, since the unpivot has occured prior to selection.
 
 - `exprMap`: A function of card name that returns the expression for a `NAME_SUM` column. 
@@ -326,6 +331,8 @@ Used to define extensions in `summon`
 - `version`: When defining a column using a python function, as opposed to Polars expressions, add a unique version number so that the unique hashed signature of the column specification can be derived 
 for caching purposes, since Polars cannot generate a serialization natively. When changing the definition, be sure to increment the version value. Otherwise you do not need to use this parameter.
 
+- `views`: Not needed for custom columns.
+
 ### Columns
 
 A table of all included columns. Columns can be referenced by enum or by string value in arguments and filter specs. The string value is always the lowercase version of the enum attribute.
@@ -418,6 +425,8 @@ A table of all included columns. Columns can be referenced by enum or by string
 | `TOUGHNESS` | `"toughness"` | `CARD` | `CARD_ATTR` | | Float |
 | `IS_BONUS_SHEET` | `"is_bonus_sheet"` | `CARD` | `CARD_ATTR` | `SET_CODE` != `EXPANSION` | Boolean |
 | `IS_DFC` | `"is_dfc"` | `CARD` | `CARD_ATTR` | Includes split cards | Boolean |
+| `ORACLE_TEXT` | `"oracle_text"` | `CARD` | `CARD_ATTR` | | String |
+| `CARD_JSON` | `"card_json"` | `CARD` | `CARD_ATTR` | The full dump of the mtgjson entry for the card as printed in the draft booster | String |
 | `PICKED_MATCH_WR` | `"picked_match_wr"` | | `AGG` | `EVENT_MATCH_WINS` / `EVENT_MATCHES` | Float |
 | `TROPHY_RATE` | `"trophy_rate"` | | `AGG` || Float |
 | `GAME_WR` | `"game_wr"` | | `AGG` | `NUM_WON` / `NUM_GAMES` | Float |
@@ -444,7 +453,7 @@ A table of all included columns. Columns can be referenced by enum or by string
 | `GP_WR_Z` | `"gp_wr_z"` | | `AGG` | `GP_WR_EXCESS` / `GP_WR_STDEV` | Float |
 | `GIH_TOTAL` | `"gih_total"` | | `AGG` | Sum `NUM_GIH` over all rows and broadcast back to row level| Float |
 | `WON_GIH_TOTAL` | `"won_gih_total"` | | `AGG` | | Float |
-| `GIH_WR_MEAN` | `"gih_wr_mean"` | | `AGG` |  `GIH_WR - GIH_WR_MEAN` | Float |
+| `GIH_WR_MEAN` | `"gih_wr_mean"` | | `AGG` | `WON_GIH_TOTAL` / `GIH_TOTAL` | Float |
 | `GIH_WR_EXCESS` | `"gih_wr_excess"` | | `AGG` | `GIH_WR - GIH_WR_MEAN` | Float |
 | `GIH_WR_VAR` | `"gih_wr_var"` | | `AGG` | Game-weighted Variance | Float |
 | `GIH_WR_STDEV` | `"gh_wr_stdev"` | | `AGG` | Sqrt of `GIH_WR_VAR` | Float |

spells_mtg-0.2.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+spells/__init__.py,sha256=QCPWQySUK2SZtCU-mSZLsn7vrNLJMDsRwil8gmAzmdk,151
+spells/cache.py,sha256=4v7h8D3TtaT0R_EdiRNhdcQrXzdH_CukezO6oAXvNEY,2956
+spells/cards.py,sha256=6seKpgI4TlJxI20bvcgt5VpxzsbCnnjWneDWpneJJ6Y,3497
+spells/columns.py,sha256=Zw7IIR-HX2HCdeYBGn0RmPGzPA1juGfMl050ndtWhlc,22052
+spells/draft_data.py,sha256=xIr0Jpzv3ktp5AptVFuXlSqTqwGcHE-j1sXNtf064c0,10497
+spells/enums.py,sha256=BQIZvCSAopiscnKY-Qm_j2BgmPy9R5oj1yeIrjMQM1o,4507
+spells/external.py,sha256=qe6wOBDhPN4CZNQvYRq6G-OpIZcWTZzJjySgnf2Gu1o,10258
+spells/filter.py,sha256=J-YTOOAzOQpvIX29tviYL04RVoOUlfsbjBXoQBDCEdQ,3380
+spells/manifest.py,sha256=XEJwwYJzOEWrQQwka39F9SgZo38hH_Kj4MPY7GOuLvY,6903
+spells/schema.py,sha256=z8Qn2SiHG4T6YfPsz8xHLGMjU_Ofm76-Vrquh3b9B64,6422
+spells_mtg-0.2.2.dist-info/METADATA,sha256=zUFcfmHmEp_TD34EYBnFt48qAFOqLNVJv2iKxgFnZIo,41597
+spells_mtg-0.2.2.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
+spells_mtg-0.2.2.dist-info/entry_points.txt,sha256=a9Y1omdl9MdnKuIj3aOodgrp-zZII6OCdvqwgP6BFvI,63
+spells_mtg-0.2.2.dist-info/licenses/LICENSE,sha256=tS54XYbJSgmq5zuHhbsQGbNQLJPVgXqhF5nu2CSRMig,1068
+spells_mtg-0.2.2.dist-info/RECORD,,

spells_mtg-0.1.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-spells/__init__.py,sha256=EcI7ijXYvPA8jj7wUZqs6CSWr__MD8AOXhkex-Hj37E,131
-spells/cache.py,sha256=4v7h8D3TtaT0R_EdiRNhdcQrXzdH_CukezO6oAXvNEY,2956
-spells/cards.py,sha256=CP8f3rUBuFQlj6xj2W72-mDQPuzozEcMu3PkRtBeX1Q,3191
-spells/columns.py,sha256=BEYKDpZYkRgV1kBqIq6XC6kXvVjOih7jGthIpy-YVSw,23339
-spells/draft_data.py,sha256=xoGn6QGaAKgIInEzi2pnvk4CH5xNrwYq4mAj3r07GfA,9272
-spells/enums.py,sha256=Idpv17rCAHDF5bENU8I8V0rpL9W5KB2GM6lhrN4GunU,4447
-spells/external.py,sha256=Apv_l32swO9bF8ihWV73cd7zpzHgxqFy8ZZa1n3XUUE,10260
-spells/filter.py,sha256=J-YTOOAzOQpvIX29tviYL04RVoOUlfsbjBXoQBDCEdQ,3380
-spells/manifest.py,sha256=XEJwwYJzOEWrQQwka39F9SgZo38hH_Kj4MPY7GOuLvY,6903
-spells/schema.py,sha256=z8Qn2SiHG4T6YfPsz8xHLGMjU_Ofm76-Vrquh3b9B64,6422
-spells_mtg-0.1.0.dist-info/METADATA,sha256=Q9FSV4QSWKXLtZCav1YCPTlgDGUXDNRzBO-BQQFIkFM,41050
-spells_mtg-0.1.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-spells_mtg-0.1.0.dist-info/entry_points.txt,sha256=a9Y1omdl9MdnKuIj3aOodgrp-zZII6OCdvqwgP6BFvI,63
-spells_mtg-0.1.0.dist-info/licenses/LICENSE,sha256=tS54XYbJSgmq5zuHhbsQGbNQLJPVgXqhF5nu2CSRMig,1068
-spells_mtg-0.1.0.dist-info/RECORD,,