kappa 0.1.5.pre → 0.2.0

data/README.md

@@ -1,16 +1,16 @@
 # <img src="https://raw.github.com/schmich/kappa/master/assets/kappa.png" /> Kappa
 
-Kappa is a Ruby library for interfacing with the [Twitch.tv API](https://github.com/justintv/Twitch-API).
+Kappa is the Ruby library for interfacing with the [Twitch.tv API](https://github.com/justintv/Twitch-API).
 
-[![Gem Version](https://badge.fury.io/rb/kappa.png)](https://badge.fury.io/rb/kappa.png)
-[![Build Status](https://secure.travis-ci.org/schmich/tome.png)](http://travis-ci.org/schmich/tome)
+[![Gem Version](https://badge.fury.io/rb/kappa.png)](http://rubygems.org/gems/kappa)
+[![Build Status](https://secure.travis-ci.org/schmich/kappa.png)](http://travis-ci.org/schmich/kappa)
 [![Dependency Status](https://gemnasium.com/schmich/kappa.png)](https://gemnasium.com/schmich/kappa)
 [![Coverage Status](https://coveralls.io/repos/schmich/kappa/badge.png?branch=master)](https://coveralls.io/r/schmich/kappa?branch=master)
 [![Code Climate](https://codeclimate.com/github/schmich/kappa.png)](https://codeclimate.com/github/schmich/kappa)
 
 ## Getting Started
 
-`gem install kappa --pre`
+`gem install kappa`
 
 ```ruby
 require 'kappa'
@@ -23,60 +23,124 @@ puts grubby.streaming?
 
 ## Examples
 
-### Channels
+### <a id="channels"></a>Channels
 
 Channels serve as the home location for a [user's](#users) content. Channels have a [stream](#streams), can run commercials, store [videos](#videos), display information and status, and have a customized page including banners and backgrounds.
 
+See also [`Kappa::V2::Channel`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Channel) documentation.
+
 ```ruby
 c = Channel.get('destiny')
-
-c.nil?                # Does the requested channel not exist? (ex: false)
-c.name                # Unique Twitch name (ex: "destiny")
-c.display_name        # Display name, e.g. name used for page title (ex: "Destiny")
-c.stream              # The currently live stream for this channel (ex: #<Kappa::V2::Stream> object)
-c.url                 # The URL for the channel's main page (ex: "http://www.twitch.tv/destiny")
-c.status              # Current status (ex: "Destiny - Diamond I ADC  - Number 1 Draven player in the entire Omaha (NE) metro area -watch from http://www.destiny.gg")
-c.streaming?          # Is the channel currently streaming? (ex: true)
-c.game_name           # Name of the primary game for this channel (ex: "League of Legends")
-c.mature?             # Does the channel have mature content? (ex: true)
-c.id                  # Unique Twitch ID (ex: 18074328)
-c.created_at          # When the channel was created (ex: #<DateTime: 2010-11-22T04:14:56+00:00 ((2455523j,15296s,0n),+0s,2299161j)>)
-c.updated_at          # When the channel was last updated, e.g. last stream time (ex: #<DateTime: 2013-05-11T19:57:29+00:00 ((2456424j,71849s,0n),+0s,2299161j)>)
-c.background_url      # URL for background image (ex: "http://static-cdn.jtvnw.net/jtv_user_pictures/destiny-channel_background_image-ab706db77853e079.jpeg")
-c.banner_url          # URL for banner image (ex: "http://static-cdn.jtvnw.net/jtv_user_pictures/destiny-channel_header_image-d2b9b2452f67ec00-640x125.jpeg")
-c.logo_url            # URL for logo image (ex: "http://static-cdn.jtvnw.net/jtv_user_pictures/destiny-profile_image-168e66661c484c5e-300x300.jpeg")
-c.video_banner_url    # URL for the image shown when the stream is offline (ex: "http://static-cdn.jtvnw.net/jtv_user_pictures/destiny-channel_offline_image-7a21fd1bd88c4ac3-640x360.jpeg")
-
-c.videos
-c.teams
-c.subscribers
-c.editors
-c.followers
-c.has_subscriber?
+c.nil?        # => false (channel exists)
+c.stream      # => #<Kappa::V2::Stream> (current live stream)
+c.url         # => "http://www.twitch.tv/destiny"
+c.status      # => "Destiny - Diamond I ADC  - Number 1 Draven player..."
+c.teams       # => [#<Kappa::V2::Team>]      
+c.videos      # => [#<Kappa::V2::Video>, ...]
+c.followers   # => [#<Kappa::V2::User>, ...]
 ```
 
-### Streams
+### <a id="streams"></a>Streams
+
+Streams are video broadcasts that are currently live. They belong to a [user](#users) and are part of a [channel](#channels).
 
-Streams are video broadcasts that are currently live. They have a [broadcaster](#users) and are part of a [channel](#channels).
+See also [`Kappa::V2::Stream`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Stream) and [`Kappa::V2::Streams`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Streams) documentation.
 
-### Users
+```ruby
+s = Stream.get('idrajit')
+s.nil?          # => false (currently live)
+s.game_name     # => "StarCraft II: Heart of the Swarm"
+s.viewer_count  # => 7267
+s.channel.url   # => "http://www.twitch.tv/idrajit"
+```
+
+### <a id="users"></a>Users
 
 These are members of the Twitch community who have a Twitch account. If broadcasting, they can own a [stream](#streams) that they can broadcast on their [channel](#channels). If mainly viewing, they might follow or subscribe to channels.
 
-### Videos
+See also [`Kappa::V2::User`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/User) documentation.
+
+```ruby
+u = User.get('snoopeh')
+u.nil?                    # => false (user exists)
+u.channel                 # => #<Kappa::V2::Channel>
+u.following.map(&:name)   # => ["national_esl1", "dreamhacklol", "riotgames"]
+```
+
+### <a id="videos"></a>Videos
 
 Videos are broadcasts or highlights owned by a [channel](#channels). Broadcasts are unedited videos that are saved after a streaming session. Highlights are videos edited from broadcasts by the channel's owner.
 
-### Teams
+See also [`Kappa::V2::Video`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Video) and [`Kappa::V2::Videos`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Videos) documentation.
+
+```ruby
+v = Video.get('a395995729')
+v.nil?          # => false (video exists)
+v.title         # => "DreamHack Open Stockholm 26-27 April"
+v.game_name     # => "StarCraft II: Heart of the Swarm"
+v.recorded_at   # => #<DateTime: 2013-04-26T18:33:48+00:00>
+v.view_count    # => 12506
+```
+
+### <a id="teams"></a>Teams
 
 Teams are an organization of [channels](#channels).
 
-### Games
+See also [`Kappa::V2::Team`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Team) documentation.
+
+```ruby
+t = Team.get('teamliquid')
+t.display_name  # => "TeamLiquid"
+t.info          # => "TeamLiquid is awesome. and esports. video games. \n\n"
+t.updated_at    # => #<DateTime: 2013-04-27T16:58:55+00:00>
+```
+
+### <a id="games"></a>Games
 
 Games are categories (e.g. League of Legends, Diablo 3) used by [streams](#streams) and [channels](#channels). Games can be searched for by query.
 
+See also [`Kappa::V2::Game`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Game), [`Kappa::V2::Games`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/Games), and [`Kappa::V2::GameSuggestion`](http://rdoc.info/github/schmich/kappa/master/Kappa/V2/GameSuggestion) documentation.
+
+```ruby
+top = Games.top(:limit => 3)
+top.map(&:name)  # => ["League of Legends", "Dota 2", "StarCraft II: Heart of the Swarm"]
+```
+
+```ruby
+g = Games.top(:limit => 1).first
+g.name                   # => "League of Legends"
+g.channel_count          # => 906
+g.viewer_count           # => 79223
+g.box_images.medium_url  # =>"http://static-cdn.jtvnw.net/ttv-boxart/League%20of%20Legends-272x380.jpg"
+```
+
+```ruby
+s = Games.find(:name => 'diablo', :live => true)
+s.map(&:name)        # => ["Diablo III", "Diablo II", "Diablo", "Diablo II: Lord of Destruction"]
+s.map(&:popularity)  # => [120, 4, 1, 1]
+```
+
+## Documentation
+
+Detailed API documentation is available at [http://rdoc.info/github/schmich/kappa/master/frames](http://rdoc.info/github/schmich/kappa/master/frames).
+
+## Versioning
+
+- TODO: Semantic versioning
+- TODO: Twitch API versions
+
 ## Contributing
 
+- [Fork and clone the repo.](http://help.github.com/fork-a-repo/)
+- [Create a branch for your changes.](http://learn.github.com/p/branching.html)
+- Run `bundle install` to install development requirements.
+- Implement your feature or bug fix.
+- Add specs under the `spec` folder to prevent regressions or to test new code.
+- Add [YARD](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md) documentation for new features. Run `rake yard` to view documentation.
+- Run `rake coverage` to run specs with code coverage. All specs must pass; coverage must remain at 100%.
+- Commit and push your changes.
+- [Submit a pull request.](http://help.github.com/send-pull-requests/)
+
 ## License
 
 Copyright &copy; 2013 Chris Schmich

data/lib/kappa.rb

@@ -9,81 +9,3 @@ require 'kappa/user'
 require 'kappa/images'
 require 'kappa/twitch'
 require 'kappa/version'
-
-# TODO
-# https://github.com/justintv/Twitch-API
-# Blocks
-#   GET /users/:login/blocks
-#   PUT /users/:user/blocks/:target
-#   DELETE /users/:user/blocks/:target
-# Channels
-#   - GET /channels/:channel
-#   GET /channel
-#   GET /channels/:channel/editors
-#   PUT /channels/:channel
-#   GET /channels/:channel/videos
-#   GET /channels/:channel/follows
-#   DELETE /channels/:channel/stream_key
-#   POST /channels/:channel/commercial
-# Chat
-#   GET /chat/:channel
-#   GET /chat/emoticons
-# Follows
-#   GET /channels/:channel/follows
-#   GET /users/:user/follows/channels
-#   GET /users/:user/follows/channels/:target
-#   PUT /users/:user/follows/channels/:target
-#   DELETE /users/:user/follows/channels/:target
-# Games
-#   - GET /games/top
-# Ingests
-#   GET /ingests
-# Root
-#   GET /
-# Search
-#   GET /search/streams
-#   - GET /search/games
-# Streams
-#   - GET /streams/:channel
-#   - GET /streams
-#   GET /streams/featured
-#   GET /streams/summary
-#   GET /streams/followed
-# Subscriptions
-#   GET /channels/:channel/subscriptions
-#   GET /channels/:channel/subscriptions/:user
-# Teams
-#   GET /teams
-#   GET /teams/:team
-# Users
-#   GET /users/:user
-#   GET /user
-#   GET /streams/followed
-# Videos
-#   GET /videos/:id
-#   GET /videos/top
-#   GET /channels/:channel/videos
-
-# Overarching
-# - Common query syntax
-# - Access to raw properties (e.g. stream['game'] or stream.raw('game'))
-# - Paginated results take a block to allow for intermediate processing/termination
-
-# t = Kappa::Client.new
-# c = t.channel('lagtvmaximusblack')
-# c.editors -> [...]
-# c.videos -> [...]
-# c.followers -> [...]
-# c.subscriptions
-# c.start_commercial
-# c.reset_stream_key
-# c... ; c.save! 
-# TODO: current user channel
-
-# t = Kappa::Client.new
-# t.streams.all
-# t.streams.all(:limit => 10)
-# t.streams.featured
-# t.streams.where(:channel => 'lagtvmaximusblack')
-# t.streams.where(:channel => [...], :game => '...', :embeddable => t/f, :hls => t/f)
-# t.stream_summary

data/lib/kappa/channel.rb

@@ -1,24 +1,13 @@
 require 'cgi'
 
-module Kappa
-  # @private
-  class ChannelBase
-    include IdEquality
-
-    def self.get(channel_name)
-      encoded_name = CGI.escape(channel_name)
-      json = connection.get("channels/#{encoded_name}")
-      if !json || json['status'] == 404
-        nil
-      else
-        new(json)
-      end
-    end
-  end
-end
-
 module Kappa::V2
-  class Channel < Kappa::ChannelBase
+  # Channels serve as the home location for a user's content. Channels have a stream, can run
+  # commercials, store videos, display information and status, and have a customized page including
+  # banners and backgrounds.
+  # @see .get Channel.get
+  # @see Stream
+  # @see User
+  class Channel
     # TODO:
     # c.subscriptions
     # c.start_commercial
@@ -26,7 +15,9 @@ module Kappa::V2
     # c.foo = 'bar' ; c.save!
     # Current user's channel
     include Connection
+    include Kappa::IdEquality
 
+    # @private
     def initialize(hash)
       @id = hash['_id']
       @background_url = hash['background']
@@ -49,7 +40,22 @@ module Kappa::V2
       end
     end
 
-    # This flag is specified by the owner of the channel.
+    # Get a channel by name.
+    # @param channel_name [String] The name of the channel to get. This is the same as the stream or user name.
+    # @return [Channel] A valid `Channel` object if the channel exists, `nil` otherwise.
+    def self.get(channel_name)
+      encoded_name = CGI.escape(channel_name)
+      json = connection.get("channels/#{encoded_name}")
+
+      # HTTP 422 can happen if the channel is associated with a Justin.tv account.
+      if !json || json['status'] == 404 || json['status'] == 422
+        nil
+      else
+        new(json)
+      end
+    end
+
+    # Does this channel have mature content? This flag is specified by the owner of the channel.
     # @return [Boolean] `true` if the channel has mature content, `false` otherwise.
     def mature?
       @mature
@@ -62,8 +68,8 @@ module Kappa::V2
       Stream.get(@name)
     end
 
-    # This makes a separate request to get the channel's stream. If you want to actually use
-    # the stream object, you should call `#stream` instead.
+    # Does this channel currently have a live stream?
+    # @note This makes a separate request to get the channel's stream. If you want to actually use the stream object, you should call `#stream` instead.
     # @return [Boolean] `true` if the channel currently has a live stream, `false` otherwise.
     # @see #stream
     def streaming?
@@ -74,6 +80,8 @@ module Kappa::V2
     # GET /channels/:channel/editors
     # https://github.com/justintv/Twitch-API/blob/master/v2_resources/channels.md#get-channelschanneleditors
     #
+    # @private
+    # Private until implemented.
     def editors
       # TODO
     end
@@ -82,19 +90,41 @@ module Kappa::V2
     # GET /channels/:channels/videos
     # https://github.com/justintv/Twitch-API/blob/master/v2_resources/videos.md#get-channelschannelvideos
     #
+    # @private
+    # Private until implemented.
     def videos(params = {})
       # TODO
     end
 
+    # TODO: Requires authentication.
+    # @private
+    # Private until implemented.
+    def subscribers
+    end
+
     #
-    # GET /channels/:channel/follows
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/channels.md#get-channelschannelfollows
-    # TODO: Warning: this set can be very large, this can run for very long time, recommend using :limit/:offset.
+    # GET /channels/:channel/subscriptions/:user
+    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/subscriptions.md#get-channelschannelsubscriptionsuser
     #
-    def followers(args = {})
+    # TODO: Requires authentication.
+    # @private
+    # Private until implemented.
+    def has_subscriber?(user)
+      # Support User object or username (string)
+    end
+
+    # Get the users following this channel.
+    # @note The number of followers is potentially very large, so it's recommended that you specify a `:limit`.
+    # @param options [Hash] Filter criteria.
+    # @option options [Fixnum] :limit (none) Limit on the number of results returned.
+    # @option options [Fixnum] :offset (0) Offset into the result set to begin enumeration.
+    # @see User
+    # @see https://github.com/justintv/Twitch-API/blob/master/v2_resources/channels.md#get-channelschannelfollows GET /channels/:channel/follows
+    # @return [Array<User>] List of users following this channel.
+    def followers(options = {})
       params = {}
 
-      limit = args[:limit]
+      limit = options[:limit]
       if limit && (limit < 100)
         params[:limit] = limit
       else
@@ -112,19 +142,6 @@ module Kappa::V2
       )
     end
 
-    # TODO: Requires authentication.
-    def subscribers
-    end
-
-    #
-    # GET /channels/:channel/subscriptions/:user
-    # https://github.com/justintv/Twitch-API/blob/master/v2_resources/subscriptions.md#get-channelschannelsubscriptionsuser
-    #
-    # TODO: Requires authentication.
-    def has_subscriber?(user)
-      # Support User object or username (string)
-    end
-
     # @return [Fixnum] Unique Twitch ID.
     attr_reader :id
 
@@ -137,7 +154,7 @@ module Kappa::V2
     # @return [DateTime] When the channel was created.
     attr_reader :created_at
 
-    # @return [String] Display name, e.g. name used for page title.
+    # @return [String] User-friendly display name. This name is used for the channel's page title.
     attr_reader :display_name
 
     # @return [String] Name of the primary game for this channel.
@@ -149,10 +166,10 @@ module Kappa::V2
     # @return [String] Unique Twitch name.
     attr_reader :name
 
-    # @return [String] Current status.
+    # @return [String] Current status set by the channel's owner.
     attr_reader :status
 
-    # @return [DateTime] When the channel was last updated, e.g. last stream time.
+    # @return [DateTime] When the channel was last updated. When a stream is started, its channel is updated.
     attr_reader :updated_at
 
     # @return [String] The URL for the channel's main page.
@@ -161,6 +178,7 @@ module Kappa::V2
     # @return [String] URL for the image shown when the stream is offline.
     attr_reader :video_banner_url
 
+    # @return [Array<Team>] The list of teams that this channel is associated with. Not all channels have associated teams.
     attr_reader :teams
   end
 end

data/lib/kappa/connection.rb

@@ -13,11 +13,13 @@ module Kappa
     def initialize(base_url = DEFAULT_BASE_URL)
       @base_url = Addressable::URI.parse(base_url)
 
+      # TODO: Expose client_id so clients of the library can (optionally) set this
+      # themselves and avoid rate limiting. Clients should still have the option to
+      # not set this and use a randomly generated ID.
+      
       uuid = SecureRandom.uuid
       # TODO: Use current library version.
       @client_id = "Kappa-v1-#{uuid}"
-
-      @last_request_time = Time.now - RATE_LIMIT_SEC
     end
 
     def get(path, query = nil)
@@ -27,25 +29,26 @@ module Kappa
         'Client-ID' => @client_id,
       }.merge(custom_headers)
 
-      response = rate_limit do
-        self.class.get(request_url, :headers => headers, :query => query)
-      end
+      response = self.class.get(request_url, :headers => headers, :query => query)
 
       # TODO: Handle non-JSON response
       # TODO: Handle invalid JSON
       # TODO: Handle non-200 codes
+      # TODO: Include HTTP status code in the return value
 
       json = response.body
       return JSON.parse(json)
     end
 
-    def accumulate(args)
-      path = args[:path]
-      params = args[:params]
-      json = args[:json]
-      sub_json = args[:sub_json]
-      klass = args[:class]
-      limit = args[:limit]
+    def accumulate(options)
+      path = options[:path]
+      params = options[:params] || {}
+      json = options[:json]
+      sub_json = options[:sub_json]
+      klass = options[:class]
+
+      total_limit = options[:limit]
+      page_limit = params[:limit] || 100
 
       objects = []
       ids = Set.new
@@ -57,13 +60,13 @@ module Kappa
           object = klass.new(object_json)
           if ids.add?(object.id)
             objects << object
-            if objects.count == limit
+            if objects.count == total_limit
               return objects
             end
           end
         end
 
-        !current_objects.empty?
+        !current_objects.empty? && (current_objects.count >= page_limit)
       end
 
       return objects
@@ -106,20 +109,6 @@ module Kappa
     end
 
   private
-    def rate_limit
-      delta = Time.now - @last_request_time
-      delay = [RATE_LIMIT_SEC - delta, 0].max
-
-      sleep delay if delay > 0
-
-      begin
-        return yield
-      ensure
-        @last_request_time = Time.now
-      end
-    end
-
-    RATE_LIMIT_SEC = 1
     DEFAULT_BASE_URL = 'https://api.twitch.tv/kraken/'
   end
 end