How donmichaell/euroleague_api works
Main Components
• API Client Library: The core of the project is contained in the “src/euroleague_api” directory. Each module (e.g., EuroLeagueData.py, game_stats.py, shot_data.py, etc.) represents a distinct API endpoint or data category.
• Documentation & Examples: The “docs” and “site” directories provide HTML-rendered documentation of the modules. The “notebooks” directory includes example notebooks for usage.
• Developer Tools: You have CI/CD configuration files (.github/workflows) and static analysis/setup files (pylintrc, mypy.ini, setup.cfg, pyproject.toml, requirements.txt, etc.) which support continuous integration, code quality, and packaging related aspects.
• External API: Represent the actual Euroleague endpoints as an external component (e.g. Swagger-based endpoints, blog-sourced endpoints).
Relationships and Interactions
• User/Consumer → API Client Library: Users install the package (via pip) and build their applications on top of it.
• API Client Library modules internally call one or more HTTP endpoints to fetch data. For example, ShotData in shot_data.py retrieves shot data when invoking methods.
• The modules rely on common utility functions (from utils.py) that help with common aspects (parsing, formatting, etc.).
• Documentation is auto-generated from the source code and is provided externally through the “site/” folder.
Architectural Patterns & Design Principles
• Layered Approach: At the base, you have the HTTP communication layer (connection to external endpoints) wrapped by individual modules that represent domain-specific data.
• Modularity: Each file/module is responsible for a specific aspect of the API (e.g., shot data, standings, play-by-play) making it easier to extend the API with additional endpoints.
• Separation of Concerns: Documentation, application logic (the Python package), and testing/examples (notebooks) are clearly separated.
• Extensibility: The design allows for additional endpoints or modules to be added as new files following the same structure.
Relevant Technologies & Frameworks
• Python (with emphasis on standard library HTTP client and optionally libraries like requests)
• Software quality tools (pre-commit, pylint, mypy)
• CI/CD environment provided by GitHub Actions (found in .github/workflows)
Elements
• Clearly Labeled Components:
• “User/Client Application” – that imports/uses the package.
• “Euroleague API Package” – with contained modules for EuroLeagueData, game_stats, player_stats, team_stats, shot_data, play_by_play_data, boxscore_data, and utils.
• “External Euroleague API Endpoints” – representing the live API.
• “Documentation/Examples” – highlighting the notebooks and generated HTML docs.
• “CI/CD and Quality Tools” – encapsulating GitHub workflows and static configurations.
• From the “User/Client Application” to individual API modules to show how methods (e.g., get_game_shot_data) are invoked.
• From API modules to the “External Euroleague API Endpoints” indicating data requests/responses.
• Visual Differentiation: Use: