Tags: swar/nba_api
Tags
v1.11.3 * remove: BoxScorePlayerTrackV2 endpoint (NBA API returns 500 error) The NBA API no longer supports this endpoint and returns HTTP 500 errors. Users should use BoxScorePlayerTrackV3 instead. Removed: - src/nba_api/stats/endpoints/boxscoreplayertrackv2.py (endpoint class) - docs/nba_api/stats/endpoints/boxscoreplayertrackv2.md (documentation) - docs/nba_api/stats/endpoints_output/boxscoreplayertrackv2_output.md (examples) - Import from src/nba_api/stats/endpoints/__init__.py - Reference from docs/table_of_contents.md - Deferred endpoint from tests/integration/deferred_endpoints.py - Mapping from tools/stats/library/mapping.py - Entry from docs/examples/Basics.ipynb endpoint list - analysis_archive/stats/analysis.json (archive file) * fix: retire BoxScorePlayerTrackV2 and fix LeagueIDNullable default (#562) - Remove BoxScorePlayerTrackV2 endpoint (NBA API returns HTTP 500) - Fix LeagueIDNullable default value to prevent empty responses - NBA API now requires explicit LeagueID instead of empty string - Bump version to 1.11.3 * remove: PlayerFantasyProfile endpoint (NBA API no longer supports) - Remove PlayerFantasyProfile endpoint class and all references - Remove documentation and test references - Update endpoint mappings and analysis tools - Endpoint removed due to NBA.com API discontinuation * fix: handle missing Coaches dataset in CommonTeamRoster (#553) - Use .get() with default empty dataset for Coaches - NBA API sometimes omits Coaches dataset - Returns empty dataset with proper headers when missing - Add comprehensive unit tests for CommonTeamRoster endpoint - Test coverage includes missing dataset scenario * fix: add missing PLAYER_SLUG and TEAM_SLUG to CommonAllPlayers (#550) - Added PLAYER_SLUG and TEAM_SLUG to expected_data in CommonAllPlayers endpoint - These fields are returned by the NBA API but were previously not included - Updated CHANGELOG.MD with fix details and note about POSITION field limitation - Fixed typo in CONTRIBUTING.md (activate -> eval \$(poetry env activate)) Closes #550 * chore: add missing PlayerFantasyProfile removal to changelog - Added PlayerFantasyProfile to v1.11.3 Removed section - Endpoint was removed in commit 0b6a694 but not documented in changelog * fix: correct CareerHighs expected_data in PlayerProfileV2 (#536) - Added missing GAME_ID field to CareerHighs expected_data - Fixed field name from STATS_VALUE to STAT_VALUE (singular) - Updated CHANGELOG.MD with fix details and clarification Note: Investigation confirmed that CareerHighs correctly returns regular season career highs (not playoff highs). All game IDs have "002" prefix indicating regular season games. Closes #536 * fix: correct Golden State Warriors city name to San Francisco (#434) - Changed city from "Golden State" to "San Francisco" in static teams data - Updated both data.py and template.py - Team name remains "Golden State Warriors" (unchanged) - Updated data timestamp to Nov 13, 2025 Closes #434 * docs: add warning for TeamDashboardByGeneralSplits plus_minus bug (#448) - Added comprehensive class docstring documenting NBA API bug with plus_minus='Y' - Added runtime UserWarning when plus_minus='Y' is used - Documented that plus_minus='Y' returns incorrect differential/delta values - Provided example showing incorrect data (FGM=-0.3 instead of 39.3) - Recommended workaround: use plus_minus='N' (default) - Updated CHANGELOG.MD under "Changed" section Note: This is an NBA.com API bug, not an nba_api issue. The warning helps users avoid incorrect data by steering them away from the broken parameter. Closes #448 * refactor: rewrite PlayByPlayV3 parser with defensive coding pattern Refactored the PlayByPlayV3 parser to eliminate fragile dynamic key extraction and follow CLAUDE.md V3 parser best practices. Changes: - Replace dynamic key indexing with explicit field access - Use defensive .get() calls with defaults throughout - Define all 24 action fields explicitly in headers tuple - Handle edge cases (missing meta, empty actions, missing fields) Testing: - Added 11 comprehensive unit tests covering all edge cases - Created test fixtures for unit testing - Verified with real API calls (475 plays processed successfully) - All 448 unit tests pass Fixes #443 * fix: document and warn about game_id_nullable limitation in LeagueGameFinder (#446) The NBA Stats API ignores the game_id_nullable parameter and returns unfiltered results. This fix addresses the issue by: - Adding runtime UserWarning when game_id_nullable is used - Documenting the limitation in module docstring with workaround examples - Adding integration tests to verify API behavior - Adding unit tests to verify warning emission Users are now warned at runtime and directed to filter results client-side: df[df['GAME_ID'] == 'game_id_value'] Also documents date_from_nullable/date_to_nullable work correctly (#526). * chore: added isort to dev container. * feat: restore TeamGameLog/TeamGameLogs endpoints and enhance integration test validation Restore endpoints: - TeamGameLog and TeamGameLogs endpoints (retired in v1.11.0) are working again - Both endpoints fully functional with all parameters - Added comprehensive unit tests (6 for TeamGameLog, 6 for TeamGameLogs) - Added integration tests (4 test cases for TeamGameLog, 5 for TeamGameLogs) - Generated documentation files in docs/nba_api/stats/endpoints/ Enhanced integration test validation: - Added dataset structure validation to prevent false retirements - Validates dataset names match expected_data keys - Validates column structure for each dataset - Logs per-dataset row counts for better diagnostics - Opt-in validation via validate_structure flag (default: False) - Refactored validation logic to reduce code complexity The enhanced validation catches: - Missing datasets that should be present - Column mismatches in expected_data definitions - API response structure changes - Empty datasets when data is expected Root cause analysis: - Endpoints were incorrectly retired Nov 2, 2025 based on GitHub issue - Integration test framework was created Nov 5, 2025 (3 days later) - No automated validation existed at time of retirement - Enhanced validation prevents similar false retirements in the future Files changed: - src/nba_api/stats/endpoints/teamgamelog.py (restored) - src/nba_api/stats/endpoints/teamgamelogs.py (restored) - tests/unit/stats/endpoints/test_teamgamelog.py (12 unit tests) - tests/integration/data/teamgamelog.py (4 test cases) - tests/integration/data/teamgamelogs.py (5 test cases) - tests/integration/test_endpoints.py (enhanced validation logic) - tests/integration/data/README.md (documentation) - docs/ (endpoint documentation) Test results: - All 37 integration tests passing - All 460 unit tests passing - All flake8 checks passing
v1.11.2 Changes. (#590) * fix: correct dataset order in 9 boxscore parsers to match expected_data (#589) Fixed critical bug where parsers returned datasets in wrong order, causing get_data_frames()[0] to return TeamStats instead of PlayerStats. Affected endpoints: - BoxScoreAdvancedV3 - BoxScoreDefensiveV2 - BoxScoreFourFactorsV3 - BoxScoreHustleV2 - BoxScoreMiscV3 - BoxScorePlayerTrackV3 - BoxScoreScoringV3 - BoxScoreTraditionalV3 - BoxScoreUsageV3 Changes: - Swapped dataset order in 9 parsers to return PlayerStats first - Updated README.md to use named attributes instead of array indices - Added regression test to prevent future dataset ordering bugs - Bumped version to 1.11.2 * fix: correct Asian naming convention in static player data * Updated player_adjustments to properly split Asian player names: - Ha Seung-jin (Korean: 하승진): last_name="Ha", first_name="Seung-jin" - Sun Yue (Chinese: 孙悦): last_name="Sun", first_name="Yue" - Yao Ming (Chinese: 姚明): last_name="Yao", first_name="Ming" - Yi Jianlian (Chinese: 易建联): last_name="Yi", first_name="Jianlian" - Zhou Qi (Chinese: 周琦): last_name="Zhou", first_name="Qi" * Fixed bug where player_adjustments overwrote is_active status - Now preserves active/inactive status from NBA API when applying name corrections - Previously hardcoded is_active=False in adjustments, losing actual player status * Added commonallplayers.json sample API response for testing - Documents NBA API response format for player data - Enables future verification of name parsing logic * Updated CHANGELOG.MD for v1.11.2 release Impact: Enables proper name-based matching and searching while respecting Asian naming conventions (family name first, given name second)
Fix/boxscoretraditionalv3 + Testing Improvements + Player Data Fiile (#… …588) * fix: Rewrite BoxScoreTraditionalV3 parser and reorganize scripts **BoxScoreTraditionalV3 Parser - Complete Rewrite:** Fixed multiple critical bugs in BoxScoreTraditionalV3 parser: 1. AttributeError: get_players_headers() method name typo (should be get_player_headers) 2. TypeError: Tuple + list concatenation in get_start_bench_headers() 3. ValueError: Column count mismatch (31 vs 26) - parser was using advanced stats instead of traditional stats Root cause: Parser incorrectly inherited from BoxScoreAdvancedV3Parser which uses advanced stats fields (offensive rating, pace, PIE) instead of traditional stats fields (FG%, rebounds, assists). Solution: - Created standalone parser with correct traditional stats field definitions - Added 12 comprehensive unit tests following TDD approach - Created minimal test fixture and full API response reference - All tuple concatenations fixed - Correct method names throughout - Parser now returns 26 fields matching expected_data **Scripts Reorganization:** - Moved static player update scripts to scripts/static_players_update/ - Renamed update.py -> generate_static_data_file.py - Deleted obsolete scripts/create_static_data_file.py - Updated src/nba_api/stats/library/data.py All 378 unit tests pass. * test: Add comprehensive unit tests for 5 V3 parsers (100% coverage) Added 59 new unit tests for previously untested parsers: - BoxScoreMatchupsV3 (9 tests) - nested matchup structure validation - PlayByPlayV3 (10 tests) - play-by-play actions and video data - ISTStandings (11 tests) - IST tournament standings with flattened games - BoxScoreHustleV2 (11 tests) - hustle statistics validation - ScheduleLeagueV2 (18 tests) - complex nested schedule structure All 437 unit tests now pass. Parser coverage increased from 67% (10/15) to 100% (15/15). Also includes: - API response fixtures for BoxScoreMatchupsV3, PlayByPlayV3, and ISTStandings - Version bump to 1.11.1 - Updated CHANGELOG.md for v1.11.1 release * fix: Correct flake8 linting error in WNBA teams data Fixed missing whitespace after comma in Seattle Storm team data (E231: missing whitespace after ',') Updated both the template file and generated data.py file. * chore: Exclude .venv, .git, and __pycache__ from flake8 checks
V next (#587) * fix: TeamGameLog and TeamGameLogs have been deprecated by the NBA. No replacement endpoint has been discovered at this time. * build: Modernized DevContainer files. * fix: Added a warning for to BoxScoreSummaryV2 regarding the availability of data on or after 4/10/2025 with a recommendation to use BoxScoreSummaryV3. * fix: Removed TeamGameLog and TeamGameLogs Endpoints. * feat: Add BoxScoreSummaryV3 endpoint with comprehensive game summary data Implements BoxScoreSummaryV3 endpoint to replace deprecated BoxScoreSummaryV2 as the NBA transitions to v3 API format. The new endpoint provides enhanced game summary information with improved data structure. Key features: - Nine datasets: GameSummary, GameInfo, ArenaInfo, Officials, LineScore, InactivePlayers, LastFiveMeetings, OtherStats, and AvailableVideo - New NBAStatsBoxscoreSummaryParserV3 with defensive data access patterns using .get() with defaults for resilience to missing data - Comprehensive docstrings for all parser methods and endpoint classes Code organization improvements: - Introduced _expected_data/ folder structure to separate data definitions from endpoint logic, improving code maintainability and navigation - Follows pattern from test data files for consistency Testing: - 25 unit tests covering parser methods, endpoint initialization, and edge cases including missing data handling - Test fixtures organized in tests/unit/stats/endpoints/data/ * build: CircleCI. Deprecated cimg/python:3.9 and added cimg/python:3.14 * feat: Add DunkScoreLeaders endpoint with comprehensive dunk tracking Add new DunkScoreLeaders endpoint to access NBA dunk tracking data including: - Dunk scores and subscores (jump, power, style, defensive contest) - Biomechanics data (player vertical, hang time, takeoff distance) - Ball tracking metrics (max height, speed through rim) - Dunk style indicators (reverse, 360, alley-oop, etc.) - 55 total fields with complete test coverage Implementation follows best practices: - Expected data in separate _expected_data/dunkscoreleaders.py file - Full docstrings and type hints - Comprehensive unit tests (9 tests, all passing) - Test data fixture for reliable testing - Pylint score: 8.65/10 (excellent) - Flake8: 0 errors Files added: - src/nba_api/stats/endpoints/dunkscoreleaders.py - src/nba_api/stats/endpoints/_expected_data/dunkscoreleaders.py - tests/unit/stats/endpoints/test_dunkscoreleaders.py - tests/unit/stats/endpoints/data/dunkscoreleaders.json * build: Add Makefile and configure code formatters Add comprehensive Makefile for development automation: - Flexible FILES parameter to target specific files - Lint targets (flake8, pylint, combined) - Format targets (isort + black in correct order) - Test targets with coverage support - Documented usage with examples Configure black and isort for compatibility: - Added [tool.isort] with profile="black" for compatibility - Added [tool.black] with line-length=88 and Python 3.10-3.13 - Ensures isort runs before black to prevent conflicts Update poetry.lock for dependency consistency. * build: Deprecate Python 3.9 Minimum Python version increased from 3.9 to 3.10: - Update pyproject.toml requires-python to >=3.10 - Remove Python 3.9 classifier - Update Black target-version to include py314 Update CircleCI configuration: - Add cimg/python:3.14 to test matrix - Set default_image to Python 3.14 - Fix missing closing quote on line 12 Update documentation: - Change README.md minimum version from Python 3.7+ to Python 3.10+ Note: Python 3.9 is no longer supported. Minimum version is now Python 3.10. * fix: Handle empty weeks array in ScheduleLeagueV2 parser Fixes parsing issue for older seasons (e.g., 2015-16) where the weeks array is empty. The parser now returns default headers when weeks array is empty instead of raising IndexError. Changes: - Modified NBAStatsScheduleLeagueV2Parser.get_weeks_headers() to handle empty weeks arrays gracefully - Added comprehensive unit tests for both old (empty weeks) and new (populated weeks) response formats - Created Python test data file for minimal, fast test fixtures - Added full API response example to docs/nba_api/stats/endpoints/responses/ All 243 unit tests pass. * refactor: Move parsers to src/nba_api/stats/endpoints/_parsers/ Reorganizes parser classes for better maintainability and co-location with their corresponding endpoint definitions. Uses underscore prefix to indicate internal/private implementation. Changes: - Created src/nba_api/stats/endpoints/_parsers/ directory structure - Split parserv3.py (1110 lines) into individual parser files: - boxscoreadvancedv3.py (NBAStatsBoxscoreParserV3) - boxscoretraditionalv3.py (NBAStatsBoxscoreTraditionalParserV3) - boxscorematchupsv3.py (NBAStatsBoxscoreMatchupsParserV3) - boxscoresummaryv3.py (NBAStatsBoxscoreSummaryParserV3) - playbyplayv3.py (NBAStatsPlayByPlayParserV3) - iststandings.py (NBAStatsISTStandingsParser) - scheduleleaguev2.py (NBAStatsScheduleLeagueV2Parser + IntParser) - Updated imports in library/http.py to use new parser location - Updated test imports to use new location - Added deprecation notice to library/parserv3.py with backward compatibility (re-exports from new location) Benefits: - Parsers co-located with endpoints in same parent directory - Each parser in its own file for easier navigation and maintenance - File names match endpoint names for consistency - Underscore prefix signals internal/private API - Matches pattern of _expected_data/ directory - Backward compatible for external code still importing from parserv3 All 243 unit tests pass. * refactor: Move parser registry to _parsers module Decouples HTTP library from parser implementations by moving PARSER_DICT and parser lookup logic into the _parsers module itself. This follows the Inversion of Control principle - the parsers package now owns its registry. Changes: - Move PARSER_DICT from http.py to _parsers/__init__.py as _PARSER_REGISTRY - Add get_parser_for_endpoint() factory function in _parsers - Remove NBAStatsParser wrapper class from http.py - Update http.py to use get_parser_for_endpoint() directly - Add docstrings to NBAStatsResponse and NBAStatsHTTP classes - Update parserv3.py deprecation shim to re-export new function Benefits: - HTTP library no longer imports all 8 parser classes - Parsers module is self-contained with its own registry - Easier to extend - just update _parsers/__init__.py when adding parsers - Better separation of concerns - Maintains full backward compatibility All 243 unit tests passing. * build: Update flake8 max-line-length to 88 Align flake8 max-line-length with Black's default of 88 characters for consistency across code formatters. * build: Add pylint for comprehensive code quality checks - Add pylint 4.0.2 as dev dependency - Create .pylintrc with sensible defaults aligned with project style - Max line length set to 88 (matching Black and flake8) - Disable overly strict checks for existing codebase - Makefile already has lint targets: lint-flake8, lint-pylint, and lint * refactor: Refactor V3 parsers to dedicated _parsers module with comprehensive test coverage Reorganize V3 boxscore parsers into a dedicated `_parsers/` module following separation of concerns and improving maintainability. All parsers now follow a consistent pattern with comprehensive test coverage using TDD approach. Changes: - Move existing parsers (boxscoreadvancedv3, boxscoretraditionalv3) to _parsers/ - Add 6 new parsers with complete implementations: - boxscoredefensivev2: Defensive statistics (deflections, charges, etc.) - boxscorefourfactorsv3: Four factors analysis (eFG%, TO%, etc.) - boxscorehustlev2: Hustle stats (contested shots, loose balls, etc.) - boxscoremiscv3: Miscellaneous stats (points off turnovers, etc.) - boxscoreplayertrackv3: Player tracking (distance, speed, touches, etc.) - boxscorescoringv3: Scoring breakdowns (2PT, 3PT, paint, etc.) - boxscoreusagev3: Usage percentages and possession distribution - Create parser registry in _parsers/__init__.py with register_parser() function - Fix circular import in http.py using lazy parser loading - Add 7 test suites with 86 comprehensive unit tests (all passing) - Add Python test fixtures (not JSON files) for all parsers - Add API response documentation in docs/nba_api/stats/endpoints/responses/ All parsers: - Return headers as lists (not tuples) for API compatibility - Follow consistent metadata patterns (team, player, statistics) - Handle missing/incomplete data gracefully - Include comprehensive test coverage (initialization, headers, data extraction) Test results: 329 total unit tests passing (86 new parser tests) Code quality: All files formatted with black/isort, linted with flake8 * docs: Add REFACTORING.md to track technical debt and future improvements Create a structured document for tracking refactoring opportunities and technical debt. First item documents the parser/HTTP layer decoupling that should be addressed in a future PR. - Establish priority levels (High/Medium/Low) - Include context, proposed solutions, and benefits - Archive completed refactorings with commit references - Add guidelines for contributors adding new items * test: Add integration test framework for validating endpoint scenarios Create simple integration tests to validate specific endpoint behaviors reported in GitHub issues. Focus on testing exact scenarios users report, not parameter discovery or API requirements. Common use cases: - "Does endpoint work at all?" → Basic smoke test - "Season 2020-21 returns empty" → Test exact param combo - "Playoffs broken for this endpoint" → Validate the scenario Structure: - tests/integration/data/{endpoint}.py - TEST_CASES constant - tests/integration/test_endpoint_parameters.py - Test functions - Simple pytest -k filtering to test specific endpoints Usage: # Test specific endpoint with all scenarios pytest tests/integration/test_endpoint_parameters.py -k playerdashptshotdefend -v # Quick smoke tests pytest tests/integration/test_endpoint_parameters.py -k smoke -v Benefits: - No more Colab/Postman for validating issues - Easy to add scenarios from GitHub reports - Standardized TEST_CASES format across all files - Clear expected results: "has_data", "empty", or "error" * refactor: Remove smoke and integration terminology from test files * docs: Update integration test documentation with expected validation format * feat: Add ScoreboardV3 endpoint with comprehensive dataset support Implement ScoreboardV3 endpoint with 6 datasets providing game schedule, scores, leaders, and broadcaster information: - ScoreboardInfo: Game date and league metadata - GameHeader: Core game information (status, timing, series data) - LineScore: Team scores, records, and timeouts - GameLeaders: Per-game leader statistics - TeamLeaders: Season leader statistics (season averages) - Broadcasters: Comprehensive broadcaster info (TV, radio, OTT) Implementation follows TDD workflow with full test coverage: - Parser with 15 unit tests (all passing) - Endpoint with 10 unit tests (all passing) - Integration tests with 3 scenarios (all passing) Closes #580 * docs: Add deprecation warning to BoxScoreTraditionalV2 Add comprehensive deprecation warning to BoxScoreTraditionalV2 endpoint: - Module-level docstring with deprecation notice - Class docstring with Sphinx deprecation directive - Runtime DeprecationWarning when endpoint is instantiated Users are advised to migrate to BoxScoreTraditionalV3 as data is no longer being published for V2 as of the 2025-26 NBA season. * test: Add comprehensive tests for TeamDashLineups endpoint - Add unit tests for TeamDashLineups endpoint (12 tests, 96% coverage) - Test initialization, parameters, datasets, and expected data structure - Mock HTTP requests for isolated testing - Follow established pattern from test_dunkscoreleaders.py - Add integration tests for TeamDashLineups with 4 test scenarios - Cleveland Cavaliers 5-man lineups 2024-25 - Lakers 2-man lineups 2023-24 - Warriors 3-man playoffs 2023-24 - Celtics 4-man lineups with date range - Tests include full logging (URLs, parameters, response size, data rows) - Migrate JSON test fixtures to Python fixtures pattern - Create teamdashlineups.py and dunkscoreleaders.py minimal fixtures - Move full JSON responses to docs/nba_api/stats/endpoints/responses/ - Update test files to import Python fixtures instead of loading JSON - Improves test performance and follows V3 endpoint pattern All tests pass with no flake8 errors. * fix: Add missing boxscoresummaryv3 Python fixture for unit tests The test_boxscoresummaryv3.py was loading a JSON file that didn't exist, causing 21 test failures in CI. Create minimal Python fixture following the established pattern from other V3 endpoints. - Create tests/unit/stats/endpoints/data/boxscoresummaryv3.py with BOXSCORESUMMARYV3_SAMPLE minimal fixture - Update test_boxscoresummaryv3.py to import Python fixture instead of loading non-existent JSON file - Fixture includes all required fields for parser tests All 25 boxscoresummaryv3 tests now pass. * chore: Prepare release v1.11.0 Update version to 1.11.0 and add comprehensive changelog entry. Release includes: - 3 new endpoints (BoxScoreSummaryV3, DunkScoreLeaders, ScoreboardV3) - Enhanced testing infrastructure with integration test framework - Parser architecture refactoring to _parsers module - Build system improvements (pylint, formatters, Makefile) - Python 3.9 deprecation - Multiple bug fixes and documentation updates See CHANGELOG.MD for complete details.
Fix/add origin header (#571) * fix: update HTTP headers to resolve NBA Stats API connection issues - Updated User-Agent to Chrome 140 - Added Sec-Ch-Ua, Sec-Ch-Ua-Mobile, and Sec-Fetch-Dest headers - Removed x-nba-stats-origin and x-nba-stats-token headers * chore: update static player data and improve update script - Updated static player and team data - Added comprehensive logging to static_players_update/update.py - Updated data generation template * chore: corrected template.py for WNVA Valkyries
chore: release v1.10.1 (#567) - Update version to 1.10.1 in pyproject.toml - Generate comprehensive changelog with v1.10.1 and v1.10.0 entries - Add gen-release.sh script for local release preparation - Fix Unix line endings and remove set -e from script - Restore complete changelog history after semantic-release overwrote it Release includes fixes for WinProbability data handling, PlayIn season type, build system automation, and security dependency updates.
PreviousNext