| Name | nfl-data-loader JSON |
| Version |
0.0.10
JSON |
| download |
| home_page | None |
| Summary | A Python interface for various NFL data sources |
| upload_time | 2025-08-28 17:47:04 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
data science
sports
nfl
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# nfl-data-loader
**nfl-data-loader** is a robust Python package for accessing, merging, and transforming NFL sports data from multiple sources in an object-oriented, pipeline-friendly way. It provides a unified API for teams, players, events, and venues, with rich schema documentation and ready-to-use data loaders, transformers, and formatters.
### TheEdgePredictor Services
Upstream
- espn-api-orm (PyPi Package)
- [](https://github.com/theedgepredictor/team-data-pump/actions/workflows/team_data_trigger.yaml)
- [](https://github.com/theedgepredictor/venue-data-pump/actions/workflows/venue_data_trigger.yaml)
- [](https://github.com/theedgepredictor/event-data-pump/actions/workflows/event_data_trigger.yaml)
- odds-data-pump (TBD)
- [](https://github.com/theedgepredictor/fantasy-data-pump/actions/workflows/fantasy_data_trigger.yaml)
- nfl-madden-data (Manual Yearly Trigger)
- [](https://github.com/theedgepredictor/elo-rating/actions/workflows/elo_data_trigger.yaml)
Downstream
- [](https://github.com/theedgepredictor/nfl-feature-store/actions/workflows/feature_store_data_trigger.yaml)
- nfl-model-store (TBD)
- nfl-madden-data (Manual Yearly Trigger)
## 🚀 Features
- Unified access to NFL data from multiple sources (nflverse, Madden, Pro Football Reference, ESPN API)
- Modular loader, transform, and formatter architecture
- Pydantic schemas for all endpoints and data objects
- Grouped by: `team`, `player`, `event`, `venue`
- Easy integration into ML/data pipelines
- Auto-deploy to PyPI on merge to main (see CI/CD)
## 📦 Data Sources
- [feature-store](https://github.com/theedgepredictor/nfl-feature-store)
- [Madden EA / madden.weebly](https://github.com/theedgepredictor/nfl-madden-data)
- [Pro Football Reference](https://www.pro-football-reference.com/)
- [ESPN API](https://github.com/theedgepredictor/espn-api-orm), [fantasy-data-pump](https://github.com/theedgepredictor/fantasy-data-pump)
- [nflverse](https://github.com/nflverse/nflverse-data)
- [greerreNFL](https://github.com/greerreNFL)
## 🏗️ Architecture
```
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Sources │→→ │ Formatters │→→ │ Workflows │
└────────────┘ └────────────┘ └────────────┘
│ │ │
[team, player, event, venue] [Extract, Transform, Load Blocks and Pipelines]
```
## 🧩 Loader Groups
- **Team**: Team stats, rosters, schedules, advanced metrics
- **Player**: Player stats, depth charts, Madden ratings, combine data
- **Event**: Game-level stats, play-by-play, Vegas lines, EPA, fantasy
- **Venue**: Stadium/venue metadata and mappings
## 📑 Schemas & Data Dictionary
All endpoints return data validated by Pydantic schemas. See `/schemas` for:
- Field names, types, and descriptions (see `schemas/events/features.py`, `schemas/players/madden.py`, `schemas/players/position.py`)
- Example: Player Madden schema, event feature schema, position mappers
## 🛠️ Usage Example
```python
from nfl_data_loader.api.sources.players.rosters.rosters import collect_roster
from nfl_data_loader.workflows.transforms.players.player import make_player_stats
# Load player roster for a season
roster_df = collect_roster(2024)
# Transform player stats
player_stats = make_player_stats(2024, week=1, position_group='quarterback')
```
## 📈 Data Flow Example
1. **Load**: Pull raw data from any source (e.g., ESPN, nflverse) or pull cached feature store (Event, Player)
2. **Transform**: Apply rolling averages, imputation, feature engineering
3. **Format**: Output as DataFrame, JSON, or for ML pipelines
## 🧪 Testing & Validation
- All endpoints are covered by tests (see `/tests`)
- Schemas are validated with Pydantic
- Linting and type checking enabled
## 🤖 CI/CD & PyPI Deployment
- GitHub Actions workflow auto-deploys to PyPI on merge to `main`
- See `.github/workflows/publish.yml` for details
## 🤝 Contributing
Pull requests welcome! Please add/expand tests and update schema docs for new endpoints.
---
For a full list of available endpoints, schemas, and data fields, see the `/schemas` and `/api` directories. For questions or issues, open a GitHub issue.
## Publishing
Auto publish available through GitHub Actions and Pypi
Local publishing (include token in rc)
1. ```python -m build```
2. ```twine upload dist/*```
Raw data
{
"_id": null,
"home_page": null,
"name": "nfl-data-loader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "data science, sports, NFL",
"author": null,
"author_email": "TheEdgePredictor <theedgepredictor@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/16/93/a832401ce0012d40b71c625babf1a02556f5ab40081e1a20b75b88d4c350/nfl_data_loader-0.0.10.tar.gz",
"platform": null,
"description": "\r\n# nfl-data-loader\r\n\r\n**nfl-data-loader** is a robust Python package for accessing, merging, and transforming NFL sports data from multiple sources in an object-oriented, pipeline-friendly way. It provides a unified API for teams, players, events, and venues, with rich schema documentation and ready-to-use data loaders, transformers, and formatters.\r\n\r\n### TheEdgePredictor Services\r\n\r\n\r\n\r\nUpstream\r\n- espn-api-orm (PyPi Package)\r\n - [](https://github.com/theedgepredictor/team-data-pump/actions/workflows/team_data_trigger.yaml)\r\n - [](https://github.com/theedgepredictor/venue-data-pump/actions/workflows/venue_data_trigger.yaml)\r\n - [](https://github.com/theedgepredictor/event-data-pump/actions/workflows/event_data_trigger.yaml)\r\n \r\n - odds-data-pump (TBD) \r\n - [](https://github.com/theedgepredictor/fantasy-data-pump/actions/workflows/fantasy_data_trigger.yaml)\r\n- nfl-madden-data (Manual Yearly Trigger)\r\n- [](https://github.com/theedgepredictor/elo-rating/actions/workflows/elo_data_trigger.yaml)\r\n\r\nDownstream\r\n- [](https://github.com/theedgepredictor/nfl-feature-store/actions/workflows/feature_store_data_trigger.yaml)\r\n- nfl-model-store (TBD)\r\n- nfl-madden-data (Manual Yearly Trigger)\r\n\r\n\r\n## \ud83d\ude80 Features\r\n- Unified access to NFL data from multiple sources (nflverse, Madden, Pro Football Reference, ESPN API)\r\n- Modular loader, transform, and formatter architecture\r\n- Pydantic schemas for all endpoints and data objects\r\n- Grouped by: `team`, `player`, `event`, `venue`\r\n- Easy integration into ML/data pipelines\r\n- Auto-deploy to PyPI on merge to main (see CI/CD)\r\n\r\n## \ud83d\udce6 Data Sources\r\n- [feature-store](https://github.com/theedgepredictor/nfl-feature-store)\r\n- [Madden EA / madden.weebly](https://github.com/theedgepredictor/nfl-madden-data)\r\n- [Pro Football Reference](https://www.pro-football-reference.com/)\r\n- [ESPN API](https://github.com/theedgepredictor/espn-api-orm), [fantasy-data-pump](https://github.com/theedgepredictor/fantasy-data-pump)\r\n- [nflverse](https://github.com/nflverse/nflverse-data)\r\n- [greerreNFL](https://github.com/greerreNFL)\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n```\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502 Sources \u2502\u2192\u2192 \u2502 Formatters \u2502\u2192\u2192 \u2502 Workflows \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n \u2502 \u2502 \u2502\r\n [team, player, event, venue] [Extract, Transform, Load Blocks and Pipelines]\r\n```\r\n\r\n## \ud83e\udde9 Loader Groups\r\n- **Team**: Team stats, rosters, schedules, advanced metrics\r\n- **Player**: Player stats, depth charts, Madden ratings, combine data\r\n- **Event**: Game-level stats, play-by-play, Vegas lines, EPA, fantasy\r\n- **Venue**: Stadium/venue metadata and mappings\r\n\r\n## \ud83d\udcd1 Schemas & Data Dictionary\r\nAll endpoints return data validated by Pydantic schemas. See `/schemas` for:\r\n- Field names, types, and descriptions (see `schemas/events/features.py`, `schemas/players/madden.py`, `schemas/players/position.py`)\r\n- Example: Player Madden schema, event feature schema, position mappers\r\n\r\n## \ud83d\udee0\ufe0f Usage Example\r\n```python\r\nfrom nfl_data_loader.api.sources.players.rosters.rosters import collect_roster\r\nfrom nfl_data_loader.workflows.transforms.players.player import make_player_stats\r\n\r\n# Load player roster for a season\r\nroster_df = collect_roster(2024)\r\n\r\n# Transform player stats\r\nplayer_stats = make_player_stats(2024, week=1, position_group='quarterback')\r\n```\r\n\r\n## \ud83d\udcc8 Data Flow Example\r\n1. **Load**: Pull raw data from any source (e.g., ESPN, nflverse) or pull cached feature store (Event, Player)\r\n2. **Transform**: Apply rolling averages, imputation, feature engineering\r\n3. **Format**: Output as DataFrame, JSON, or for ML pipelines\r\n\r\n## \ud83e\uddea Testing & Validation\r\n- All endpoints are covered by tests (see `/tests`)\r\n- Schemas are validated with Pydantic\r\n- Linting and type checking enabled\r\n\r\n## \ud83e\udd16 CI/CD & PyPI Deployment\r\n- GitHub Actions workflow auto-deploys to PyPI on merge to `main`\r\n- See `.github/workflows/publish.yml` for details\r\n\r\n## \ud83e\udd1d Contributing\r\nPull requests welcome! Please add/expand tests and update schema docs for new endpoints.\r\n\r\n---\r\n\r\nFor a full list of available endpoints, schemas, and data fields, see the `/schemas` and `/api` directories. For questions or issues, open a GitHub issue.\r\n\r\n## Publishing\r\n\r\nAuto publish available through GitHub Actions and Pypi\r\n\r\nLocal publishing (include token in rc)\r\n\r\n1. ```python -m build```\r\n\r\n2. ```twine upload dist/*```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python interface for various NFL data sources",
"version": "0.0.10",
"project_urls": {
"Homepage": "https://github.com/theedgepredictor/nfl-data-loader",
"Issues": "https://github.com/theedgepredictor/nfl-data-loader/issues",
"Repository": "https://github.com/theedgepredictor/nfl-data-loader"
},
"split_keywords": [
"data science",
" sports",
" nfl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8c9f0e73163e2be9a77c1b739abcee309ffe807affd3dacc559fb688a4fdff04",
"md5": "e7d9fdf0b1920e4922fe87d9f1015b02",
"sha256": "0af54878e623c03f5f5f2093b364f380e77e06059d34f278ca7f861fdd0e6b44"
},
"downloads": -1,
"filename": "nfl_data_loader-0.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7d9fdf0b1920e4922fe87d9f1015b02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 120931,
"upload_time": "2025-08-28T17:47:03",
"upload_time_iso_8601": "2025-08-28T17:47:03.470887Z",
"url": "https://files.pythonhosted.org/packages/8c/9f/0e73163e2be9a77c1b739abcee309ffe807affd3dacc559fb688a4fdff04/nfl_data_loader-0.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1693a832401ce0012d40b71c625babf1a02556f5ab40081e1a20b75b88d4c350",
"md5": "f8a0dfaa8686853be2ef44f57a8602d0",
"sha256": "0d99bc896c0646ab7a4b0144491f43da8827e9437e398f5cfff424b2814cf61d"
},
"downloads": -1,
"filename": "nfl_data_loader-0.0.10.tar.gz",
"has_sig": false,
"md5_digest": "f8a0dfaa8686853be2ef44f57a8602d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 96953,
"upload_time": "2025-08-28T17:47:04",
"upload_time_iso_8601": "2025-08-28T17:47:04.437588Z",
"url": "https://files.pythonhosted.org/packages/16/93/a832401ce0012d40b71c625babf1a02556f5ab40081e1a20b75b88d4c350/nfl_data_loader-0.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 17:47:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "theedgepredictor",
"github_project": "nfl-data-loader",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nfl-data-loader"
}
