ceblpy 0.1.0__py3-none-any.whl

ceblpy/__init__.py

@@ -0,0 +1,3 @@
+# read version from installed package
+from importlib.metadata import version
+__version__ = version("ceblpy")

ceblpy/ceblpy.py

@@ -0,0 +1,485 @@
+import pandas as pd
+from . import helpers as h
+from datetime import datetime
+
+
+def load_cebl_schedule(seasons=None):
+    """
+    Load cleaned CEBL schedule data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the schedule with the following columns:
+
+        ================================  ===========
+        Column Name                        Type
+        ================================  ===========
+        fiba_id                            int
+        season                             int
+        start_time_utc                     datetime
+        status                             str
+        competition                        str
+        venue_name                         str
+        period                             float
+        home_team_id                       int
+        home_team_name                     str
+        home_team_score                    float
+        home_team_logo_url                 str
+        home_team_url_stats_en             str
+        home_team_url_stats_fr             str
+        away_team_id                       int
+        away_team_name                     str
+        away_team_score                    float
+        away_team_logo_url                 str
+        away_team_url_stats_en             str
+        away_team_url_stats_fr             str
+        stats_url_en                       str
+        stats_url_fr                       str
+        cebl_stats_url_en                  str
+        cebl_stats_url_fr                  str
+        tickets_url_en                     str
+        tickets_url_fr                     str
+        id                                 int
+        fiba_json_url                      str
+        ================================  ===========
+
+
+    Examples
+    --------
+    >>> load_cebl_schedule(2020)
+    >>> load_cebl_schedule([2019, 2020, 2021])
+    >>> load_cebl_schedule()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    schedule = pd.read_csv("https://github.com/ryanndu/cebl-data/releases/download/schedule/cebl_schedule.csv")
+    schedule = schedule[schedule['season'].isin(seasons)]
+    return schedule
+
+
+def load_cebl_team_boxscore(seasons=None):
+    """
+    Load cleaned CEBL team boxscore data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the team boxscore with the following columns:
+
+        ==============================================  ===========
+        Column Name                                      Type
+        ==============================================  ===========
+        game_id                                          int
+        season                                           int
+        team_name                                        str
+        short_name                                       str
+        code                                             str
+        team_score                                       int
+        minutes                                          str
+        field_goals_made                                 int
+        field_goals_attempted                            int
+        field_goal_percentage                            int
+        two_point_field_goals_made                       int
+        two_point_field_goals_attempted                  int
+        two_point__percentage                            int
+        three_point_field_goals_made                     int
+        three_point_field_goals_attempted                int
+        three_point_percentage                           int
+        free_throws_made                                 int
+        free_throws_attempted                            int
+        free_throw_percentage                            int
+        offensive_rebounds                               int
+        defensive_rebounds                               int
+        rebounds                                         int
+        assists                                          int
+        steals                                           int
+        turnovers                                        int
+        blocks                                           int
+        blocks_received                                  int
+        personal_fouls                                   int
+        fouls_drawn                                      int
+        total_fouls                                      int
+        bonus_fouls                                      int
+        points_in_the_paint                              int
+        second_chance_points                             int
+        points_from_turnovers                            int
+        bench_points                                     int
+        fast_break_points                                int
+        team_index_rating                                int
+        team_index_rating_2                              int
+        team_index_rating_3                              float
+        team_index_rating_4                              float
+        team_index_rating_5                              int
+        team_index_rating_6                              int
+        team_index_rating_7                              int
+        team_fouls                                       int
+        team_turnovers                                   int
+        team_rebounds                                    int
+        team_defensive_rebounds                          int
+        team_offensive_rebounds                          int
+        period_1_score                                   int
+        period_2_score                                   float
+        period_3_score                                   float
+        period_4_score                                   float
+        biggest_lead                                     float
+        biggest_scoring_run                              float
+        time_leading                                     float
+        lead_changes                                     int
+        times_scores_level                               int
+        timeouts_left                                    int
+        head_coach                                       str
+        assistant_coach_1                                str
+        assistant_coach_2                                str
+        international_team_name                          str
+        international_short_name                         str
+        international_code                               str
+        logo                                             str
+        logo_t_url                                       str
+        logo_t_size                                      str
+        logo_t_height                                    int
+        logo_t_width                                     int
+        logo_t_bytes                                     int
+        logo_s_url                                       str
+        logo_s_size                                      str
+        logo_s_height                                    int
+        logo_s_width                                     int
+        logo_s_bytes                                     int
+        ==============================================  ===========
+
+    Examples
+    --------
+    >>> load_cebl_team_boxscore(2020)
+    >>> load_cebl_team_boxscore([2019, 2020, 2021])
+    >>> load_cebl_team_boxscore()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    team_boxscore = pd.read_csv("https://github.com/ryanndu/cebl-data/releases/download/team-boxscore/cebl_teams.csv")
+    team_boxscore = team_boxscore[team_boxscore['season'].isin(seasons)]
+    return team_boxscore
+
+
+def load_cebl_player_boxscore(seasons=None):
+    """
+    Load cleaned CEBL player boxscore data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the player boxscore with the following columns:
+
+        ======================================  ===========
+        Column Name                              Type
+        ======================================  ===========
+        game_id                                  int
+        season                                   int
+        team_name                                str
+        player_number                            int
+        player_name                              str
+        player_position                          str
+        minutes                                  str
+        points                                   int
+        field_goals_made                         int
+        field_goals_attempted                    int
+        field_goal_percentage                    int
+        two_point_field_goals_made               int
+        two_point_field_goals_attempted          int
+        two_point__percentage                    int
+        three_point_field_goals_made             int
+        three_point_field_goals_attempted        int
+        three_point_percentage                   int
+        free_throws_made                         int
+        free_throws_attempted                    int
+        free_throw_percentage                    int
+        offensive_rebounds                       int
+        defensive_rebounds                       int
+        rebounds                                 int
+        assists                                  int
+        turnovers                                int
+        steals                                   int
+        blocks                                   int
+        blocks_received                          int
+        personal_fouls                           int
+        fouls_drawn                              int
+        plus_minus                               int
+        index_rating                             int
+        index_rating_2                           int
+        index_rating_3                           float
+        index_rating_4                           float
+        index_rating_5                           int
+        index_rating_6                           int
+        index_rating_7                           int
+        second_chance_points                     int
+        fast_break_points                        int
+        points_in_the_paint                      int
+        first_name                               str
+        first_name_initial                       str
+        last_name                                str
+        last_name_initial                        str
+        international_first_name                 str
+        international_first_name_initial         str
+        international_last_name                  str
+        international_last_name_initial          str
+        scoreboard_name                          str
+        active                                   bool
+        starter                                  bool
+        captain                                  bool
+        photo_t                                  str
+        photo_s                                  str
+        ======================================  ===========
+
+    Examples
+    --------
+    >>> load_cebl_player_boxscore(2020)
+    >>> load_cebl_player_boxscore([2019, 2020, 2021])
+    >>> load_cebl_player_boxscore()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    player_boxscore = pd.read_csv("https://github.com/ryanndu/cebl-data/releases/download/player-boxscore/cebl_players.csv")
+    player_boxscore = player_boxscore[player_boxscore['season'].isin(seasons)]
+    return player_boxscore
+
+
+def load_cebl_officials(seasons=None):
+    """
+    Load cleaned CEBL officials data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the officials with the following columns:
+
+        ================================  ===========
+        Column Name                        Type
+        ================================  ===========
+        game_id                            int
+        season                             int
+        officials_type                     str
+        officials_name                     str
+        first_name                         str
+        last_name                          str
+        scoreboard_name                    str
+        first_name_initial                 str
+        last_name_initial                  str
+        international_first_name           str
+        international_first_name_initial   str
+        international_last_name            str
+        international_last_name_initial    str
+        scoreboard_name                    str
+        ================================  ===========
+        
+    Examples
+    --------
+    >>> load_cebl_officials(2020)
+    >>> load_cebl_officials([2019, 2020, 2021])
+    >>> load_cebl_officials_boxscore()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    officials = pd.read_csv("https://github.com/ryanndu/cebl-data/releases/download/officials/cebl_officials.csv")
+    officials = officials[officials['season'].isin(seasons)]
+    return officials
+
+
+def load_cebl_coaches(seasons=None):
+    """
+    Load cleaned CEBL coaches data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the coaches with the following columns:
+
+        ================================  ===========
+        Column Name                        Type
+        ================================  ===========
+        game_id                            int
+        season                             int
+        team_name                          str
+        coach_name                         str
+        coach_type                         str
+        first_name                         str
+        first_name_initial                 str
+        last_name                          str
+        last_name_initial                  str
+        international_first_name           str
+        international_first_name_initial   str
+        international_last_name            str
+        international_last_name_initial    str
+        scoreboard_name                    str
+        ================================  ===========
+        
+    Examples
+    --------
+    >>> load_cebl_coaches(2020)
+    >>> load_cebl_coaches([2019, 2020, 2021])
+    >>> load_cebl_coaches()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    coaches = pd.read_csv("https://github.com/ryanndu/cebl-data/releases/download/coaches/cebl_coaches.csv")
+    coaches = coaches[coaches['season'].isin(seasons)]
+    return coaches
+
+
+def load_cebl_pbp(seasons=None):
+    """
+    Load cleaned CEBL pbp data from the cebl data repository.
+
+    Parameters
+    ----------
+    seasons : int, list of int, or None, optional
+        Season(s) to load. By default, None loads all available seasons.
+        - int : Single season year (e.g., 2020)
+        - list of int : Multiple seasons (e.g., [2019, 2020, 2021])
+        - None : Load all available seasons
+
+        All years must be 2019 or later.
+
+    Returns
+    -------
+    pandas.DataFrame
+        A DataFrame containing the pbp with the following columns:
+
+        ================================  ===========
+        Column Name                        Type
+        ================================  ===========
+        game_id                            int
+        season                             int
+        game_time                          str
+        home_score                         int
+        away_score                         int
+        home_lead                          int
+        team_id                            int
+        period                             int
+        period_type                        str
+        player_id                          int
+        scoreboard_name                    str
+        success                            int
+        action_type                        str
+        action_number                      float
+        previous_action                    float
+        sub_type                           str
+        scoring                            int
+        shirt_number                       float
+        player_name                        str
+        first_name                         str
+        last_name                          str
+        x                                  float
+        y                                  float
+        qualifier_0                        str
+        qualifier_1                        str
+        qualifier_2                        str
+        qualifier_3                        str
+        international_first_name           str
+        international_last_name            str
+        international_first_name_initial   str
+        international_last_name_initial    str
+        ================================  ===========
+        
+    Examples
+    --------
+    >>> load_cebl_pbp(2020)
+    >>> load_cebl_pbp([2019, 2020, 2021])
+    >>> load_cebl_pbp()
+    """
+    if isinstance(seasons, int):
+        seasons = [seasons]
+    if isinstance(seasons, list):
+        h.validate_seasons(seasons)
+    elif seasons is None:
+        seasons = list(range(2019, datetime.now().year + 1))
+    else:
+        raise TypeError(f"Expected seasons to be an int, list of ints, or None, got {type(seasons).__name__}")
+    
+    pbp = pd.DataFrame()
+    for season in seasons:
+        pbp = pd.concat([pbp, pd.read_csv(f"https://github.com/ryanndu/cebl-data/releases/download/pbp/cebl_pbp_{season}.csv")])
+    return pbp

ceblpy/helpers.py

@@ -0,0 +1,29 @@
+import pandas as pd
+from datetime import datetime
+
+def validate_seasons(seasons):
+    """
+    Checks whether all the provided seasons are valid years and raises an error if not.
+
+    Parameters
+    ----------
+    seasons: list of int
+        A list of years representing seasons to validate.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> validate_seasons([2019, 2020, 2021])
+    >>> validate_seasons([2018, "2020"])  # Raises TypeError
+    >>> validate_seasons([2022, 2023, 2030])  # Raises ValueError
+    """
+    if not isinstance(seasons, list):
+        raise TypeError("Expected a list of years")
+    for year in seasons:
+        if not isinstance(year, int):
+            raise TypeError(f"Expected an integer for year, got {type(year).__name__}")
+        if year < 2019 or year > datetime.now().year:
+            raise ValueError(f"Year {year} out of valid range (2019-{datetime.now().year})")

ceblpy-0.1.0.dist-info/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025, Ryan Du
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

ceblpy-0.1.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.3
+Name: ceblpy
+Version: 0.1.0
+Summary: Extract and analyze data form the Canadian Elite Basketball league (CEBL).
+License: MIT
+Author: Ryan Du
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pandas (>=2.3.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# ceblpy <img src="https://github.com/ryanndu/ceblpy/raw/main/assets/images/cebl-logo.png" align="right" width="100" height="100"/>
+
+---
+
+## Overview
+
+**[ceblpy](https://github.com/ryanndu/ceblpy)** is a Python package designed for working with the Canadian Elite Basketball League (CEBL) data.
+
+The package has functions to retrieve team and player box scores, game schedules, coach and officials information, and full play-by-play data.
+
+---
+
+## Installation
+
+You can install the **[ceblpy](https://github.com/ryanndu/ceblpy)** package with:
+
+```bash
+$ pip install ceblpy
+```
+
+---
+
+## Usage
+
+To retrieve the CEBL schedule for a given season (e.g., 2024), use the `load_cebl_schedule()` function:
+
+```python
+from ceblpy.ceblpy import load_cebl_schedule
+
+# Load the 2024 CEBL season schedule
+schedule = load_cebl_schedule(2024)
+
+# Preview the data
+print(schedule.head())
+```
+
+---
+
+## Contributing
+
+Found a bug? Have an idea to make ceblpy better? We'd love to hear from you!
+- **Open an issue** on our **[GitHub Issues](https://github.com/ryanndu/ceblpy/issues)** page
+- **Email Me** directly at **[ryandu343@gmail.com](mailto:ryandu343@gmail.com)**
+
+All suggestions and contributions are welcome!
+
+---
+
+## License
+
+`ceblpy` was created by Ryan Du and David Awosoga. It is licensed under the terms of the MIT license.
+
+---
+
+## Credits
+
+`ceblpy` was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) and the `py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).

ceblpy-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ceblpy/__init__.py,sha256=BEMXUVUjrxmZr2QkWknXKXSkSCYqurdFIitKUBigsvM,110
+ceblpy/ceblpy.py,sha256=xref64dSEcDNX6Zsog74KWIDK7kZc7VNkFoHNyrMOuc,21234
+ceblpy/helpers.py,sha256=lCCpS1DBPcO4cJWDHbu8NE_Dw8n6v9wpG0s0yeUtgYs,948
+ceblpy-0.1.0.dist-info/LICENSE,sha256=KCoyVd7Op-r5Ray0mGmDgKiF6z1PCeJ7Rwxplau4Qhs,1088
+ceblpy-0.1.0.dist-info/METADATA,sha256=hr7R90cPQDmmj61137kl5Fts6EYV1DSy94A4MWZtLOY,1992
+ceblpy-0.1.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+ceblpy-0.1.0.dist-info/RECORD,,

ceblpy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any