Add team_abbr_mapping and player_name_mapping datasets

CHANGELOG.md

@@ -1,6 +1,7 @@
 # nflreadpy devel
 
-- update load_participation() season assertions to use improved week-level logic.
+* update `load_participation()` season assertions to use improved week-level logic.
+* Added `team_abbr_mapping()`, `team_abbr_mapping_norelocate()`, and `player_name_mapping()`
 
 ---
 # nflreadpy v0.1.5

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "nflreadpy"
-version = "0.1.5"
+version = "0.1.6"
 description = "A Python package for downloading NFL data from nflverse repositories"
 readme = "README.md"
 license = "MIT"

src/nflreadpy/__init__.py

@@ -10,6 +10,11 @@
 __version__ = version("nflreadpy")
 
 from .cache import clear_cache
+from .datasets import (
+    team_abbr_mapping,
+    team_abbr_mapping_norelocate,
+    player_name_mapping,
+)
 from .load_combine import load_combine
 from .load_contracts import load_contracts
 from .load_depth_charts import load_depth_charts
@@ -62,4 +67,8 @@
     "get_current_season",
     "get_current_week",
     "clear_cache",
+    # datasets
+    "team_abbr_mapping",
+    "team_abbr_mapping_norelocate",
+    "player_name_mapping",
 ]

src/nflreadpy/data/__init__.py

@@ -0,0 +1 @@
+# Placeholder

src/nflreadpy/datasets.py

@@ -0,0 +1,71 @@
+"""Load nflreadpy datasets."""
+
+import os.path
+from importlib import resources
+
+import polars as pl
+
+
+def data_path(dataset=None) -> str:
+    """Get Path to nflreadpy Data Files.
+
+    Returns:
+        Path to file. Empty string if `dataset = None` and error if the file doesn't exist.
+    """
+    if dataset is None:
+        return ""
+    with resources.path("nflreadpy.data", dataset + ".parquet") as f:
+        data_file_path = f
+    if os.path.isfile(data_file_path):
+        return data_file_path
+    else:
+        raise FileNotFoundError(f"The file {data_file_path} doesn't exist!")
+
+
+def team_abbr_mapping() -> pl.DataFrame:
+    """Alternate team abbreviation mappings
+
+    A lookup table mapping common alternate team abbreviations.
+
+    Returns:
+        Polars DataFrame with two columns `name` and `value` where `value` reflects
+        the standardized nflverse team abbreviation.
+
+    See Also:
+        <https://nflreadr.nflverse.com/reference/team_abbr_mapping.html>
+
+    """
+    return pl.read_parquet(data_path("team_abbr_mapping"))
+
+
+def team_abbr_mapping_norelocate() -> pl.DataFrame:
+    """Alternate team abbreviation mappings, no relocation
+
+    A lookup table mapping common alternate team abbreviations,
+    but does not follow relocations to their current city.
+
+    Returns:
+        Polars DataFrame with two columns `name` and `value` where `value` reflects
+        the standardized nflverse team abbreviation.
+
+    See Also:
+        <https://nflreadr.nflverse.com/reference/team_abbr_mapping_norelocate.html>
+
+    """
+    return pl.read_parquet(data_path("team_abbr_mapping_norelocate"))
+
+
+def player_name_mapping() -> pl.DataFrame:
+    """Alternate player name mappings
+
+    A lookup table mapping common alternate player names.
+
+    Returns:
+        Polars DataFrame with two columns `name` and `value` where `value` reflects
+        the standardized player name.
+
+    See Also:
+        <https://nflreadr.nflverse.com/reference/player_name_mapping.html>
+
+    """
+    return pl.read_parquet(data_path("player_name_mapping"))

tests/test_integration.py

@@ -40,6 +40,9 @@ def test_all_exports(self):
             "get_current_season",
             "get_current_week",
             "clear_cache",
+            # datasets
+            "team_abbr_mapping",
+            "team_abbr_mapping_norelocate",
         ]
 
         for export in expected_exports:
@@ -124,6 +127,28 @@ def test_load_ff_rankings_all(self):
         assert isinstance(df, pl.DataFrame)
         assert len(df) >= 0
 
+    def test_team_abbr_mappings(self):
+        """Test team_abbr_mappings."""
+        df1 = nfl.team_abbr_mapping()
+        df2 = nfl.team_abbr_mapping_norelocate()
+        assert isinstance(df1, pl.DataFrame)
+        assert isinstance(df2, pl.DataFrame)
+        assert len(df1) > 0
+        assert len(df2) > 0
+        assert len(df1) >= 143
+        assert len(df2) >= 149
+        # Map to 32 teams + AFC, NFC, NFL
+        assert df1.select("value").n_unique() == 35
+        # Map to 32 teams + AFC, NFC, NFL + SD, STL, OAK
+        assert df2.select("value").n_unique() == 38
+
+    def test_player_name_mapping(self):
+        """Test player_name_mapping."""
+        df = nfl.player_name_mapping()
+        assert isinstance(df, pl.DataFrame)
+        assert len(df) > 0
+        assert len(df) >= 136
+
 
 class TestSeasonalDataLoaders:
     """Test loaders that require season parameters."""