sportsdataverse-py

SportsDataverse Python

Outcome

Create a user-owned multi-sport artifact with documented league, upstream source, module, loader function, arguments, package version, retrieval time, grain, schema, coverage, natural key, and validation results.

SportsDataverse modules and upstream endpoints vary. Discover and probe the installed interface before a large pull; never guess that one league's function name or parameters apply to another.

When to use this skill

Use for supported NBA, MLB, NHL, college, soccer, and other multi-sport schedule, scoreboard, roster, box-score, or event sources. Prefer nflreadpy for bulk nflverse releases and pybaseball for Statcast or baseball leaderboard depth.

Read references/when_not_nflreadpy.md when choosing an NFL source. Read references/load_patterns.md when choosing the acquisition depth and snapshot pattern for another module.

Installation

python -m pip install sportsdataverse pandas pyarrow

Network access and upstream availability are external constraints. Record the installed package version and preserve successful source responses used in claims.

Interface discovery

import importlib
import importlib.metadata
import inspect
import pkgutil
import sportsdataverse

print(importlib.metadata.version("sportsdataverse"))
print([
    item.name for item in pkgutil.iter_modules(sportsdataverse.__path__)
    if not item.name.startswith("_")
])
league = importlib.import_module("sportsdataverse.nba")
callables = [
    name for name in dir(league)
    if not name.startswith("_") and callable(getattr(league, name))
]
print(callables)
for name in callables:
    print(name, inspect.signature(getattr(league, name)))

Consult the installed package documentation, signature, and return type. A function may accept dates rather than season, return nested mappings rather than a table, or expose different parameters across modules and versions. Do not restrict discovery to load_*: installed releases also expose functions with provider- and league-prefixed names such as espn_*.

Source and loader decision table

Need	Start with	Escalate only when	Main risk
Season coverage/results	schedule or bulk season loader	game fields are insufficient	status/schema variation
Today's or bounded slate	scoreboard/date loader	detail endpoint is required	assuming one date equals a season
Team/player box data	box-score loader	event/play grain is essential	pagination and nested schema
Play-by-play/events	event loader	question truly requires it	volume, truncation, post-event fields
Rosters	roster loader	historical snapshots are needed	current roster used as historical
Multi-league comparison	separate league artifacts first	identifiers/grains are normalized	false schema equivalence

Prefer bulk schedule/release loaders over date-by-date scraping when the package offers them. Request event-level data only when schedule or box-score grain cannot answer the question.

Acquisition workflow

1. Lock sport, competition, season/date window, grain, and required fields.
2. Confirm installed package version and supported league module.
3. Inspect available functions, signatures, docs, and return types.
4. Run the smallest representative request.
5. Inspect nested structure or columns, dtypes, row count, key, and status values.
6. Save the raw response or minimally converted table before normalization.
7. Check pagination, request limits, and observed coverage.
8. Convert to pandas only if the next user-selected tool requires it.
9. Normalize names and types in a separate derived artifact with a field map.
10. Validate dates, teams, scores, duplicates, missingness, and schema drift.
11. Save raw and normalized artifacts plus a manifest and known fallback.

Normalized schedule schema

When preparing game-level analysis, prefer durable fields such as:

game_id, season, event_time, home_team, away_team,
home_score, away_score, status, source

Also preserve competition/league, season type, neutral-site flag, venue, timezone, and raw identifiers when available. Keep unmapped source fields in the raw artifact rather than discarding them. Derive team-game rows only after the game-level artifact passes uniqueness and completion checks.

Validation checks

Interface and retrieval

• package version, module, loader, and exact arguments are recorded;
• the returned object type and conversion steps are documented;
• requested competitions, seasons, or dates are present;
• pagination/request limits did not truncate results;
• empty responses are distinguished from endpoint errors;
• raw artifacts can be traced to a retrieval timestamp and source.

Game or schedule grain

• event IDs are unique or duplicate causes are resolved;
• home and away identifiers are present and distinct;
• completed status agrees with non-null plausible outcomes;
• scheduled/postponed/canceled events remain distinguishable;
• timestamps and timezones are understood;
• regular season, postseason, neutral sites, ties, and overtime are treated explicitly.

Cross-season or cross-league data

• schema drift is reported before concatenation;
• team/player IDs and name changes are mapped explicitly;
• units, score conventions, period structures, and grains are not assumed equal;
• each source remains attributable after normalization;
• row counts and missingness are broken out by league and season.

Multi-sport caveats

• A similarly named column can have different semantics across modules.
• Season labels may refer to start year, end year, or competition-specific codes.
• Scoreboard helpers often accept dates and return only a bounded slate; they are not necessarily season loaders.
• Historical dumps or upstream feeds can contain constant scores, duplicates, missing periods, or incomplete seasons. Sanity-check distributions.
• Current rosters and post-event box scores are not automatically legal pre-event predictors.
• Ties, overtime, shootouts, doubleheaders, aggregate legs, neutral venues, and postseason formats differ by sport.
• A shared normalized schema aids storage but does not erase sport-specific logic.

Team-game derivation

If a downstream analysis requires team-game grain:

1. validate one unique completed source row per contest;
2. preserve the raw game row and status;
3. emit two complementary rows with shared game_id;
4. reverse team/opponent, home flag, scores, and margin correctly;
5. preserve tie/overtime/neutral-site semantics;
6. report both team-row and unique-game counts;
7. verify the full-panel win rate is understood as a construction property.

Do not normalize directly from an unchecked, possibly truncated scoreboard response.

Snapshot manifest

package_and_version
league_module
upstream_source_if_known
loader_and_exact_arguments
retrieval_timestamp_utc
requested_and_observed_coverage
raw_artifact_path_and_checksum
normalized_artifact_path_and_checksum
grain_and_natural_key
rows_events_teams_and_seasons
status_filter_and_timezone
field_mapping_and_transformations
pagination_or_request_limit_check
schema_drift_known_gaps_and_fallback

Hard constraints and integrity rules

1. Never assume league modules expose the same API.
2. Never guess loader arguments without inspecting the installed signature.
3. Never swallow endpoint or schema errors and return empty data as success.
4. Never merge leagues before normalizing identifiers, units, and grain.
5. Never treat post-event fields as pre-event predictors.
6. Never perform an unbounded event-level pull.
7. Preserve source attribution, package version, and retrieval time.
8. Filter completed games under a documented status rule for outcome analysis.
9. Validate pagination, uniqueness, scores, and schema before modeling.
10. Preserve raw source data separately from normalized derivatives.

Anti-patterns

• passing a season argument to a date-only scoreboard helper;
• believing one scoreboard response contains an entire season;
• modeling rows with incomplete or ambiguous status;
• ignoring constant-score or duplicate-event corruption;
• normalizing disparate leagues by column name alone;
• silent schema drift across seasons;
• loading play-by-play when schedules answer the question;
• claiming success from a zero-row table after an upstream failure;
• converting/discarding nested fields before saving the raw response.

Worked examples

Bounded module probe

Discover functions for the installed NBA module, inspect the candidate schedule loader signature, request one small season/date slice, record return type and schema, and expand only after checking event IDs and coverage.

Multi-league schedule comparison

Acquire and validate each league separately. Save league-specific raw snapshots, normalize only common game-level fields with a source column, retain sport- specific fields separately, and compare rates only after aligning competition, season type, status, and denominator definitions.

Helper

python <path-to-sportsdataverse-py>/scripts/smoke_load.py \
  --modules nba,mlb,nhl --list-modules

The helper parses arguments before importing the optional public package and uses installed distribution metadata for the version. It discovers real public namespaces, imports every requested module, and exits nonzero if any requested module fails; a partial probe is not reported as success. It does not call an endpoint or prove that a particular loader/source is healthy.

Output contract

Return raw and normalized artifact paths, package version, league module, upstream source if known, loader and arguments, retrieval time, grain, natural key, rows/events, schema, filters, coverage, mapping, pagination check, known gaps, fallback, and validation results.

Resources

• references/load_patterns.md — read when choosing schedule, box-score, or event acquisition depth and snapshot shape.
• references/when_not_nflreadpy.md — read when choosing between SportsDataverse and nflreadpy for NFL data.
• scripts/smoke_load.py — lightweight installed-module probe.