espn 0.1.3 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MGYxMjBmZGVlZTE0NDM5NWRkNWM3MmQ1Yjg3ODhjOTVkNjQ5ODhjMw==
+    ODhiNTFjZWMxNmZiY2M0NDdlY2EwMTk1ZDI1ZmNiMzE4N2I0NWQzZQ==
   data.tar.gz: !binary |-
-    ODE1YzlmNzA2NmE4YTdmMGRjYzYwYjcxOTA3ZDNiODA0M2FmODU5OA==
+    ZDM5YmFkZTE4OTlhZjg5NmE3OTMyOWIxYWYyOTU0ODNhZjEwZWRiNQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NWNiNjBmMDJjODJmZTg0ZTM5MjBmNDI3MjRmZjdiNmYyNmFlNjllMDY3NmI2
-    ZjY0OGIyNGIwYzg1YTQ5Y2Q2YzY5ZmIxZjg0Nzk3YzFiZWZlMGNmNzU5ZDRm
-    NTFlYWRkOGI2NDU5NzI1Y2U4NGI2N2E2MTI4NDdiMjMwYTdmOGM=
+    ZTY0NDUzYTU3ZmNmMTIyMWRmZTFkNTYxMjBiY2ZkYWFlMmJhMTJkYWZhMDBm
+    NGNmZTMxZTMyMjc4Zjc3NDMzYjI5N2VlZGY3Yzg5MDk5YmFjMmU1ZWEzODkw
+    ZDZhMTZlNmZhY2U4OTFiNmIxYjM5MzQzMGM1NWZmZTdmYTE3NjM=
   data.tar.gz: !binary |-
-    MmFkOThkZTk1ZDZiNDIxYmE0ZmY1MzNiNWFmNWY3M2IwMTMxMjg2NDBiZTJh
-    YzRmOGFjOTdjMjNkZGY0ZTc1NzYxMjdhNzEzMmJmYzc0OWQ2MDcxNDQ2MDRl
-    M2I1N2U4MzYxODhlZTk4ODlhMjFkNTI0NzVhZTE1ZGYyZThjZTM=
+    MzM1MDI4Mzc5M2ZlOWZhYjEyMzJlYzQ4Njg5Zjg4YzBlZDI5NmUyYTgwNTRl
+    N2IzMDBjM2Y5ZTFiMmIwODU5MWRmYzc5MTBkYzY2ZTA0YzUyZTRlMTM1Yzg2
+    YWVlYjZmNzZlNTUzZDZhYzVkNzQ0NzNhZmRlYzVmMjJjZjQ5YzE=

data/README.md

@@ -19,15 +19,100 @@ Next, make calls against the ESPN API.
 
 ### Sports
 
-    sport = client.sports(sport: 'baseball', league: 'mlb').sports.first
-    puts sport.leagues.first.groups.first.name
-    # => American League
+The Sports API is what they call a 'Helper' API. This allows you to pull out data for different sections of the API. The Sports API is not documented, but you can see how it works on their [API explorer.](http://developer.espn.com/io-docs)
+
+    client.sports(:mlb)
+    # => [#<Hashie::Mash name="baseball"...>]
+
+
+### Athletes
+
+For more information about the Athletes API, [view the documentation.](http://developer.espn.com/docs/athletes)
+
+    client.athletes(:mlb)
+    # => [#<Hashie::Mash fullName="Chase Utley"...>]
+
+    client.athlete(12345, :nfl).fullName
+    # => #<Hashie::Mash fullName="LeSean McCoy"...>
+
+### Audio
+
+For more information about the Audio API, [view the documentation.](http://developer.espn.com/docs/audio)
+
+    client.audio(podcast_id: 5)
+    # => [#<Hashie::Mash id=8656148 premium=false description=...>]
+
+### ESPN Now
+
+For more information about the ESPN NOW API, [view the documentation.](http://developer.espn.com/docs/now)
+
+    client.now
+    # => [#<Hashie::Mash headline="Halladay's future"...>]
 
 ### Headlines
 
-    headline = client.headlines(sport: 'baseball', league: 'mlb').headlines.first
-    puts headline.title
-    # => Atlanta Braves outfielder Jason Heyward hit in jaw with pitch
+For more information about the Headlines API, [view the documentation.](http://developer.espn.com/docs/headlines)
+
+    client.headlines(:mlb)
+    # => [#<Hashie::Mash headline="Ronnie Brewer has deal with Rockets"...>]
+
+    client.headline(12345, :nfl)
+    # => #<Hashie::Mash headline="Eagles won't be good this year"...>
+
+### Medals
+
+For more information about the Medals API, [view the documentation.](http://developer.espn.com/docs/medals)
+
+    client.medals
+    # => #<Hashie::Mash season=#<Hashie::Mash...> sports=[] competitors=[]...>
+
+### Research Notes
+
+For more information about the Resarch Notes API, [view the documentation.](http://developer.espn.com/docs/research)
+
+    client.notes
+    # => [#<Hashie::Mash headline="Cowboys Stink"...>]
+
+    client.note(8659824)
+    # => #<Hashie::Mash headline="Cowboys Stink"...>
+
+### Scores & Schedules
+
+For more information about the Scores & Schedules API, [view the documentation.](http://developer.espn.com/docs/scores)
+
+    client.scores(:mlb)
+    # => [#<Hashie::Mash competitions=[#<Hashie::Mash competitors=[]...]...>]
+
+    client.score(12345)
+    # => #<Hashie::Mash competitions=[#<Hashie::Mash competitors=[]...]...>
+
+### Standings
+
+For more information about the Standings API, [view the documentation.](http://developer.espn.com/docs/standings)
+
+    client.standings(:nba)
+    # => [#<Hashie::Mash name="Eastern" groups=[]...>]
+
+### Teams
+
+For more information about the Teams API, [view the documentation.](http://developer.espn.com/docs/teams)
+
+    client.teams(:mlb)
+    # => [#<Hashie::Mash name="Phillies"...>]
+
+    client.team(12345, :nfl)
+    # => #<Hashie::Mash name="Eagles"...>
+
+### Video
+
+For more information about the Video API, [view the documentation.](http://developer.espn.com/docs/video)
+
+    client.videos
+    # => [#<Hashie::Mash name="Video Channel" videos=[]...>]
+
+## More Information
+
+This is a Ruby Wrapper around the ESPN developer API. If you want to see how their API works, you can [visit their developer center.](http://developer.espn.com/overview)
 
 ## Inspiration
 

data/lib/espn.rb

@@ -1,7 +1,12 @@
 require 'espn/configuration'
 require 'espn/client'
 require 'espn/error'
+require 'espn/arguments'
+require 'uri_template'
 
+# Public: The ESPN Module that all other modules and classes will be a part of.
+# This module extends the Configuration module so you can modify defaults at
+# this level.
 module ESPN
   extend Configuration
 

data/lib/espn/arguments.rb

@@ -0,0 +1,41 @@
+require 'espn/mapper'
+require 'espn/helpers'
+
+module ESPN
+
+  # Internal: Extract options from method arguments.
+  class Arguments < Array
+    include ESPN::Mapper
+    include ESPN::Helpers
+
+    # Public: Gets the options Hash.
+    attr_reader :options
+
+    # Public: Initialize an instance of Arguments.
+    #
+    # args      - The Array of arguments passed into a method.
+    # defaults  - The Hash of default values for the options (default: {}).
+    # required  - The Array of fields that are required (default: []).
+    def initialize(args, defaults={}, required=[])
+      @options = args.last.is_a?(::Hash) ? args.pop : {}
+
+      # Set defaults, only if the value in @options is nil.
+      @options.merge!(defaults) { |k, v1, v2| v1 }
+
+      # Extract sport and league
+      @options[:sport], @options[:league] =
+        extract_sport_and_league(args, @options)
+
+      # Validate required fields
+      required.each do |field|
+        if blank?(@options[field.to_sym])
+          raise ArgumentError, "You must supply a valid #{field}."
+        end
+      end
+
+      super(args)
+    end
+
+  end
+
+end

data/lib/espn/client.rb

@@ -1,6 +1,5 @@
-require 'espn/connection'
+require 'espn/helpers'
 require 'espn/request'
-
 require 'espn/client/athletes'
 require 'espn/client/audio'
 require 'espn/client/headlines'
@@ -15,10 +14,35 @@ require 'espn/client/video'
 
 module ESPN
 
+  # Public: The class that handles the bulk of the work between the API and
+  # the wrapper.
+  #
+  # Examples
+  #
+  #   client = ESPN::Client.new(api_key: 'abc123')
+  #   # => ESPN::Client
   class Client
 
-    # Public: An attr_accessor for each configuration option.
-    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+    # Public: Gets/Sets the Symbol adapter.
+    attr_accessor :adapter
+
+    # Public: Gets/Sets the Fixnum api version.
+    attr_accessor :api_version
+
+    # Public: Gets/Sets the String api key.
+    attr_accessor :api_key
+
+    # Public: Gets/Sets the Fixnum open timeout.
+    attr_accessor :open_timeout
+
+    # Public: Gets/Sets the String proxy.
+    attr_accessor :proxy
+
+    # Public: Gets/Sets the Fixnum timeout.
+    attr_accessor :timeout
+
+    # Public: Gets/Sets the String user agent.
+    attr_accessor :user_agent
 
     # Public: Initialize a new Client. To see all options that can be
     # configured, look at the Configuration module, specifically
@@ -47,8 +71,8 @@ module ESPN
       !api_key.nil?
     end
 
-    include ESPN::Connection
     include ESPN::Request
+    include ESPN::Helpers
     include ESPN::Client::Athletes
     include ESPN::Client::Audio
     include ESPN::Client::Headlines

data/lib/espn/client/athletes.rb

@@ -1,32 +1,50 @@
 module ESPN
   class Client
+
+    # Public: The mapping to the ATHLETES API of the ESPN developer API.
+    #
+    # Examples
+    #
+    #   class Client
+    #     include ESPN::Client::Athletes
+    #   end
     module Athletes
 
+      # Public: Get a specific athlete from the ESPN API.
+      #
+      # id      - An id of an athlete.
+      # sport   - A Symbol or String of the sport (optional).
+      # league  - A Symbol or String of the league. If a league is passed, but
+      #           not a sport, an attempt will be made to map the league to a
+      #           sport (required).
+      # opts    - Hash options used to refine the selection. If sport and/or
+      #           league are passed in, they will override the mapped values
+      #           You can find a full list of options on the ESPN developer API
+      #           website (default: {}).
+      #
+      # Returns a Hashie::Mash.
+      def athlete(id, *args)
+        arguments = ESPN::Arguments.new(args, {}, [:league])
+        pattern = "sports/:sport/:league/athletes/#{id}"
+        get(pattern, arguments.options).sports.first.leagues.first.athletes.first
+      end
+
       # Public: Get athlete stats and information from the ESPN API.
       #
-      # opts  - Hash options used to refine the selection (default: {}).
-      #       - :sport        - The name of the sport (default: nil).
-      #       - :league       - The name of the league (default: nil).
-      #       - :athlete_id   - The id of the athlete (default: nil).
+      # sport   - A Symbol or String of the sport (optional).
+      # league  - A Symbol or String of the league. If a league is passed, but
+      #           not a sport, an attempt will be made to map the league to a
+      #           sport (required).
+      # opts    - Hash options used to refine the selection. If sport and/or
+      #           league are passed in, they will override the mapped values
+      #           You can find a full list of options on the ESPN developer API
+      #           website (default: {}).
       #
       # Returns an Array of Hashie::Mash.
-      def athletes(opts={})
-        url = "sports"
-
-        unless opts[:sport].to_s.empty?
-          url += "/#{opts[:sport]}"
-          unless opts[:league].to_s.empty?
-            url += "/#{opts[:league]}"
-          end
-        end
-
-        url += "/athletes"
-
-        unless opts[:athlete_id].to_s.empty?
-          url += "/#{opts[:athlete_id]}"
-        end
-
-        get(url, opts)
+      def athletes(*args)
+        arguments = ESPN::Arguments.new(args, {}, [:league])
+        pattern = "sports/:sport/:league/athletes"
+        get(pattern, arguments.options).sports.first.leagues.first.athletes
       end
 
     end

data/lib/espn/client/audio.rb

@@ -1,35 +1,36 @@
 module ESPN
   class Client
+
+    # Public: The mapping to the AUDIO API of the ESPN developer API.
+    #
+    # Examples
+    #
+    #   class Client
+    #     include ESPN::Client::Audio
+    #   end
     module Audio
 
       # Public: Get audio podcasts and clips from ESPN.
       #
-      # opts  - Hash options used to refine the selection (default: {}).
-      #       - :method         - The name of the sport (default: 'podcasts').
-      #       - :podast_id      - The id of the podcast (default: nil).
-      #       - :recording_id   - The id of the recording (default: nil).
+      # opts    - Hash options used to refine the selection. If sport and/or
+      #           league are passed in, they will override the mapped values
+      #           You can find a full list of options on the ESPN developer API
+      #           website (default: {}).
+      #           :method       - The name of the sport (default: 'podcasts').
+      #           :podcast_id   - The id of the podcast (default: nil).
+      #           :recording_id - The id of the recording (default: nil).
       #
       # Returns an Array of Hashie::Mash.
       def audio(opts={})
-        opts [:method] ||= 'podcasts'
-
-        url = 'audio'
+        opts[:method] ||= 'podcasts'
 
+        # Correct invalid method.
         if opts[:method] == 'podcast_recordings'
-          url += '/podcasts/recordings'
-        else
-          url += "/#{opts[:method]}"
-        end
-
-        unless opts[:podcast_id].to_s.empty?
-          url += "/#{opts[:podcast_id]}"
-        end
-
-        unless opts[:recording_id].to_s.empty?
-          url += "/#{opts[:recording_id]}"
+          opts[:method] = 'podcasts/recordings'
         end
 
-        get(url, opts)
+        pattern = "audio/#{opts[:method]}/:podcast_id/:recording_id"
+        get(pattern, opts).recordings
       end
 
     end

data/lib/espn/client/headlines.rb

@@ -1,38 +1,69 @@
 module ESPN
   class Client
+
+    # Public: The mapping to the HEADLINES API of the ESPN developer API.
+    #
+    # Examples
+    #
+    #   class Client
+    #     include ESPN::Client::Headlines
+    #   end
     module Headlines
 
+      # Public: Get a specific headline from the ESPN API.
+      #
+      # id    - The id of the headline to get.
+      # opts  - Hash options used to refine the selection. You can find the full
+      #         list of options on the ESPN developer API website (default: {}).
+      #
+      # Examples:
+      #
+      #   client.headline(12345)
+      #   # Request made to 'sports/news/12345'
+      #
+      # Returns a Hashie::Mash.
+      def headline(id, opts={})
+        get("sports/news/#{id}", opts).headlines.first
+      end
+
       # Public: Get latest sports news and analysis from the ESPN API.
       #
-      # opts  - Hash options used to refine the selection (default: {}).
-      #       - :section      - The news section (default: 'sports').
-      #       - :sport        - The name of the sport (default: nil).
-      #       - :league       - The name of the league (default: nil).
-      #       - :method       - The method of headlines (default: nil).
-      #       - :headline_id  - The id of a specific headline (default: nil).
+      # sport   - A Symbol or String of the sport (optional).
+      # league  - A Symbol or String of the league. If a league is passed, but
+      #           not a sport, an attempt will be made to map the league to a
+      #           sport (optional).
+      # opts    - Hash options used to refine the selection. If sport and/or
+      #           league are passed in, they will override the mapped values
+      #           You can find a full list of options on the ESPN developer API
+      #           website (default: {}).
+      #           :section  - The news section (default: 'sports').
+      #           :sport    - Name of the sport (default: nil, optional).
+      #           :league   - Name of the league (default: nil, optional).
+      #           :method   - Method of headlines (default: nil, optional).
+      #
+      # Examples
+      #
+      #   client.headlines(:mlb)
+      #   # Request made to 'sports/baseball/mlb/news'
+      #
+      #   client.headlines('baseball')
+      #   # Request will be made to 'sports/baseball/news'
+      #
+      #   client.headlines('horse-racing', :mlb)
+      #   # Request will be made to 'sports/horse-racing/mlb/news'
+      #
+      #   client.headlines(:mlb, sport: 'basketball')
+      #   # Request will be made to 'sports/basketball/mlb/news'
+      #
+      #   client.headlines(:baseball, :mlb, sport: 'basketball', league: 'nba')
+      #   # Request will be made to 'sports/basketball/nba/news'
       #
       # Returns an Array of Hashie::Mash.
-      def headlines(opts={})
-        url = opts[:section] || 'sports'
-
-        unless opts[:sport].to_s.empty?
-          url += "/#{opts[:sport]}"
-          unless opts[:league].to_s.empty?
-            url += "/#{opts[:league]}"
-          end
-        end
-
-        url += '/news'
-
-        unless opts[:method].to_s.empty?
-          url += "/headlines/#{opts[:method]}"
-        end
-
-        unless opts[:headline_id].to_s.empty?
-          url += "/#{opts[:headline_id]}"
-        end
-
-        get(url, opts)
+      def headlines(*args)
+        arguments = ESPN::Arguments.new(args, section: 'sports')
+        pattern = arguments.options[:section]
+        pattern += '/:sport/:league/news/headlines/:method/:id'
+        get(pattern, arguments.options).headlines
       end
 
     end