| Name | nflreadpy JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Python package for downloading NFL data from nflverse repositories |
| upload_time | 2025-09-11 16:38:57 |
| maintainer | None |
| docs_url | None |
| author | Tan Ho |
| requires_python | >=3.10 |
| license | None |
| keywords |
nfl
football
sports
data
analytics
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# nflreadpy
A Python package for downloading NFL data from nflverse repositories. This is a
Python port of the popular R package [nflreadr](https://github.com/nflverse/nflreadr),
designed to provide easy access to NFL data with caching, progress tracking, and
modern Python conventions.
## Features
- **Compatible API** with nflreadr R package
- **Fast data loading** with Polars DataFrames
- **Intelligent caching** (memory or filesystem)
- **Progress tracking** for large downloads
- **Modern Python** (3.10+) with type hints
## Install
```bash
# Using uv (recommended)
uv add nflreadpy
# Using pip
pip install nflreadpy
```
## Usage
```python
import nflreadpy as nfl
# Load current season play-by-play data
pbp = nfl.load_pbp()
# Load player game-level stats for multiple seasons
player_stats = nfl.load_player_stats([2022, 2023])
# Load all available team level stats
team_stats = nfl.load_team_stats(seasons=True)
# nflreadpy uses Polars instead of pandas. Convert to pandas if needed:
pbp_pandas = pbp.to_pandas()
```
## Available Functions
### Core Loading Functions
- `load_pbp()` - play-by-play data
- `load_player_stats()` - player game or season statistics
- `load_team_stats()` - team game or season statistics
- `load_schedules()` - game schedules and results
- `load_players()` - player information
- `load_rosters()` - team rosters
- `load_rosters_weekly()` - team rosters by season-week
- `load_snap_counts()` - snap counts
- `load_nextgen_stats()` - advanced stats from nextgenstats.nfl.com
- `load_ftn_charting()` - charted stats from ftnfantasy.com/data
- `load_participation()` - participation data (historical)
- `load_draft_picks()` - nfl draft picks
- `load_injuries()` - injury statuses and practice participation
- `load_contracts()` - historical contract data from OTC
- `load_officials()` - officials for each game
- `load_combine()` - nfl combine results
- `load_depth_charts()` - depth charts
- `load_trades()` - trades
- `load_ff_playerids()` - ffverse/dynastyprocess player ids
- `load_ff_rankings()` - fantasypros rankings
- `load_ff_opportunity()` - expected yards, touchdowns, and fantasy points
### Utility Functions
- `clear_cache()` - Clear cached data
- `get_current_season()` - Get current NFL season
- `get_current_week()` - Get current NFL week
## Configuration
Configure nflreadpy using environment variables:
```bash
# Cache settings
export NFLREADPY_CACHE=filesystem # "memory", "filesystem", or "off"
export NFLREADPY_CACHE_DIR=/path/to/cache # path for filesystem cache
export NFLREADPY_CACHE_DURATION=86400 # time in seconds
# Behavior
export NFLREADPY_VERBOSE=true # Show progress messages
export NFLREADPY_TIMEOUT=30 # Request timeout in seconds
```
Or configure programmatically:
```python
from nflreadpy.config import update_config
update_config(
cache_mode="memory",
verbose=False,
prefer_format="csv"
)
```
## Getting help
The best places to get help on this package are:
- the [nflverse discord](https://discord.com/invite/5Er2FBnnQa) (for
both this package as well as anything NFL analytics related)
- opening [an issue](https://github.com/nflverse/nflreadpy/issues/new/choose)
## Data Sources
nflreadpy downloads data from the following nflverse repositories:
- [nflverse-data](https://github.com/nflverse/nflverse-data) - Play-by-play, rosters, stats
- [nfldata](https://github.com/nflverse/nfldata) - Schedules and game data
- [dynastyprocess](https://github.com/dynastyprocess/data) - fantasy football data
- [ffopportunity](https://github.com/ffverse/ffopportunity) - expected yards and fantasy points
See the automation status page [here](https://nflreadr.nflverse.com/articles/nflverse_data_schedule.html)
for last update date/times for each release.
## License
MIT License - see [LICENSE](LICENSE) file for details.
The majority of all nflverse data available (ie all but the FTN data as of July 2025)
is broadly licensed as CC-BY 4.0, and the FTN data is CC-BY-SA 4.0 (see nflreadr
docs for each main data file).
## Development
This project uses the following tooling:
- **uv** for dependency management
- **ruff** for linting and formatting
- **mypy** for type checking
- **pytest** for testing
```bash
# Install development dependencies
uv sync --dev
# Run tests
uv run pytest
# Format code
uv run ruff format
# Type check
uv run mypy src
```
## Disclaimer
Most of the first version was written by Claude based on nflreadr, use at your
own risk.
## Contributing
Many hands make light work! Here are some ways you can contribute to
this project:
- You can [open an issue](https://github.com/nflverse/nflreadpy/issues/new/choose) if
you’d like to request a feature or report a bug/error.
- If you’d like to contribute code, please check out [the contribution guidelines](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "nflreadpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "nfl, football, sports, data, analytics",
"author": "Tan Ho",
"author_email": "Tan Ho <nflverse@tanho.ca>",
"download_url": "https://files.pythonhosted.org/packages/8f/71/69871c6ffd396277ab8cb7e05e97ede9787b20750edd001127c007bb587a/nflreadpy-0.1.0.tar.gz",
"platform": null,
"description": "# nflreadpy\n\nA Python package for downloading NFL data from nflverse repositories. This is a\nPython port of the popular R package [nflreadr](https://github.com/nflverse/nflreadr),\ndesigned to provide easy access to NFL data with caching, progress tracking, and\nmodern Python conventions.\n\n## Features\n\n- **Compatible API** with nflreadr R package\n- **Fast data loading** with Polars DataFrames\n- **Intelligent caching** (memory or filesystem)\n- **Progress tracking** for large downloads\n- **Modern Python** (3.10+) with type hints\n\n## Install\n\n```bash\n# Using uv (recommended)\nuv add nflreadpy\n\n# Using pip\npip install nflreadpy\n```\n\n## Usage\n\n```python\nimport nflreadpy as nfl\n\n# Load current season play-by-play data\npbp = nfl.load_pbp()\n\n# Load player game-level stats for multiple seasons\nplayer_stats = nfl.load_player_stats([2022, 2023])\n\n# Load all available team level stats\nteam_stats = nfl.load_team_stats(seasons=True)\n\n# nflreadpy uses Polars instead of pandas. Convert to pandas if needed:\npbp_pandas = pbp.to_pandas()\n```\n\n## Available Functions\n\n### Core Loading Functions\n\n- `load_pbp()` - play-by-play data\n- `load_player_stats()` - player game or season statistics\n- `load_team_stats()` - team game or season statistics\n- `load_schedules()` - game schedules and results\n- `load_players()` - player information\n- `load_rosters()` - team rosters\n- `load_rosters_weekly()` - team rosters by season-week\n- `load_snap_counts()` - snap counts\n- `load_nextgen_stats()` - advanced stats from nextgenstats.nfl.com\n- `load_ftn_charting()` - charted stats from ftnfantasy.com/data\n- `load_participation()` - participation data (historical)\n- `load_draft_picks()` - nfl draft picks\n- `load_injuries()` - injury statuses and practice participation\n- `load_contracts()` - historical contract data from OTC\n- `load_officials()` - officials for each game\n- `load_combine()` - nfl combine results\n- `load_depth_charts()` - depth charts\n- `load_trades()` - trades\n- `load_ff_playerids()` - ffverse/dynastyprocess player ids\n- `load_ff_rankings()` - fantasypros rankings\n- `load_ff_opportunity()` - expected yards, touchdowns, and fantasy points\n\n### Utility Functions\n\n- `clear_cache()` - Clear cached data\n- `get_current_season()` - Get current NFL season\n- `get_current_week()` - Get current NFL week\n\n## Configuration\n\nConfigure nflreadpy using environment variables:\n\n```bash\n# Cache settings\nexport NFLREADPY_CACHE=filesystem # \"memory\", \"filesystem\", or \"off\"\nexport NFLREADPY_CACHE_DIR=/path/to/cache # path for filesystem cache\nexport NFLREADPY_CACHE_DURATION=86400 # time in seconds\n\n# Behavior\nexport NFLREADPY_VERBOSE=true # Show progress messages\nexport NFLREADPY_TIMEOUT=30 # Request timeout in seconds\n```\n\nOr configure programmatically:\n\n```python\nfrom nflreadpy.config import update_config\n\nupdate_config(\n cache_mode=\"memory\",\n verbose=False,\n prefer_format=\"csv\"\n)\n```\n\n## Getting help\n\nThe best places to get help on this package are:\n\n- the [nflverse discord](https://discord.com/invite/5Er2FBnnQa) (for\n both this package as well as anything NFL analytics related)\n- opening [an issue](https://github.com/nflverse/nflreadpy/issues/new/choose)\n\n## Data Sources\n\nnflreadpy downloads data from the following nflverse repositories:\n\n- [nflverse-data](https://github.com/nflverse/nflverse-data) - Play-by-play, rosters, stats\n- [nfldata](https://github.com/nflverse/nfldata) - Schedules and game data\n- [dynastyprocess](https://github.com/dynastyprocess/data) - fantasy football data\n- [ffopportunity](https://github.com/ffverse/ffopportunity) - expected yards and fantasy points\n\nSee the automation status page [here](https://nflreadr.nflverse.com/articles/nflverse_data_schedule.html)\nfor last update date/times for each release.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\nThe majority of all nflverse data available (ie all but the FTN data as of July 2025)\nis broadly licensed as CC-BY 4.0, and the FTN data is CC-BY-SA 4.0 (see nflreadr\ndocs for each main data file).\n\n## Development\n\nThis project uses the following tooling:\n\n- **uv** for dependency management\n- **ruff** for linting and formatting\n- **mypy** for type checking\n- **pytest** for testing\n\n```bash\n# Install development dependencies\nuv sync --dev\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run ruff format\n\n# Type check\nuv run mypy src\n```\n\n## Disclaimer\nMost of the first version was written by Claude based on nflreadr, use at your\nown risk.\n\n## Contributing\n\nMany hands make light work! Here are some ways you can contribute to\nthis project:\n\n- You can [open an issue](https://github.com/nflverse/nflreadpy/issues/new/choose) if\nyou\u2019d like to request a feature or report a bug/error.\n\n- If you\u2019d like to contribute code, please check out [the contribution guidelines](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for downloading NFL data from nflverse repositories",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://nflreadpy.readthedocs.io",
"Homepage": "https://github.com/nflverse/nflreadpy",
"Issues": "https://github.com/nflverse/nflreadpy/issues",
"Repository": "https://github.com/nflverse/nflreadpy"
},
"split_keywords": [
"nfl",
" football",
" sports",
" data",
" analytics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "359f27df1a2a994ae77b2d58bc63547b1a72c2c113ce9c20f1695a31d4ac2937",
"md5": "5b9473ecb05555eae191e7569958e015",
"sha256": "f898429baedb1cb459736c4e6f5e6b8b4c34165c7068929498bd442fd36b9fd6"
},
"downloads": -1,
"filename": "nflreadpy-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b9473ecb05555eae191e7569958e015",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25629,
"upload_time": "2025-09-11T16:38:56",
"upload_time_iso_8601": "2025-09-11T16:38:56.323246Z",
"url": "https://files.pythonhosted.org/packages/35/9f/27df1a2a994ae77b2d58bc63547b1a72c2c113ce9c20f1695a31d4ac2937/nflreadpy-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8f7169871c6ffd396277ab8cb7e05e97ede9787b20750edd001127c007bb587a",
"md5": "bb263fd03b71e10b68aba2ca69a0345b",
"sha256": "c5f6bcefa8a1345733cac9093097ad2b1f84c8f728ca840b7e1cb7377ad559e0"
},
"downloads": -1,
"filename": "nflreadpy-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bb263fd03b71e10b68aba2ca69a0345b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13022,
"upload_time": "2025-09-11T16:38:57",
"upload_time_iso_8601": "2025-09-11T16:38:57.294106Z",
"url": "https://files.pythonhosted.org/packages/8f/71/69871c6ffd396277ab8cb7e05e97ede9787b20750edd001127c007bb587a/nflreadpy-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 16:38:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nflverse",
"github_project": "nflreadpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nflreadpy"
}
