diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8833e..d55d5fc 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 946dfae..1b1eccd 100644 --- a/pyproject.toml +++ b/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" diff --git a/src/nflreadpy/__init__.py b/src/nflreadpy/__init__.py index 89d5aa4..f939487 100644 --- a/src/nflreadpy/__init__.py +++ b/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", ] diff --git a/src/nflreadpy/data/__init__.py b/src/nflreadpy/data/__init__.py new file mode 100644 index 0000000..dcf2c80 --- /dev/null +++ b/src/nflreadpy/data/__init__.py @@ -0,0 +1 @@ +# Placeholder diff --git a/src/nflreadpy/data/player_name_mapping.parquet b/src/nflreadpy/data/player_name_mapping.parquet new file mode 100644 index 0000000..d180751 Binary files /dev/null and b/src/nflreadpy/data/player_name_mapping.parquet differ diff --git a/src/nflreadpy/data/team_abbr_mapping.parquet b/src/nflreadpy/data/team_abbr_mapping.parquet new file mode 100644 index 0000000..c6d68b1 Binary files /dev/null and b/src/nflreadpy/data/team_abbr_mapping.parquet differ diff --git a/src/nflreadpy/data/team_abbr_mapping_norelocate.parquet b/src/nflreadpy/data/team_abbr_mapping_norelocate.parquet new file mode 100644 index 0000000..a88a981 Binary files /dev/null and b/src/nflreadpy/data/team_abbr_mapping_norelocate.parquet differ diff --git a/src/nflreadpy/datasets.py b/src/nflreadpy/datasets.py new file mode 100644 index 0000000..75acc27 --- /dev/null +++ b/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: + + + """ + 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: + + + """ + 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: + + + """ + return pl.read_parquet(data_path("player_name_mapping")) diff --git a/tests/test_integration.py b/tests/test_integration.py index 10f38a4..4954497 100644 --- a/tests/test_integration.py +++ b/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.""" diff --git a/uv.lock b/uv.lock index dc3478c..55a2d2f 100644 --- a/uv.lock +++ b/uv.lock @@ -577,7 +577,7 @@ wheels = [ [[package]] name = "nflreadpy" -version = "0.1.5" +version = "0.1.6" source = { editable = "." } dependencies = [ { name = "platformdirs" },