nba 0.1.1 → 0.2.0

data/lib/nba/player.rb

@@ -1,28 +1,246 @@
+require "equalizer"
+require "shale"
+require_relative "team"
+require_relative "position"
+
 module NBA
-  class Player
-    attr_reader :name, :number, :positions, :from, :to
-
-    def initialize(attributes = {})
-      attributes.each do |key, value|
-        instance_variable_set("@#{key}", value) if self.respond_to?(key)
-      end
-    end
-
-    def pretty_print
-      "#{self.name}, number #{self.number}, position: #{self.positions.join(', ')}"
-    end
-
-    # Returns an array of Player objects given a team roster
-    def self.all_from_roster(players)
-      players.select{ |player| player['to'].nil? }.map do |player|
-        new(
-          :name      => player['player'],
-          :number    => player['number'].to_i,
-          :positions => player['position'],
-          :from      => player['from'].to_i,
-          :to        => "Present"
-        )
-      end
+  # Represents an NBA player
+  class Player < Shale::Mapper
+    include Equalizer.new(:id)
+
+    # @!attribute [rw] id
+    #   Returns the unique identifier for the player
+    #   @api public
+    #   @example
+    #     player.id #=> 2544
+    #   @return [Integer] the unique identifier for the player
+    attribute :id, Shale::Type::Integer
+
+    # @!attribute [rw] full_name
+    #   Returns the player's full name
+    #   @api public
+    #   @example
+    #     player.full_name #=> "LeBron James"
+    #   @return [String] the player's full name
+    attribute :full_name, Shale::Type::String
+
+    # @!attribute [rw] first_name
+    #   Returns the player's first name
+    #   @api public
+    #   @example
+    #     player.first_name #=> "LeBron"
+    #   @return [String] the player's first name
+    attribute :first_name, Shale::Type::String
+
+    # @!attribute [rw] last_name
+    #   Returns the player's last name
+    #   @api public
+    #   @example
+    #     player.last_name #=> "James"
+    #   @return [String] the player's last name
+    attribute :last_name, Shale::Type::String
+
+    # @!attribute [rw] is_active
+    #   Returns whether the player is currently active
+    #   @api public
+    #   @example
+    #     player.is_active #=> true
+    #   @return [Boolean] whether the player is currently active
+    attribute :is_active, Shale::Type::Boolean
+
+    # @!attribute [rw] jersey_number
+    #   Returns the player's jersey number
+    #   @api public
+    #   @example
+    #     player.jersey_number #=> 23
+    #   @return [Integer] the player's jersey number
+    attribute :jersey_number, Shale::Type::Integer
+
+    # @!attribute [rw] position
+    #   Returns the player's position
+    #   @api public
+    #   @example
+    #     player.position #=> #<NBA::Position>
+    #   @return [Position] the player's position
+    attribute :position, Position
+
+    # @!attribute [rw] height
+    #   Returns the player's height
+    #   @api public
+    #   @example
+    #     player.height #=> "6-9"
+    #   @return [String] the player's height
+    attribute :height, Shale::Type::String
+
+    # @!attribute [rw] weight
+    #   Returns the player's weight
+    #   @api public
+    #   @example
+    #     player.weight #=> 250
+    #   @return [Integer] the player's weight
+    attribute :weight, Shale::Type::Integer
+
+    # @!attribute [rw] college
+    #   Returns the player's college
+    #   @api public
+    #   @example
+    #     player.college #=> "St. Vincent-St. Mary HS (OH)"
+    #   @return [String] the player's college
+    attribute :college, Shale::Type::String
+
+    # @!attribute [rw] country
+    #   Returns the player's country
+    #   @api public
+    #   @example
+    #     player.country #=> "USA"
+    #   @return [String] the player's country
+    attribute :country, Shale::Type::String
+
+    # @!attribute [rw] draft_year
+    #   Returns the year the player was drafted
+    #   @api public
+    #   @example
+    #     player.draft_year #=> 2003
+    #   @return [Integer] the year the player was drafted
+    attribute :draft_year, Shale::Type::Integer
+
+    # @!attribute [rw] draft_round
+    #   Returns the round the player was drafted
+    #   @api public
+    #   @example
+    #     player.draft_round #=> 1
+    #   @return [Integer] the round the player was drafted
+    attribute :draft_round, Shale::Type::Integer
+
+    # @!attribute [rw] draft_number
+    #   Returns the number the player was drafted
+    #   @api public
+    #   @example
+    #     player.draft_number #=> 1
+    #   @return [Integer] the number the player was drafted
+    attribute :draft_number, Shale::Type::Integer
+
+    # @!attribute [rw] team
+    #   Returns the player's current team
+    #   @api public
+    #   @example
+    #     player.team #=> #<NBA::Team>
+    #   @return [Team] the player's current team
+    attribute :team, Team
+
+    alias_method :active?, :is_active
+
+    # Returns whether the player is a point guard
+    #
+    # @api public
+    # @example
+    #   player.point_guard? #=> true
+    # @return [Boolean] true if the player is a point guard
+    def point_guard?
+      position_matches?("PG", "Point Guard")
+    end
+
+    # Returns whether the player is a shooting guard
+    #
+    # @api public
+    # @example
+    #   player.shooting_guard? #=> true
+    # @return [Boolean] true if the player is a shooting guard
+    def shooting_guard?
+      position_matches?("SG", "Shooting Guard")
+    end
+
+    # Returns whether the player is a guard
+    #
+    # @api public
+    # @example
+    #   player.guard? #=> true
+    # @return [Boolean] true if the player is a guard (point guard or shooting guard)
+    def guard?
+      point_guard? || shooting_guard? || position_matches?("G", "Guard")
+    end
+
+    # Returns whether the player is a small forward
+    #
+    # @api public
+    # @example
+    #   player.small_forward? #=> true
+    # @return [Boolean] true if the player is a small forward
+    def small_forward?
+      position_matches?("SF", "Small Forward")
+    end
+
+    # Returns whether the player is a power forward
+    #
+    # @api public
+    # @example
+    #   player.power_forward? #=> true
+    # @return [Boolean] true if the player is a power forward
+    def power_forward?
+      position_matches?("PF", "Power Forward")
+    end
+
+    # Returns whether the player is a forward
+    #
+    # @api public
+    # @example
+    #   player.forward? #=> true
+    # @return [Boolean] true if the player is a forward (small forward or power forward)
+    def forward?
+      small_forward? || power_forward? || position_matches?("F", "Forward")
+    end
+
+    # Returns whether the player is a center
+    #
+    # @api public
+    # @example
+    #   player.center? #=> true
+    # @return [Boolean] true if the player is a center
+    def center?
+      position_matches?("C", "Center")
+    end
+
+    json do
+      map "id", to: :id
+      map "person_id", to: :id
+      map "personId", to: :id
+      map "full_name", to: :full_name
+      map "fullName", to: :full_name
+      map "display_first_last", to: :full_name
+      map "displayFirstLast", to: :full_name
+      map "first_name", to: :first_name
+      map "firstName", to: :first_name
+      map "last_name", to: :last_name
+      map "lastName", to: :last_name
+      map "is_active", to: :is_active
+      map "isActive", to: :is_active
+      map "jersey", to: :jersey_number
+      map "jerseyNum", to: :jersey_number
+      map "position", to: :position
+      map "pos", to: :position
+      map "height", to: :height
+      map "weight", to: :weight
+      map "college", to: :college
+      map "country", to: :country
+      map "draft_year", to: :draft_year
+      map "draftYear", to: :draft_year
+      map "draft_round", to: :draft_round
+      map "draftRound", to: :draft_round
+      map "draft_number", to: :draft_number
+      map "draftNumber", to: :draft_number
+      map "team", to: :team
+    end
+
+    private
+
+    # Returns whether the player's position matches the given abbreviation or name
+    #
+    # @api private
+    # @return [Boolean]
+    def position_matches?(abbreviation, name)
+      return false unless position
+
+      position.abbreviation.eql?(abbreviation) || position.name.eql?(name)
     end
   end
 end

data/lib/nba/player_awards.rb

@@ -0,0 +1,110 @@
+require "json"
+require_relative "client"
+require_relative "collection"
+
+require_relative "award"
+
+module NBA
+  # Provides methods to retrieve player awards
+  module PlayerAwards
+    # Result set name for player awards
+    # @return [String] the result set name
+    PLAYER_AWARDS = "PlayerAwards".freeze
+
+    # Retrieves all awards for a player
+    #
+    # @api public
+    # @example
+    #   awards = NBA::PlayerAwards.find(player: 201939)
+    #   awards.each { |a| puts "#{a.season}: #{a.description}" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of awards
+    def self.find(player:, client: CLIENT)
+      player_id = extract_player_id(player)
+      path = "playerawards?PlayerID=#{player_id}"
+      response = client.get(path)
+      parse_response(response, player_id)
+    end
+
+    # Parses the API response into award objects
+    # @api private
+    # @return [Collection] collection of awards
+    def self.parse_response(response, player_id)
+      return Collection.new unless response
+
+      data = JSON.parse(response)
+      result_set = find_result_set(data)
+      return Collection.new unless result_set
+
+      headers = result_set["headers"]
+      rows = result_set["rowSet"]
+      return Collection.new unless headers && rows
+
+      awards = rows.map { |row| build_award(headers, row, player_id) }
+      Collection.new(awards)
+    end
+    private_class_method :parse_response
+
+    # Finds the player awards result set in the response
+    # @api private
+    # @return [Hash, nil] the result set hash
+    def self.find_result_set(data)
+      result_sets = data["resultSets"]
+      return unless result_sets
+
+      result_sets.find { |rs| rs["name"].eql?(PLAYER_AWARDS) }
+    end
+    private_class_method :find_result_set
+
+    # Builds an Award object from raw data
+    # @api private
+    # @return [Award] the award object
+    def self.build_award(headers, row, player_id)
+      data = headers.zip(row).to_h
+      Award.new(**award_attributes(data, player_id))
+    end
+    private_class_method :build_award
+
+    # Combines all award attributes
+    # @api private
+    # @return [Hash] the combined attributes
+    def self.award_attributes(data, player_id)
+      identity_attributes(data, player_id).merge(award_info_attributes(data))
+    end
+    private_class_method :award_attributes
+
+    # Extracts identity attributes from data
+    # @api private
+    # @return [Hash] identity attributes
+    def self.identity_attributes(data, player_id)
+      {player_id: player_id, first_name: data.fetch("FIRST_NAME"), last_name: data.fetch("LAST_NAME"),
+       team: data.fetch("TEAM"), description: data.fetch("DESCRIPTION")}
+    end
+    private_class_method :identity_attributes
+
+    # Extracts award info attributes from data
+    # @api private
+    # @return [Hash] award info attributes
+    def self.award_info_attributes(data)
+      {all_nba_team_number: data.fetch("ALL_NBA_TEAM_NUMBER"), season: data.fetch("SEASON"),
+       month: data.fetch("MONTH"), week: data.fetch("WEEK"), conference: data.fetch("CONFERENCE"),
+       award_type: data.fetch("TYPE"), subtype1: data.fetch("SUBTYPE1"),
+       subtype2: data.fetch("SUBTYPE2"), subtype3: data.fetch("SUBTYPE3")}
+    end
+    private_class_method :award_info_attributes
+
+    # Extracts player ID from a Player object or returns the integer
+    #
+    # @api private
+    # @param player [Player, Integer] the player or player ID
+    # @return [Integer] the player ID
+    def self.extract_player_id(player)
+      case player
+      when Player then player.id
+      else player
+      end
+    end
+    private_class_method :extract_player_id
+  end
+end

data/lib/nba/player_career_by_college.rb

@@ -0,0 +1,86 @@
+require_relative "client"
+require_relative "response_parser"
+
+require_relative "college_player_stat"
+
+module NBA
+  # Provides methods to retrieve player career stats by college
+  module PlayerCareerByCollege
+    # Per mode constant for per game stats
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Retrieves career statistics for all players from a specific college
+    #
+    # @api public
+    # @example
+    #   # Get all players from Duke
+    #   stats = NBA::PlayerCareerByCollege.find(college: "Duke")
+    #   stats.each { |s| puts "#{s.player_name}: #{s.pts} career points" }
+    #
+    # @example
+    #   # Get per-game averages
+    #   stats = NBA::PlayerCareerByCollege.find(college: "Kentucky", per_mode: NBA::PlayerCareerByCollege::PER_GAME)
+    #
+    # @param college [String] the college name (required)
+    # @param per_mode [String] the per mode (Totals or PerGame)
+    # @param season [String, nil] optional season filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of college player stats
+    def self.find(college:, per_mode: TOTALS, season: nil, client: CLIENT)
+      path = build_path(college, per_mode, season)
+      ResponseParser.parse(client.get(path)) { |data| build_stat(data) }
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(college, per_mode, season)
+      season_param = "&SeasonNullable=#{season}" if season
+      "playercareerbycollege?College=#{college}&LeagueID=00" \
+        "&PerModeSimple=#{per_mode}&SeasonTypeAllStar=Regular+Season#{season_param}"
+    end
+    private_class_method :build_path
+
+    # Builds a college player stat from API data
+    # @api private
+    # @return [CollegePlayerStat]
+    def self.build_stat(data)
+      CollegePlayerStat.new(**identity_info(data), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       college: data["COLLEGE"], gp: data["GP"], min: data["MIN"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts shooting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_stats
+
+    # Extracts counting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"]}
+    end
+    private_class_method :counting_stats
+  end
+end

data/lib/nba/player_career_by_college_rollup.rb

@@ -0,0 +1,143 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "player_career_by_college"
+
+module NBA
+  # Provides methods to retrieve player career stats aggregated by college region
+  module PlayerCareerByCollegeRollup
+    # Per mode constant for per game stats
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Per mode constant for totals
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Result set name for East region colleges
+    # @return [String] the result set name
+    EAST = "East".freeze
+
+    # Result set name for Midwest region colleges
+    # @return [String] the result set name
+    MIDWEST = "Midwest".freeze
+
+    # Result set name for South region colleges
+    # @return [String] the result set name
+    SOUTH = "South".freeze
+
+    # Result set name for West region colleges
+    # @return [String] the result set name
+    WEST = "West".freeze
+
+    # Retrieves career statistics for players from East region colleges
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerCareerByCollegeRollup.east
+    #   stats.each { |s| puts "#{s.player_name} (#{s.college}): #{s.pts} career points" }
+    #
+    # @param per_mode [String] the per mode (Totals or PerGame)
+    # @param season [String, nil] optional season filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of college player stats
+    def self.east(per_mode: TOTALS, season: nil, client: CLIENT)
+      path = build_path(per_mode, season)
+      ResponseParser.parse(client.get(path), result_set: EAST) { |data| build_stat(data) }
+    end
+
+    # Retrieves career statistics for players from Midwest region colleges
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerCareerByCollegeRollup.midwest
+    #   stats.each { |s| puts "#{s.player_name} (#{s.college}): #{s.pts} career points" }
+    #
+    # @param per_mode [String] the per mode (Totals or PerGame)
+    # @param season [String, nil] optional season filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of college player stats
+    def self.midwest(per_mode: TOTALS, season: nil, client: CLIENT)
+      path = build_path(per_mode, season)
+      ResponseParser.parse(client.get(path), result_set: MIDWEST) { |data| build_stat(data) }
+    end
+
+    # Retrieves career statistics for players from South region colleges
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerCareerByCollegeRollup.south
+    #   stats.each { |s| puts "#{s.player_name} (#{s.college}): #{s.pts} career points" }
+    #
+    # @param per_mode [String] the per mode (Totals or PerGame)
+    # @param season [String, nil] optional season filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of college player stats
+    def self.south(per_mode: TOTALS, season: nil, client: CLIENT)
+      path = build_path(per_mode, season)
+      ResponseParser.parse(client.get(path), result_set: SOUTH) { |data| build_stat(data) }
+    end
+
+    # Retrieves career statistics for players from West region colleges
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerCareerByCollegeRollup.west
+    #   stats.each { |s| puts "#{s.player_name} (#{s.college}): #{s.pts} career points" }
+    #
+    # @param per_mode [String] the per mode (Totals or PerGame)
+    # @param season [String, nil] optional season filter
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of college player stats
+    def self.west(per_mode: TOTALS, season: nil, client: CLIENT)
+      path = build_path(per_mode, season)
+      ResponseParser.parse(client.get(path), result_set: WEST) { |data| build_stat(data) }
+    end
+
+    # Builds the API request path
+    # @api private
+    # @return [String] the request path
+    def self.build_path(per_mode, season)
+      season_param = "&SeasonNullable=#{season}" if season
+      "playercareerbycollegerollup?LeagueID=00" \
+        "&PerModeSimple=#{per_mode}&SeasonTypeAllStar=Regular+Season#{season_param}"
+    end
+    private_class_method :build_path
+
+    # Builds a college player stat from API data
+    # @api private
+    # @return [CollegePlayerStat]
+    def self.build_stat(data)
+      CollegePlayerStat.new(**identity_info(data), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_stat
+
+    # Extracts identity information from data
+    # @api private
+    # @return [Hash]
+    def self.identity_info(data)
+      {player_id: data["PLAYER_ID"], player_name: data["PLAYER_NAME"],
+       college: data["COLLEGE"], gp: data["GP"], min: data["MIN"]}
+    end
+    private_class_method :identity_info
+
+    # Extracts shooting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_stats
+
+    # Extracts counting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"]}
+    end
+    private_class_method :counting_stats
+  end
+end

data/lib/nba/player_career_stats.rb

@@ -0,0 +1,77 @@
+require_relative "client"
+require_relative "response_parser"
+require_relative "career_stats"
+require_relative "utils"
+
+module NBA
+  # Provides methods to retrieve player career statistics
+  module PlayerCareerStats
+    # Regular season per game stats type
+    # @return [String] the per mode
+    PER_GAME = "PerGame".freeze
+
+    # Totals stats type
+    # @return [String] the per mode
+    TOTALS = "Totals".freeze
+
+    # Result set name for regular season stats
+    # @return [String] the result set name
+    RESULT_SET_NAME = "SeasonTotalsRegularSeason".freeze
+
+    # Retrieves career statistics for a player
+    #
+    # @api public
+    # @example
+    #   stats = NBA::PlayerCareerStats.find(player: 201939)
+    #   stats.each { |s| puts "#{s.season_id}: #{s.pts} PPG" }
+    # @param player [Integer, Player] the player ID or Player object
+    # @param per_mode [String] the per mode (PerGame, Totals)
+    # @param client [Client] the API client to use
+    # @return [Collection] a collection of career stats by season
+    def self.find(player:, per_mode: PER_GAME, client: CLIENT)
+      player_id = Utils.extract_id(player)
+      path = "playercareerstats?PlayerID=#{player_id}&PerMode=#{per_mode}"
+      ResponseParser.parse(client.get(path), result_set: RESULT_SET_NAME) do |data|
+        build_career_stats(data, player_id)
+      end
+    end
+
+    # Builds career stats from API data
+    # @api private
+    # @return [CareerStats]
+    def self.build_career_stats(data, player_id)
+      CareerStats.new(**season_info(data, player_id), **shooting_stats(data), **counting_stats(data))
+    end
+    private_class_method :build_career_stats
+
+    # Extracts season information from data
+    # @api private
+    # @return [Hash]
+    def self.season_info(data, player_id)
+      {player_id: player_id, season_id: data["SEASON_ID"], team_id: data["TEAM_ID"],
+       team_abbreviation: data["TEAM_ABBREVIATION"], player_age: data["PLAYER_AGE"],
+       gp: data["GP"], gs: data["GS"], min: data["MIN"]}
+    end
+    private_class_method :season_info
+
+    # Extracts shooting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.shooting_stats(data)
+      {fgm: data["FGM"], fga: data["FGA"], fg_pct: data["FG_PCT"],
+       fg3m: data["FG3M"], fg3a: data["FG3A"], fg3_pct: data["FG3_PCT"],
+       ftm: data["FTM"], fta: data["FTA"], ft_pct: data["FT_PCT"]}
+    end
+    private_class_method :shooting_stats
+
+    # Extracts counting statistics from data
+    # @api private
+    # @return [Hash]
+    def self.counting_stats(data)
+      {oreb: data["OREB"], dreb: data["DREB"], reb: data["REB"],
+       ast: data["AST"], stl: data["STL"], blk: data["BLK"],
+       tov: data["TOV"], pf: data["PF"], pts: data["PTS"]}
+    end
+    private_class_method :counting_stats
+  end
+end