yt 0.6.3 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0608745d313bbcec172603a1854abfffdee3f074
-  data.tar.gz: 1f53091e0e0810f74c00a63f82584404fb640044
+  metadata.gz: ec366e6612cd8a61ec3067f58c819426b4da21ad
+  data.tar.gz: 3708e2efffd1b660afe370630d2f9b86e23f9e59
 SHA512:
-  metadata.gz: 3d79894c6d8bb6ce42e1e0ab7ee49c05f723a68eb41c2e1f32f5278979fb7e73d902af587648fb76b8cc5d18012d37220e04f84b1d463f714399a80cf46ce509
-  data.tar.gz: c393cf4018880ec464394d6c55087b8a65a99bcbf0466da48574c37927dc4232441851bf5b8f18033d361159e022dc6f584dbd68022b53849894ecd8849bcd09
+  metadata.gz: 33b816e4a002b24218b08b602c1faf999c854e04fa2edd3a3c84127ee0860463fe68ef8a07577d18830443497347ce55f968320503e5f27706b9e558be3cd884
+  data.tar.gz: 7e802cf425854455fd936424312f1343ce82a7bd35032b373cfb17df6b2c811525668013e91e2d7b7c3999725cf93d211e042981ff8dbbe55d58e7a3fa0eace5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    yt (0.6.3)
+    yt (0.6.4)
       activesupport
 
 GEM
@@ -20,7 +20,7 @@ GEM
       term-ansicolor
       thor
     diff-lcs (1.2.5)
-    docile (1.1.3)
+    docile (1.1.4)
     i18n (0.6.9)
     json (1.8.1)
     mime-types (2.3)
@@ -33,9 +33,9 @@ GEM
       rspec-core (~> 3.0.0)
       rspec-expectations (~> 3.0.0)
       rspec-mocks (~> 3.0.0)
-    rspec-core (3.0.0)
+    rspec-core (3.0.1)
       rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.0)
+    rspec-expectations (3.0.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.0.0)
     rspec-mocks (3.0.1)

data/HISTORY.md

@@ -6,6 +6,7 @@ v0.6 - 2014/06/05
 * Add the .status association to *every* type of resource (Channel, Video, Playlist)
 * Allow account.videos to be chained with .where, such as in account.videos.where(q: 'query')
 * Retry request once when YouTube times out
+* Handle annotations with "never" as the timestamp, without text, singleton positions, of private videos
 
 v0.5 - 2014/05/16
 -----------------

data/README.md

@@ -332,7 +332,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.6.3'
+    gem 'yt', '~> 0.6.4'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)

data/lib/yt.rb

@@ -1,3 +1,11 @@
 require 'yt/config'
 require 'yt/models/account'
-require 'yt/models/content_owner'
+require 'yt/models/content_owner'
+
+# An object-oriented Ruby client for YouTube.
+# Helps creating applications that need to interact with YouTube objects.
+# Inclused methods to access YouTube Data API V3 resources (channels, videos,
+# ...), YouTube Analytics API V2 resources (metrics, earnings, ...), and
+# objects not available through the API (annotations).
+module Yt
+end

data/lib/yt/actions/insert.rb

@@ -14,7 +14,10 @@ module Yt
       end
 
       def insert_params
+        path = "/youtube/v3/#{self.class.to_s.demodulize.camelize :lower}"
+
         {}.tap do |params|
+          params[:path] = path
           params[:method] = :post
           params[:auth] = @auth
           params[:expected_response] = Net::HTTPOK

data/lib/yt/collections/annotations.rb

@@ -5,6 +5,8 @@ module Yt
   module Collections
     # Provides methods to interact with a collection of YouTube annotations.
     # Resources with annotations are: {Yt::Models::Video videos}.
+    # @note Since there is no (authenticable) API endpoint to retrieve
+    #   annotations, only annotations of *public videos* can be retrieved.
     class Annotations < Base
 
     private
@@ -38,6 +40,15 @@ module Yt
 
         document = response.body.fetch('document', {})['annotations'] || {}
         Array.wrap document.fetch 'annotation', []
+      rescue Yt::Error => error
+        expected?(error) ? [] : raise(error)
+      end
+
+      # Since there is no API endpoint, retrieving annotations of unknown
+      # videos or of private videos (to which YouTube responds with 403)
+      # should not raise an error, but simply not return any annotation.
+      def expected?(error)
+        error.is_a? Yt::Errors::Forbidden
       end
     end
   end

data/lib/yt/collections/playlist_items.rb

@@ -22,21 +22,20 @@ module Yt
 
     private
 
+      # @return [Yt::Models::PlaylistItem] a new playlist item initialized with
+      #   one of the items returned by asking YouTube for a list of items.
+      # @see https://developers.google.com/youtube/v3/docs/playlistItems#resource
       def new_item(data)
         Yt::PlaylistItem.new id: data['id'], snippet: data['snippet'], status: data['status'], auth: @auth
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list items.
+      # @see https://developers.google.com/youtube/v3/docs/playlistItems/list
       def list_params
         super.tap do |params|
           params[:params] = {maxResults: 50, part: 'snippet,status', playlistId: @parent.id}
         end
       end
-
-      def insert_params
-        super.tap do |params|
-          params[:path] = '/youtube/v3/playlistItems'
-        end
-      end
     end
   end
 end

data/lib/yt/collections/playlists.rb

@@ -25,21 +25,20 @@ module Yt
 
     private
 
+      # @return [Yt::Models::Playlist] a new playlist initialized with
+      #   one of the items returned by asking YouTube for a list of playlists.
+      # @see https://developers.google.com/youtube/v3/docs/playlists#resource
       def new_item(data)
         Yt::Playlist.new id: data['id'], snippet: data['snippet'], status: data['status'], auth: @auth
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list playlists.
+      # @see https://developers.google.com/youtube/v3/docs/playlist/list
       def list_params
         super.tap do |params|
           params[:params] = {maxResults: 50, part: 'snippet,status', channelId: @parent.id}
         end
       end
-
-      def insert_params
-        super.tap do |params|
-          params[:path] = '/youtube/v3/playlists'
-        end
-      end
     end
   end
 end

data/lib/yt/collections/snippets.rb

@@ -7,10 +7,15 @@ module Yt
 
     private
 
+      # @return [Yt::Models::Snippet] a new snippet initialized with
+      #   one of the items returned by asking YouTube for a list of snippets.
       def new_item(data)
         Yt::Snippet.new data: data['snippet']
       end
 
+      # @return [Hash] the parameters to submit to YouTube to get the
+      #   snippet of a resource, for instance a channel.
+      # @see https://developers.google.com/youtube/v3/docs/channels#resource
       def list_params
         super.tap do |params|
           params[:params] = {id: @parent.id, part: 'snippet'}

data/lib/yt/collections/statuses.rb

@@ -7,10 +7,17 @@ module Yt
 
     private
 
+      # @return [Yt::Models::Status] a new status initialized with
+      #   one of the items returned by asking YouTube for a list of statuses,
+      #   of a resource, for instance a channel.
+      # @see https://developers.google.com/youtube/v3/docs/playlists#resource
       def new_item(data)
         Yt::Status.new data: data['status']
       end
 
+      # @return [Hash] the parameters to submit to YouTube to get the status
+      #   of a resource, for instance a channel.
+      # @see https://developers.google.com/youtube/v3/docs/channels/list
       def list_params
         super.tap do |params|
           params[:params] = {id: @parent.id, part: 'status'}

data/lib/yt/collections/subscriptions.rb

@@ -20,6 +20,10 @@ module Yt
 
     private
 
+      # @return [Yt::Models::Subscription] a new subscription initialized with
+      #   one of the items returned by asking YouTube for a list of
+      #   subscriptions to a channel.
+      # @see https://developers.google.com/youtube/v3/docs/subscriptions#resource
       def new_item(data)
         Yt::Subscription.new id: data['id'], auth: @auth
       end
@@ -41,15 +45,18 @@ module Yt
         super params
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list subscriptions.
+      # @see https://developers.google.com/youtube/v3/docs/subscriptions/list
       def list_params
         super.tap do |params|
           params[:params] = {maxResults: 50, forChannelId: @parent.id, mine: true, part: 'snippet'}
         end
       end
 
+      # @return [Hash] the parameters to submit to YouTube to add a subscriptions.
+      # @see https://developers.google.com/youtube/v3/docs/subscriptions/insert
       def insert_params
         super.tap do |params|
-          params[:path] = '/youtube/v3/subscriptions'
           params[:params] = {part: 'snippet'}
           params[:body] = {snippet: {resourceId: {channelId: @parent.id}}}
         end

data/lib/yt/collections/user_infos.rb

@@ -7,10 +7,15 @@ module Yt
 
     private
 
+      # @return [Yt::Models::UserInfo] a new user info initialized with
+      #   one of the items returned by asking YouTube for a list of user infos.
       def new_item(data)
         Yt::UserInfo.new data: data
       end
 
+      # @return [Hash] the parameters to submit to YouTube to get the
+      #   user info of an account
+      # @see https://developers.google.com/+/api/latest/people/getOpenIdConnect
       def list_params
         super.tap do |params|
           params[:path] = '/oauth2/v2/userinfo'
@@ -18,11 +23,15 @@ module Yt
         end
       end
 
+      # next_page is overloaded here because, differently from the other
+      # endpoints, asking for the user info does not return a paginated result,
+      # so @page_token has to be explcitly set to nil, and the result wrapped
+      # in an Array.
       def next_page
         request = Yt::Request.new list_params
         response = request.run
         @page_token = nil
-        
+
         Array.wrap response.body
       end
     end

data/lib/yt/models/account.rb

@@ -8,19 +8,19 @@ module Yt
     class Account < Base
       include Associations::Authentications
 
-      # @!attribute channel
+      # @!attribute [r] channel
       #   @return [Yt::Models::Channel] the account’s channel.
       has_one :channel
       delegate :playlists, :create_playlist, :delete_playlists, to: :channel
 
-      # @!attribute user_info
+      # @!attribute [r] user_info
       #   @return [Yt::Models::UserInfo] the account’s profile information.
       has_one :user_info
       delegate :id, :email, :has_verified_email?, :gender, :name,
                :given_name, :family_name, :profile_url, :avatar_url,
                :locale, :hd, to: :user_info
 
-      # @!attribute videos
+      # @!attribute [r] videos
       #   @return [Yt::Collections::Videos] the videos owned by the account.
       has_many :videos
 

data/lib/yt/models/annotation.rb

@@ -7,7 +7,7 @@ module Yt
       # @option options [String] :data The XML representation of an annotation
       # @note YouTube API V3 does not provide access to video annotations,
       #   therefore the XML endpoint is used to retrieve them and its response
-      #    is passed to the Annotation initializer.
+      #   is passed to the Annotation initializer.
       def initialize(options = {})
         @data = options[:data]
       end
@@ -75,7 +75,7 @@ module Yt
     private
 
       def text
-        @text ||= @data.fetch 'TEXT', ''
+        @text ||= @data['TEXT'] || ''
       end
 
       def type
@@ -107,7 +107,7 @@ module Yt
       end
 
       def timestamps
-        @timestamps ||= positions.map do |pos|
+        @timestamps ||= positions.reject{|pos| pos['t'] == 'never'}.map do |pos|
           regex = %r{(?:|(?<hours>\d*):)(?:|(?<min>\d*):)(?<sec>\d*)\.(?<ms>\d*)}
           match = pos['t'].match regex
           hours = (match[:hours] || '0').to_i
@@ -118,7 +118,7 @@ module Yt
       end
 
       def positions
-        @positions ||= region['rectRegion'] || region['anchoredRegion'] || []
+        @positions ||= Array.wrap region['rectRegion'] || region['anchoredRegion']
       end
 
       def region

data/lib/yt/models/authentication.rb

@@ -1,9 +1,49 @@
 module Yt
   module Models
-    # Provides methods to authenticate with YouTube.
-    # @see https://developers.google.com/youtube/v3/guides/authentication
+    # Provides methods to authenticate with YouTube (and Google) API.
+    # @see https://developers.google.com/accounts/docs/OAuth2
     class Authentication
-      attr_reader :access_token, :refresh_token, :expires_at
+
+      # Before your application can access private data using a Google API,
+      # it must obtain an access token that grants access to that API.
+      # A single access token can grant varying degrees of access to multiple
+      # APIs. A variable parameter called scope controls the set of resources
+      # and operations that an access token permits.
+      # After an application obtains an access token, it sends the token to a
+      # Google API in an HTTP authorization header.
+      # Access tokens are valid only for the set of operations and resources
+      # described in the scope of the token request. For example, if an access
+      # token is issued for the Google+ API, it does not grant access to the
+      # Google Contacts API.
+      #
+      # @return [String] the OAuth2 Google access token.
+      attr_reader :access_token
+
+      # Access tokens have limited lifetimes. If your application needs access
+      # to a Google API beyond the lifetime of a single access token, it can
+      # obtain a refresh token. A refresh token allows your application to
+      # obtain new access tokens.
+      # @note Save refresh tokens in secure long-term storage and continue to
+      # use them as long as they remain valid. Limits apply to the number of
+      # refresh tokens that are issued per client-user combination, and per
+      # user across all clients, and these limits are different. If your
+      # application requests enough refresh tokens to go over one of the
+      # limits, older refresh tokens stop working.
+      # There is currently a 25-token limit per Google user account.
+      # If a user account has 25 valid tokens, the next authentication request
+      # succeeds, but quietly invalidates the oldest outstanding token without
+      # any user-visible warning.
+      #
+      # @return [String] the OAuth2 Google refresh token.
+      attr_reader :refresh_token
+
+      # Access tokens have limited lifetimes. If your application needs access
+      # to a Google API beyond the lifetime of a single access token, it can
+      # obtain a refresh token. A refresh token allows your application to
+      # obtain new access tokens.
+      #
+      # @return [Time] the time when access token no longer works.
+      attr_reader :expires_at
 
       def initialize(data = {})
         @access_token = data['access_token']
@@ -11,6 +51,7 @@ module Yt
         @expires_at = expiration_date data.slice('expires_at', 'expires_in')
       end
 
+      # @return [Boolean] whether the access token has expired.
       def expired?
         @expires_at && @expires_at.past?
       end

data/lib/yt/models/base.rb

@@ -2,8 +2,9 @@ require 'yt/actions/delete'
 require 'yt/actions/update'
 require 'yt/errors/request_error'
 
+require 'active_support' # does not load anything by default but is required
 require 'active_support/core_ext/module/delegation' # for delegate
-require 'active_support/core_ext/string/inflections' # for camelize
+require 'active_support/core_ext/string/inflections' # for camelize/constantize
 
 module Yt
   module Models
@@ -13,29 +14,36 @@ module Yt
 
       # @private
       def self.has_many(attributes)
-        attributes = attributes.to_s
         require "yt/collections/#{attributes}"
-        mod = attributes.sub(/.*\./, '').camelize
-        collection = "Yt::Collections::#{mod.pluralize}".constantize
-
-        define_method attributes do
-          ivar = instance_variable_get "@#{attributes}"
-          instance_variable_set "@#{attributes}", ivar || collection.of(self)
-        end
+        collection_name = attributes.to_s.sub(/.*\./, '').camelize.pluralize
+        collection = "Yt::Collections::#{collection_name}".constantize
+        define_memoized_method(attributes) { collection.of self }
       end
 
       # @private
       def self.has_one(attribute)
         attributes = attribute.to_s.pluralize
         has_many attributes
+        define_memoized_method(attribute) { send(attributes).first! }
+      end
+
+    private
 
-        define_method attribute do
-          ivar = instance_variable_get "@#{attribute}"
-          instance_variable_set "@#{attribute}", ivar || send(attributes).first!
+      # A wrapper around Ruby’s +define_method+ that, in addition to adding an
+      # instance method called +name+, adds an instance variable called +@name+
+      # that stores the result of +name+ the first time is invoked, and returns
+      # it every other time. Especially useful if invoking +name+ takes a long
+      # time.
+      def self.define_memoized_method(name, &method)
+        define_method name do
+          ivar = instance_variable_get "@#{name}"
+          instance_variable_set "@#{name}", ivar || instance_eval(&method)
         end
       end
     end
   end
 
+  # By including Models in the main namespace, models can be initialized with
+  # the shorter notation Yt::Video.new, rather than Yt::Models::Video.new.
   include Models
 end

data/lib/yt/models/channel.rb

@@ -10,15 +10,15 @@ module Yt
       include Associations::Earnings
       include Associations::Views
 
-      # @!attribute subscriptions
+      # @!attribute [r] subscriptions
       #   @return [Yt::Collections::Subscriptions] the channel’s subscriptions.
       has_many :subscriptions
 
-      # @!attribute videos
+      # @!attribute [r] videos
       #   @return [Yt::Collections::Videos] the channel’s videos.
       has_many :videos
 
-      # @!attribute playlists
+      # @!attribute [r] playlists
       #   @return [Yt::Collections::Playlists] the channel’s playlists.
       has_many :playlists
 

data/lib/yt/models/content_owner.rb

@@ -7,7 +7,7 @@ module Yt
     # @see https://developers.google.com/youtube/analytics/v1/content_owner_reports
     class ContentOwner < Account
 
-      # @!attribute partnered_channels
+      # @!attribute [r] partnered_channels
       #   @return [Yt::Collection::PartneredChannels] the channels managed by the CMS account.
       has_many :partnered_channels
 

data/lib/yt/models/description.rb

@@ -2,61 +2,48 @@ require 'yt/models/url'
 
 module Yt
   module Models
-    # Provides read-only access to the description of a YouTube resource.
-    # Resources with descriptions are: videos and channels.
-    #
-    # @example
-    #   description = Yt::Description.new 'Fullscreen provides a suite of end-to-end YouTube tools and services to many of the world’s leading brands and media companies.'
-    #   description.to_s.slice(0,19) # => 'Fullscreen provides'
-    #   description.length # => 127
+    # Encapsulates information about the description of a resource, for
+    # instance a channel.
+    # @see https://developers.google.com/youtube/v3/docs/channels#resource
     #
+    # The value has a maximum length of 1000 characters.
     class Description < String
-      # Returns whether the description includes a YouTube video URL
-      #
+      # @return [Boolean] whether the description includes a link to a video
       # @example
-      #   description = Yt::Description.new 'Link to video: youtube.com/watch?v=MESycYJytkU'
+      #   description = Yt::Models::Description.new 'Link to video: youtube.com/watch?v=MESycYJytkU'
       #   description.has_link_to_video? #=> true
       #
-      # @return [Boolean] Whether the description includes a link to a video
+      # @todo add an option to match the link to a specific video
       def has_link_to_video?
-        # TODO: might take as an option WHICH video to link to
-        # in order to check if it's my own video
         links.any?{|link| link.kind == :video}
       end
 
-      # Returns whether the description includes a YouTube channel URL
-      #
+      # @return [Boolean] whether the description includes a link to a channel
       # @example
       #   description = Yt::Description.new 'Link to channel: youtube.com/fullscreen'
       #   description.has_link_to_channel? #=> true
       #
-      # @return [Boolean] Whether the description includes a link to a channel
-      def has_link_to_channel?(options = {}) # TODO: which channel
-        # TODO: might take as an option WHICH channel to link to
-        # in order to check if it's my own channel
+      # @todo add an option to match the link to a specific channel
+      def has_link_to_channel?(options = {})
         links.any?{|link| link.kind == :channel}
       end
 
-      # Returns whether the description includes a YouTube subscription URL
-      #
+      # @return [Boolean] whether the description includes a link to subscribe
       # @example
       #   description = Yt::Description.new 'Link to subscribe: youtube.com/subscription_center?add_user=fullscreen'
       #   description.has_link_to_subscribe? #=> true
       #
-      # @return [Boolean] Whether the description includes a link to subscribe
-      def has_link_to_subscribe?(options = {}) # TODO: which channel
-        # TODO: might take as an option WHICH channel to subscribe to
-        # in order to check if it's my own channel
+      # @todo add an option to match the link to subscribe to a specific channel
+      def has_link_to_subscribe?(options = {})
         links.any?{|link| link.kind == :subscription}
       end
 
-      # Returns whether the description includes a YouTube playlist URL
-      #
+      # @return [Boolean] whether the description includes a link to a playlist
       # @example
       #   description = Yt::Description.new 'Link to playlist: youtube.com/playlist?list=LLxO1tY8h1AhOz0T4ENwmpow'
       #   description.has_link_to_playlist? #=> true
       #
-      # @return [Boolean] Whether the description includes a link to a playlist
+      # @todo add an option to match the link to a specific playlist
       def has_link_to_playlist?
         links.any?{|link| link.kind == :playlist}
       end

data/lib/yt/models/details_set.rb

@@ -2,28 +2,29 @@ require 'yt/models/base'
 
 module Yt
   module Models
+    # Encapsulates information about the content of a resource, for
+    # instance a video.
+    # @see https://developers.google.com/youtube/v3/docs/videos#resource
     class DetailsSet < Base
 
       def initialize(options = {})
         @data = options[:data]
       end
 
-      # Return the duration of the YouTube video.
-      #
-      # @return [Integer] Duration in seconds of the YouTube video
+      # @return [Integer] the duration of the resource (in seconds).
       def duration
         @duration = to_seconds @data.fetch('duration', 0)
       end
-      # also available: dimension, definition, caption, licensed_content?
 
     private
 
-      # The length of the video. The tag value is an ISO 8601 duration in the format PT#M#S,
-      # in which the letters PT indicate that the value specifies a period of time, and
-      # the letters M and S refer to length in minutes and seconds, respectively. The #
-      # characters preceding the M and S letters are both integers that specify the number
-      # of minutes (or seconds) of the video. For example, a value of PT15M51S indicates
-      # that the video is 15 minutes and 51 seconds long.
+      # The duration of the resource as reported by YouTube. The value is an
+      # ISO 8601 duration in the format PT#M#S, in which the letters PT
+      # indicate that the value specifies a period of time, and the letters M
+      # and S refer to length in minutes and seconds, respectively. The #
+      # characters preceding the M and S letters are both integers that specify
+      # the number of minutes (or seconds) of the video. For example, a value
+      # of PT15M51S indicates that the video is 15 minutes and 51 seconds long.
       def to_seconds(iso8601_duration)
         match = iso8601_duration.match %r{^PT(?:|(?<hours>\d*?)H)(?:|(?<min>\d*?)M)(?:|(?<sec>\d*?)S)$}
         hours = (match[:hours] || '0').to_i

data/lib/yt/models/id.rb

@@ -1,5 +1,7 @@
 module Yt
   module Models
+    # Encapsulates information about the ID that YouTube uses to uniquely
+    # identify a resource.
     class Id < String
     end
   end

data/lib/yt/models/playlist.rb

@@ -6,10 +6,17 @@ module Yt
     # @see https://developers.google.com/youtube/v3/docs/playlists
     class Playlist < Resource
 
-      # @!attribute playlist_items
+      # @!attribute [r] playlist_items
       #   @return [Yt::Collections::PlaylistItems] the playlist’s items.
       has_many :playlist_items
 
+      # Deletes the playlist.
+      #
+      # This method requires {Resource#auth auth} to return an authenticated
+      # instance of {Yt::Account} with permissions to delete the playlist.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an account with permissions to delete the playlist.
+      # @return [Boolean] whether the playlist does not exist anymore.
       def delete
         do_delete {@id = nil}
         !exists?
@@ -37,6 +44,14 @@ module Yt
         !@id.nil?
       end
 
+      # Adds a video to the playlist
+      # Does not raise an error if the video cannot be added (e.g., unknown).
+      #
+      # This method requires {Resource#auth auth} to return an authenticated
+      # instance of {Yt::Account} with permissions to update the playlist.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an account with permissions to update the playlist.
+      # @return [Yt::PlaylistItem] the item added to the playlist.
       def add_video(video_id)
         playlist_items.insert video_params(video_id), ignore_errors: true
       end
@@ -59,6 +74,8 @@ module Yt
 
     private
 
+      # @return [Hash] the parameters to submit to YouTube to delete a playlist.
+      # @see https://developers.google.com/youtube/v3/docs/playlists/delete
       def delete_params
         super.tap do |params|
           params[:path] = '/youtube/v3/playlists'
@@ -66,6 +83,8 @@ module Yt
         end
       end
 
+      # @return [Hash] the parameters to submit to YouTube to update a playlist.
+      # @see https://developers.google.com/youtube/v3/docs/playlists/update
       def update_params
         super.tap do |params|
           params[:path] = '/youtube/v3/playlists'

data/lib/yt/models/playlist_item.rb

@@ -35,6 +35,8 @@ module Yt
 
     private
 
+      # @return [Hash] the parameters to submit to YouTube to delete a playlist item.
+      # @see https://developers.google.com/youtube/v3/docs/playlistItems/delete
       def delete_params
         super.tap do |params|
           params[:path] = '/youtube/v3/playlistItems'

data/lib/yt/models/rating.rb

@@ -22,6 +22,8 @@ module Yt
 
     private
 
+      # @return [Hash] the parameters to submit to YouTube to update a rating.
+      # @see https://developers.google.com/youtube/v3/docs/videos/rate
       def update_params
         super.tap do |params|
           params[:method] = :post

data/lib/yt/models/request.rb

@@ -1,6 +1,7 @@
 require 'net/http' # for Net::HTTP.start
 require 'uri' # for URI.json
 require 'json' # for JSON.parse
+require 'active_support' # does not load anything by default  but is required
 require 'active_support/core_ext' # for Hash.from_xml, Hash.to_param
 
 require 'yt/config'

data/lib/yt/models/snippet.rb

@@ -2,28 +2,25 @@ require 'yt/models/description'
 
 module Yt
   module Models
+    # Encapsulates information about the snippet of a resource, for
+    # instance a channel.
+    # @see https://developers.google.com/youtube/v3/docs/channels#resource
     class Snippet
       def initialize(options = {})
         @data = options[:data]
       end
 
-      # Return the title of the YouTube resource.
-      #
-      # @return [String] Title of the YouTube resource
+      # @return [String] the resource’s title.
       def title
         @title ||= @data.fetch 'title', ''
       end
 
-      # Return the description of a YouTube resource.
-      #
-      # @return [Yt::Description] A Yt::Description object for the YouTube resource
+      # @return [Yt::Models::Description] the resource’s description.
       def description
         @description ||= Description.new @data.fetch('description', '')
       end
 
-      # Return the publication date of a YouTube resource.
-      #
-      # @return [Time or nil] The publication date for the YouTube resource
+      # @return [Time or nil] the date and time that the resource was created.
       def published_at
         @published_at ||= Time.parse @data['publishedAt']
       end
@@ -38,9 +35,13 @@ module Yt
         @tags ||= @data.fetch 'tags', []
       end
 
-      # Return the URL of a thumbnail image of the YouTube resource.
-      #
-      # @return [String] A URL.
+      # @return [String] a thumbnail image associated with the resource.
+      # @param [Symbol or String] size The size of the thumbnail to retrieve.
+      #   Valid values are: default, medium, high.
+      #   For a resource that refers to a video, default equals 120x90px,
+      #   medium equals 320x180px, high equals 480x360px.
+      #   For a resource that refers to a channel, default equals 88x88px,
+      #   medium equals 240x240px, high equals 800x800px.
       def thumbnail_url(size = :default)
         @thumbnails ||= @data.fetch 'thumbnails', {}
         @thumbnails.fetch(size.to_s, {})['url']

data/lib/yt/models/status.rb

@@ -1,25 +1,30 @@
 module Yt
   module Models
+    # Encapsulates information about the privacy status of a resource, for
+    # instance a channel.
+    # @see https://developers.google.com/youtube/v3/docs/channels#resource
     class Status
       def initialize(options = {})
         @data = options[:data]
       end
 
-      # @return [Boolean] Is the resource public?
+      # @return [Boolean] whether the resource is public
       def public?
         privacy_status == 'public'
       end
 
-      # @return [Boolean] Is the resource private?
+      # @return [Boolean] whether the resource is private
       def private?
         privacy_status == 'private'
       end
 
-      # @return [Boolean] Is the resource unlisted?
+      # @return [Boolean] whether the resource is unlisted
       def unlisted?
         privacy_status == 'unlisted'
       end
 
+      # @return [String] the privacy status of the channel.
+      # Valid values are: private, public, unlisted
       def privacy_status
         @privacy_status ||= @data['privacyStatus']
       end

data/lib/yt/models/subscription.rb

@@ -29,6 +29,8 @@ module Yt
 
     private
 
+      # @return [Hash] the parameters to submit to YouTube to delete a subscription.
+      # @see https://developers.google.com/youtube/v3/docs/subscriptions/delete
       def delete_params
         super.tap do |params|
           params[:path] = '/youtube/v3/subscriptions'

data/lib/yt/models/video.rb

@@ -5,16 +5,16 @@ module Yt
     # Provides methods to interact with YouTube videos.
     # @see https://developers.google.com/youtube/v3/docs/videos
     class Video < Resource
-      # @!attribute details_set
+      # @!attribute [r] details_set
       #   @return [Yt::Models::DetailsSet] the video’s content details.
       has_one :details_set
       delegate :duration, to: :details_set
 
-      # @!attribute rating
+      # @!attribute [r] rating
       #   @return [Yt::Models::Rating] the video’s rating.
       has_one :rating
 
-      # @!attribute annotations
+      # @!attribute [r] annotations
       #   @return [Yt::Collections::Annotations] the video’s annotations.
       has_many :annotations
 

data/lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.6.3'
+  VERSION = '0.6.4'
 end

data/spec/associations/no_auth/video_spec.rb

@@ -4,10 +4,17 @@ require 'yt/models/video'
 describe Yt::Video, :device_app do
   subject(:video) { Yt::Video.new id: id, auth: $account }
 
-  context 'given an existing video with annotations' do
+  context 'given a public video with annotations' do
     let(:id) { 'MESycYJytkU' }
 
     it { expect(video.annotations).to be_a Yt::Collections::Annotations }
     it { expect(video.annotations.first).to be_a Yt::Annotation }
   end
+
+  context 'given a private video' do
+    let(:id) { 'JzDEc54FVTc' }
+
+    it { expect(video.annotations).to be_a Yt::Collections::Annotations }
+    it { expect(video.annotations.count).to be_zero }
+  end
 end

data/spec/models/annotation_spec.rb

@@ -24,6 +24,18 @@ describe Yt::Annotation do
       it { expect(annotation.below? 5).to be true }
     end
 
+    context 'given an annotation without a single position' do
+      let(:xml) { %Q{
+        <segment>
+        <movingRegion type="rect">
+        <rectRegion d="0" h="17.7779998779" t="0:05.000" w="25.0" x="7.117000103" y="5.07000017166"/>
+        </movingRegion>
+        </segment>
+      } }
+      it { expect(annotation.above? 50).to be true }
+      it { expect(annotation.below? 50).to be_falsey }
+    end
+
     context 'given an annotation without explicit location' do
       let(:xml) { '<segment></segment>' }
       it { expect(annotation.above? 50).to be_falsey }
@@ -75,6 +87,11 @@ describe Yt::Annotation do
       let(:xml) { '<action type="openUrl"><url link_class="3"/></action>' }
       it { expect(annotation).not_to have_link_to_playlist }
     end
+
+    context 'given an annotation without text' do
+      let(:xml) { '<TEXT />' }
+      it { expect(annotation).not_to have_link_to_playlist }
+    end
   end
 
   describe '#has_link_to_same_window?' do
@@ -127,5 +144,18 @@ describe Yt::Annotation do
       it { expect(annotation.starts_after? 0).to be_nil }
       it { expect(annotation.starts_before? 0).to be_nil }
     end
+
+    context 'given an annotation with "never" as the timestamp' do
+      let(:xml) { %Q{
+        <segment>
+        <movingRegion type="rect">
+        <rectRegion h="6.0" t="never" w="25.0" x="7.0" y="5.0"/>
+        <rectRegion h="6.0" t="never" w="25.0" x="7.0" y="5.0"/>
+        </movingRegion>
+        </segment>
+      } }
+      it { expect(annotation.starts_after? 0).to be_nil }
+      it { expect(annotation.starts_before? 0).to be_nil }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yt
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.6.4
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-12 00:00:00.000000000 Z
+date: 2014-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport