yt 0.11.6 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c55e1f1f22fd6b8b4e6fe44a48fc7810ea9d0339
-  data.tar.gz: 240e018e958c9e5ebe768736da774dfafaaf345f
+  metadata.gz: 54ab025a1959cb9cb0ec25849d5936357c1c5bdf
+  data.tar.gz: 5cec0556974d50170a889a7a2348962a0cb1754f
 SHA512:
-  metadata.gz: d1573d2e0347daa451e4e77912307d27986694d9e2a1839d4c1ac632703f5a2343dc36ea91a83b57f27a5125179048a89fb2df6b8bc91bb2b153e028ae85f77c
-  data.tar.gz: 250cc4b5a7ac15fa4499347c181b954a73a60620385960da00b83ef8058ab4a60d847ebd134ad5770ea5a1f280e55eddedb9549fbaae7fe11ae687409cf98e43
+  metadata.gz: 3427b8b2d9f3cd1b1d1640a0adb1e2946cefc2a254e123bb9127ffd417e5cc13e6e8068ec885e48b8c383b467e0bb510a25b6085d77c8163ac6d926064f39381
+  data.tar.gz: 780a2e9ef4ebb816086d3c3ef82992ef0bb94caaeae3f255108e8d7877015539ab2a3d38451bb056f1e3854c6cca9721ffd1eaef492e74a0f95eb0537bc0ec17

data/CHANGELOG.md

@@ -6,6 +6,41 @@ For more information about changelogs, check
 [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 0.12.1 - unreleased
+
+* [ENHANCEMENT] Add `position` option to add_video (to specify where in a playlist to add a video)
+* [FEATURE] Add `update` to PlaylistItem (to change the position of the item in the playlist)
+
+## 0.12.0 - 2014-08-31
+
+**How to upgrade**
+
+If your code never calls the `delete` method directly on a Subscription
+object (to delete subscriptions by id), then you are good to go.
+
+If it does, then be aware that trying to delete an unknown subscription will
+now raise a RequestError, and will not accept `ignore_errors` as an option:
+
+    account = Yt::Account.new access_token: 'ya29...'
+    subscription = Yt::Subscription.new id: '--unknown-id--', auth: account
+    # old behavior
+    subscription.delete ignore_errors: true # => false
+    # new behavior
+    subscription.delete # => raises Yt::Errors::RequestError "subscriptionNotFound"
+
+Note that the `unsubscribe` and `unsubscribe!` methods of `Channel` have not
+changed, so you can still try to unsubscribe from a channel and not raise an
+error by using the `unsubscribe` method:
+
+    account = Yt::Account.new access_token: 'ya29...'
+    channel = Yt::Channel.new id: 'UC-CHANNEL-ID', auth: account
+    channel.unsubscribe # => returns falsey if you were not subscribed
+    channel.unsubscribe! # => raises Yt::Errors::RequestError if you were not subscribed
+
+* [ENHANCEMENT] Replace `has_many :subscriptions` with `has_one :subscription` in Channel
+* [FEATURE] Add `subscribed_channels` to Channel (list which channels the channel is subscribed to)
+* [FEATURE] Add `subscribers` to Account (list which channels are subscribed to an account)
+
 ## 0.11.6 - 2014-08-28
 
 * [BUGFIX] Make Resource.new(url: url).title hit the right endpoint

data/README.md

@@ -41,7 +41,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.11.6'
+    gem 'yt', '~> 0.12.0'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
@@ -61,6 +61,7 @@ Use [Yt::Account](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Acco
 * access the channel managed by the account
 * access the videos uploaded by the account
 * upload a video
+* list the channels subscribed to an account
 
 ```ruby
 # Accounts can be initialized with access token, refresh token or an authorization code
@@ -75,6 +76,10 @@ account.videos.first #=> #<Yt::Models::Video @id=...>
 account.upload_video 'my_video.mp4', title: 'My new video', privacy_status: 'private'
 account.upload_video 'http://example.com/remote.m4v', title: 'My other video', tags: ['music']
 
+account.subscribers.count #=> 2
+account.subscribers.first #=> #<Yt::Models::Channel @id=...>
+account.subscribers.first.title #=> 'Fullscreen'
+
 ```
 
 *The methods above require to be authenticated as a YouTube account (see below).*
@@ -134,6 +139,7 @@ Use [Yt::Channel](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Chan
 * read the attributes of a channel
 * access the videos of a channel
 * access the playlists of a channel
+* access the channels that the channel is subscribed to
 * subscribe to and unsubscribe from a channel
 * create and delete playlists from a channel
 * retrieve the daily earnings, views, comments, likes, dislikes, shares and impressions of a channel
@@ -161,6 +167,9 @@ channel.videos.first #=> #<Yt::Models::Video @id=...>
 
 channel.playlists.count #=> 2
 channel.playlists.first #=> #<Yt::Models::Playlist @id=...>
+
+channel.subscribed_channels.count #=> 132
+channel.subscribed_channels.first #=> #<Yt::Models::Channel @id=...>
 ```
 
 *The methods above do not require authentication.*
@@ -371,7 +380,7 @@ playlist.playlist_items.first #=> #<Yt::Models::PlaylistItem @id=...>
 
 ```ruby
 playlist.update title: 'A <title> with angle brackets', description: 'desc', tags: ['new tag'], privacy_status: 'private'
-playlist.add_video 'MESycYJytkU'
+playlist.add_video 'MESycYJytkU', position: 2
 playlist.add_videos ['MESycYJytkU', 'MESycYJytkU']
 playlist.delete_playlist_items title: 'Fullscreen Creator Platform' #=> [true]
 ```
@@ -384,6 +393,7 @@ Yt::PlaylistItem
 Use [Yt::PlaylistItem](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/PlaylistItem) to:
 
 * read the attributes of a playlist item
+* update the position of an item inside a playlist
 * delete a playlist item
 
 ```ruby
@@ -406,6 +416,7 @@ item.video #=> #<Yt::Models::Video @id=...>
 *The methods above do not require authentication.*
 
 ```ruby
+item.update position: 3 #=> true
 item.delete #=> true
 ```
 

data/lib/yt/actions/list.rb

@@ -24,9 +24,19 @@ module Yt
         end
       end
 
-      # @private
       # Returns the total number of items that YouTube can provide for the
       # given request, either all in one page or in consecutive pages.
+      #
+      # This number comes from the 'totalResults' component of the 'pageInfo'
+      # which, accordingly to YouTube documentation, *does not always match
+      # the actual number of items in the response*.
+      #
+      # For instance, when retrieving a list of channels, 'totalResults' might
+      # include inactive channels, which are filtered out from the response.
+      #
+      # The only way to obtain the *real* number of returned items is to
+      # iterate through all the pages, which can results in many requests.
+      # To avoid this, +total_results+ is provided as a good size estimation.
       def total_results
         response = request(list_params).run
         total_results = response.body.fetch('pageInfo', {})['totalResults']

data/lib/yt/associations/has_attribute.rb

@@ -0,0 +1,51 @@
+require 'yt/models/timestamp'
+
+module Yt
+  module Associations
+    module HasAttribute
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+    private
+
+      def type_cast(value, type)
+        case [type]
+          when [Time] then Yt::Timestamp.parse(value) if value
+          when [Integer] then value.to_i if value
+          when [Float] then value.to_f if value
+          when [Symbol] then value.to_sym if value
+          when [Hash] then value || {}
+        end
+      end
+
+      module ClassMethods
+        def has_attribute(attribute, options = {}, &block)
+          define_memoized_method(attribute) do
+            field = options.fetch(:from, attribute).to_s
+            field = field.camelize(:lower) if options.fetch(:camelize, true)
+            value = @data.fetch field, options[:default]
+            value = type_cast value, options[:type] if options[:type]
+            block_given? ? instance_exec(value, &block) : value
+          end
+        end
+
+      private
+
+        # 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 define_memoized_method(name, &method)
+          ivar_name = "@#{name.to_s.gsub /[?!]$/, ''}"
+
+          define_method name do
+            value = instance_variable_get ivar_name
+            instance_variable_set ivar_name, value || instance_eval(&method)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yt/associations/has_many.rb

@@ -12,25 +12,10 @@ module Yt
         require 'active_support' # does not load anything by default
         require 'active_support/core_ext/string/inflections' # for camelize ...
         require "yt/collections/#{attributes}"
-
         collection_name = attributes.to_s.sub(/.*\./, '').camelize.pluralize
         collection = "Yt::Collections::#{collection_name}".constantize
         define_memoized_method(attributes) { collection.of self }
       end
-
-    private
-
-      # 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 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
 end

data/lib/yt/collections/content_owners.rb

@@ -14,10 +14,6 @@ module Yt
         {owner_name: data['id'], authentication: @auth.authentication}
       end
 
-      def new_item(data)
-        Yt::ContentOwner.new owner_name: data['id'], authentication: @auth.authentication
-      end
-
       # @return [Hash] the parameters to submit to YouTube to list content
       #   owners administered by the account.
       # @see https://developers.google.com/youtube/partner/docs/v1/contentOwners/list

data/lib/yt/collections/playlist_items.rb

@@ -24,7 +24,7 @@ module Yt
       end
 
       def insert_parts
-        {snippet: {keys: [:playlist_id, :resource_id]}}
+        {snippet: {keys: [:playlist_id, :resource_id, :position]}}
       end
     end
   end

data/lib/yt/collections/resources.rb

@@ -39,7 +39,7 @@ module Yt
       def build_insert_body_part(part, attributes = {})
         {}.tap do |body_part|
           part[:keys].map do |key|
-            body_part[camelize key] = attributes[key]
+            body_part[camelize key] = attributes[key] if attributes[key]
           end
         end
       end

data/lib/yt/collections/subscribed_channels.rb

@@ -0,0 +1,46 @@
+require 'yt/collections/channels'
+
+module Yt
+  module Collections
+    # Provides methods to interact with the list of channels a resource is
+    # subscribed to.
+    #
+    # Resources with subscribed channels are: {Yt::Models::Channel channels}.
+    #
+    class SubscribedChannels < Channels
+
+    private
+
+      def attributes_for_new_item(data)
+        snippet = data.fetch 'snippet', {}
+        resource = snippet.fetch 'resourceId', {}
+        {id: resource['channelId'], snippet: snippet, auth: @auth}
+      end
+
+      # @return [Hash] the parameters to submit to YouTube to list subscribers.
+      # @see https://developers.google.com/youtube/v3/docs/subscriptions/list
+      def list_params
+        super.tap{|params| params[:path] = '/youtube/v3/subscriptions'}
+      end
+
+      # @private
+      # @note Subscribers overwrites +channel_params+ since the query
+      #   is slightly different.
+      def channels_params
+        {}.tap do |params|
+          params[:max_results] = 50
+          params[:part] = 'snippet'
+          params[:channel_id] = @parent.id
+          apply_where_params! params
+        end
+      end
+
+      # @private
+      # @note Subscribers overwrites +list_resources+ since the objects to
+      #   instatiate belongs to Channel class not Subscriber.
+      def resource_class
+        Yt::Models::Channel
+      end
+    end
+  end
+end

data/lib/yt/collections/subscribers.rb

@@ -0,0 +1,33 @@
+require 'yt/collections/subscribed_channels'
+
+module Yt
+  module Collections
+    # Provides methods to interact with subscribers of a YouTube resource.
+    #
+    # Resources with subscribers are: {Yt::Models::Account accounts}.
+    #
+    # Confusingly, YouTube API provides the +same+ endpoint to either
+    # retrieve the channels that you are subscribed to or the channels
+    # that are subscribed to you. The difference relies in the setting the
+    # +mySubscribers+ parameter to true and in reading the information
+    # from the +subscriberSnippet+ part, not the +snippet+ part.
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions/list
+    class Subscribers < SubscribedChannels
+
+    private
+
+      def attributes_for_new_item(data)
+        snippet = data.fetch 'subscriberSnippet', {}
+        {id: snippet['channelId'], snippet: snippet, auth: @auth}
+      end
+
+      def channels_params
+        {}.tap do |params|
+          params[:max_results] = 50
+          params[:part] = 'subscriberSnippet'
+          params[:my_subscribers] = true
+        end
+      end
+    end
+  end
+end

data/lib/yt/collections/subscriptions.rb

@@ -6,7 +6,6 @@ module Yt
     class Subscriptions < Base
 
       def insert(options = {})
-        throttle
         do_insert
       rescue Yt::Error => error
         ignorable_error = error.reasons.include? 'subscriptionDuplicate'
@@ -14,34 +13,12 @@ module Yt
         raise error unless options[:ignore_errors] && ignorable_error
       end
 
-      def delete_all(params = {}, options = {})
-        throttle
-        do_delete_all params, options
-      end
-
     private
 
       def attributes_for_new_item(data)
         {id: data['id'], auth: @auth}
       end
 
-      # @note Google API must have some caching layer by which if we try to
-      # delete a subscription that we just created, we encounter an error.
-      # To overcome this, if we have just updated the subscription, we must
-      # wait some time before requesting it again.
-      #
-      def throttle(seconds = 11)
-        @last_changed_at ||= Time.now - seconds
-        wait = [@last_changed_at - Time.now + seconds, 0].max
-        sleep wait
-        @last_changed_at = Time.now
-      end
-
-      def fetch_page(params = {})
-        throttle
-        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

data/lib/yt/models/account.rb

@@ -9,7 +9,8 @@ module Yt
       # @!attribute [r] channel
       #   @return [Yt::Models::Channel] the account’s channel.
       has_one :channel
-      delegate :playlists, :create_playlist, :delete_playlists, to: :channel
+      delegate :playlists, :create_playlist, :delete_playlists,
+        :subscribed_channels, to: :channel
 
       # @!attribute [r] user_info
       #   @return [Yt::Models::UserInfo] the account’s profile information.
@@ -21,6 +22,10 @@ module Yt
       #   @return [Yt::Collections::Videos] the videos owned by the account.
       has_many :videos
 
+      # @!attribute [r] subscribers
+      #   @return [Yt::Collections::Subscribers] the channels subscribed to the account.
+      has_many :subscribers
+
       # @return [String] name of the CMS account, if the account is partnered.
       # @return [nil] if the account is not a partnered content owner.
       attr_reader :owner_name

data/lib/yt/models/annotation.rb

@@ -4,7 +4,7 @@ module Yt
     # @note YouTube API V3 does not provide access to video annotations,
     #   therefore a legacy XML endpoint is used to retrieve annotations.
     # @see https://www.youtube.com/yt/playbook/annotations.html
-    class Annotation
+    class Annotation < Base
       # @param [Hash] options the options to initialize an Annotation.
       # @option options [String] :data The XML representation of an annotation
       def initialize(options = {})
@@ -77,9 +77,7 @@ module Yt
         @text ||= @data['TEXT'] || ''
       end
 
-      def type
-        @type ||= @data.fetch 'type', ''
-      end
+      has_attribute :type, default: ''
 
       def link_class
         @link_class ||= url['link_class']
@@ -93,9 +91,7 @@ module Yt
         @url ||= action.fetch 'url', {}
       end
 
-      def action
-        @action ||= @data.fetch 'action', {}
-      end
+      has_attribute :action, default: {}
 
       def top
         @top ||= positions.map{|pos| pos['y'].to_f}.max
@@ -129,9 +125,7 @@ module Yt
         @region ||= segment.fetch 'movingRegion', {}
       end
 
-      def segment
-        @segment ||= (@data['segment'] || {})
-      end
+      has_attribute :segment, type: Hash
     end
   end
 end

data/lib/yt/models/asset.rb

@@ -42,9 +42,7 @@ module Yt
 
       # @return [String] the ID that YouTube assigns and uses to uniquely
       #   identify the asset.
-      def id
-        @id ||= @data['id']
-      end
+      has_attribute :id
 
       # @return [String] the asset’s type. This value determines the metadata
       #   fields that you can set for the asset. In addition, certain API
@@ -54,9 +52,7 @@ module Yt
       #   Valid values for this property are: art_track_video, composition,
       #   episode, general, movie, music_video, season, show, sound_recording,
       #   video_game, and web.
-      def type
-        @type ||= @data['type']
-      end
+      has_attribute :type
 
 # Status
 
@@ -68,9 +64,7 @@ module Yt
       #   the status of an asset, so it’s impossible to update, although the
       #   documentation says this should be the case. If YouTube ever fixes
       #   the API, then the following code can be uncommented.
-      # def status
-      #   @status ||= @data["status"]
-      # end
+      # has_attribute :status
       #
       # # @return [Boolean] whether the asset is active.
       # def active?
@@ -97,7 +91,6 @@ module Yt
           params[:params] = {on_behalf_of_content_owner: @auth.owner_name}
         end
       end
-
     end
   end
 end