yt 0.15.2 → 0.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fe92325f41cffdb8e81da539742c539cc3280fd0
-  data.tar.gz: 40ccb712b549661f2cd905dfed5870cf14d77f4e
+  metadata.gz: 955b88eeaa4654c03880228bf322546eb0fba3c3
+  data.tar.gz: 8b5bbaf09793909b2230180a49107a58f0f69ed7
 SHA512:
-  metadata.gz: 2567686bcaae799d503506e063ec171e16fa7ed975e9fb78d053c971c1aad144c0d3bdabc10daf7ad69b30045ef8c8edb945c37d0b19ed007cb5d664b774e9c4
-  data.tar.gz: 6283dfcb5b3288c2bf1f66bd15833a5bd073982f253b759c3fceb665c6c29ce7e373073aa0a9e1243b82167e5b58f9e7d1ae8f02f90a2764ac77289279398e0c
+  metadata.gz: 6715a5ff1ec202aa3f1d678aea12baa21f87daf15f1234c3b24e4e0be298b62db322ea1c6ea8e948fd4345a49ca15d27aa3b03237f0f8249d0fea67f371cbcc8
+  data.tar.gz: eac8f4472b3c814986f3c41469357043019648e523edfef4aafdf4ef3003a4d4700e5c3b2d6eb17df799ed750ebd0372057ecfa2946b3196e0dc43e1df944b60

data/CHANGELOG.md

@@ -7,6 +7,12 @@ For more information about changelogs, check
 [Vandamme](http://tech-angels.github.io/vandamme).
 
 
+## 0.15.3 - 2015-04-27
+
+* [FEATURE] New `file_size`, `file_type`, `container` methods for Yt::Video.
+* [BUGFIX] Retrieve `category_id` also for videos obtained through a search.
+* [FEATURE] Add .includes(:category) to .videos in order to eager-load category title and ID of a collection of videos
+
 ## 0.15.2 - 2015-04-27
 
 * [FEATURE] New `embed_html` method for Yt::Video.

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.15.2'
+    gem 'yt', '~> 0.15.3'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
@@ -310,6 +310,8 @@ Use [Yt::Video](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Video)
 * retrieve data about live-streaming videos
 * retrieve the advertising options of a video
 * retrieve the HTML code of the video player
+* retrieve the file details of a video
+* retrieve the category title of a video
 
 ```ruby
 # Videos can be initialized with ID or URL
@@ -368,6 +370,12 @@ video.concurrent_viewers #=> 0
 
 video.embed_html #=> "<iframe type='text/html' src='http://www.youtube.com/embed/BPNYv0vd78A' width='640' height='360' frameborder='0' allowfullscreen='true'/>"
 
+video.file_size #=> 8000000
+video.file_type #=> "video"
+video.container #=> "mov"
+
+video.category_title #=> "People & Blogs"
+
 video.annotations.count #=> 1
 video.annotations.first #=> #<Yt::Models::Annotation @id=...>
 ```
@@ -913,9 +921,3 @@ the [YouTube Analytics API](https://developers.google.com/youtube/analytics).
 If you find that a method is missing, fork the project, add the missing code,
 write the appropriate tests, then submit a pull request, and it will gladly
 be merged!
-
-Don’t hesitate to send code comments, issues or pull requests through GitHub
-and to spread the love on Twitter by following [@ytgem](https://twitter.com/intent/user?screen_name=ytgem) – 
-all feedback is appreciated.
-
-![yt4](https://cloud.githubusercontent.com/assets/7408595/3638115/0ef9d6bc-1037-11e4-831a-787204e9b979.png)

data/lib/yt/collections/file_details.rb

@@ -0,0 +1,29 @@
+require 'yt/collections/base'
+require 'yt/models/file_detail'
+
+module Yt
+  module Collections
+    class FileDetails < Base
+
+    private
+
+      def attributes_for_new_item(data)
+        {data: data['fileDetails']}
+      end
+
+      # @return [Hash] the parameters to submit to YouTube to get the
+      #   file detail of a video.
+      # @see https://developers.google.com/youtube/v3/docs/videos#fileDetails
+      def list_params
+        super.tap do |params|
+          params[:params] = file_details_params
+          params[:path] = '/youtube/v3/videos'
+        end
+      end
+
+      def file_details_params
+        {max_results: 50, part: 'fileDetails', id: @parent.id}
+      end
+    end
+  end
+end

data/lib/yt/collections/video_categories.rb

@@ -0,0 +1,35 @@
+require 'yt/collections/base'
+require 'yt/models/video_category'
+
+module Yt
+  module Collections
+    class VideoCategories < Base
+
+    private
+
+      def attributes_for_new_item(data)
+        {}.tap do |attributes|
+          attributes[:id] = data['id']
+          attributes[:snippet] = data['snippet']
+          attributes[:auth] = @auth
+        end
+      end
+
+      # @return [Hash] the parameters to submit to YouTube to list video categories.
+      # @see https://developers.google.com/youtube/v3/docs/videoCategories/list
+      def list_params
+        super.tap do |params|
+          params[:params] = video_categories_params
+        end
+      end
+
+      def video_categories_params
+        {}.tap do |params|
+          params[:part] = 'snippet'
+          params[:id] = @parent.category_id if @parent
+          apply_where_params! params
+        end
+      end
+    end
+  end
+end

data/lib/yt/collections/videos.rb

@@ -24,12 +24,16 @@ module Yt
           attributes[:status] = data['status']
           attributes[:content_details] = data['contentDetails']
           attributes[:statistics] = data['statistics']
+          attributes[:video_category] = data['videoCategory']
           attributes[:auth] = @auth
         end
       end
 
       def eager_load_items_from(items)
         if included_relationships.any?
+          include_category = included_relationships.delete(:category)
+          included_relationships.append(:snippet).uniq! if include_category
+
           ids = items.map{|item| item['id']['videoId']}
           parts = included_relationships.map{|r| r.to_s.camelize(:lower)}
           conditions = {id: ids.join(','), part: parts.join(',')}
@@ -46,6 +50,17 @@ module Yt
               end
             end
           end
+
+          if include_category
+            category_ids = items.map{|item| item['snippet']['categoryId']}.uniq
+            conditions = {id: category_ids.join(',')}
+            video_categories = Collections::VideoCategories.new(auth: @auth).where conditions
+
+            items.each do |item|
+              video_category = video_categories.find{|v| v.id == item['snippet']['categoryId']}
+              item['videoCategory'] = video_category.data
+            end
+          end
         end
         super
       end

data/lib/yt/models/file_detail.rb

@@ -0,0 +1,26 @@
+require 'yt/models/base'
+
+module Yt
+  module Models
+    # Encapsulates basic information about the video file itself,
+    # including the file name, size, type, and container.
+    # @see https://developers.google.com/youtube/v3/docs/videos#fileDetails
+    class FileDetail < Base
+      attr_reader :data
+
+      def initialize(options = {})
+        @data = options[:data] || {}
+      end
+
+      # @return [Integer] the file size of the video (in bytes).
+      has_attribute :file_size, type: Integer
+
+      # @return [String] the file type of the file. May be one of:
+      #   archive, audio, document, image, other, project, or video.
+      has_attribute :file_type
+
+      # @return [String] the container of the video (e.g. 'mov').
+      has_attribute :container
+    end
+  end
+end

data/lib/yt/models/snippet.rb

@@ -147,9 +147,9 @@ module Yt
       end
 
       # Returns whether YouTube API includes all attributes in this snippet.
-      # For instance, YouTube API only returns tags on Videos#list, not on
-      # Videos#search. And returns position on PlaylistItems#list, not on
-      # PlaylistItems#insert.
+      # For instance, YouTube API only returns tags and categoryId on
+      # Videos#list, not on Videos#search. And returns position on
+      # PlaylistItems#list, not on PlaylistItems#insert.
       # This method is used to guarantee that, when a video was instantiated
       # by one of the methods above, an additional call to is made to retrieve
       # the full snippet in case an attribute is missing.

data/lib/yt/models/video.rb

@@ -23,6 +23,11 @@ module Yt
       delegate :duration, :hd?, :stereoscopic?, :captioned?, :licensed?,
         to: :content_detail
 
+      # @!attribute [r] file_detail
+      #   @return [Yt::Models::FileDetail] the video’s file details.
+      has_one :file_detail
+      delegate :file_size, :file_type, :container, to: :file_detail
+
       has_one :advertising_options_set
       delegate :ad_formats, to: :advertising_options_set
 
@@ -30,6 +35,11 @@ module Yt
       #   @return [Yt::Models::Rating] the video’s rating.
       has_one :rating
 
+      # @!attribute [r] video_category
+      #   @return [Yt::Models::VideoCategory] the video’s category.
+      has_one :video_category
+      delegate :title, to: :video_category, prefix: :category
+
       # @!attribute [r] live_streaming_detail
       #   @return [Yt::Models::LiveStreamingDetail] live streaming detail.
       has_one :live_streaming_detail
@@ -131,6 +141,12 @@ module Yt
         if options[:content_details]
           @content_detail = ContentDetail.new data: options[:content_details]
         end
+        if options[:file_details]
+          @file_detail = FileDetail.new data: options[:file_details]
+        end
+        if options[:video_category]
+          @video_category = VideoCategory.new data: options[:video_category]
+        end
       end
 
       # Returns the list of keyword tags associated with the video.
@@ -148,6 +164,20 @@ module Yt
         snippet.tags
       end
 
+      # Returns the category ID associated with the video.
+      # Since YouTube API only returns categoryID on Videos#list, the memoized
+      # @snippet is erased if the video was instantiated through Video#search
+      # (e.g., by calling account.videos or channel.videos), so that the full
+      # snippet (with categoryID) is loaded, rather than the partial one.
+      # @see https://developers.google.com/youtube/v3/docs/videos
+      # @return [String] ID of the YouTube category associated with the video.
+      def category_id
+        unless snippet.category_id.present? || snippet.complete?
+          @snippet = nil
+        end
+        snippet.category_id
+      end
+
       # Deletes the video.
       #
       # This method requires {Resource#auth auth} to return an authenticated
@@ -273,4 +303,4 @@ module Yt
       end
     end
   end
-end
+end

data/lib/yt/models/video_category.rb

@@ -0,0 +1,11 @@
+require 'yt/models/resource'
+
+module Yt
+  module Models
+    # Provides methods to interact with YouTube video categories.
+    # @see https://developers.google.com/youtube/v3/docs/videoCategories
+    class VideoCategory < Resource
+      delegate :data, :title, to: :snippet
+    end
+  end
+end

data/lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.15.2'
+  VERSION = '0.15.3'
 end

data/spec/models/file_detail_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+require 'yt/models/file_detail'
+
+describe Yt::FileDetail do
+  subject(:file_detail) { Yt::FileDetail.new data: data }
+
+  describe '#data' do
+    let(:data) { {"key"=>"value"} }
+    specify 'returns the data the file detail was initialized with' do
+      expect(file_detail.data).to eq data
+    end
+  end
+
+  describe '#file_size' do
+    context 'given a video with fileSize' do
+      let(:data) { {"fileSize"=>"8000000"} }
+      it { expect(file_detail.file_size).to be 8_000_000 }
+    end
+  end
+
+  describe '#file_type' do
+    context 'given a video with fileType' do
+      let(:data) { {"fileType"=>"video"} }
+      it { expect(file_detail.file_type).to eq 'video' }
+    end
+  end
+
+  describe '#container' do
+    context 'given a video with container' do
+      let(:data) { {"container"=>"mov"} }
+      it { expect(file_detail.container).to eq 'mov' }
+    end
+  end
+end

data/spec/models/player_spec.rb

@@ -7,7 +7,7 @@ describe Yt::Player do
 
   describe '#data' do
     let(:data) { {"key"=>"value"} }
-    specify 'returns the data the statistics set was initialized with' do
+    specify 'returns the data the player was initialized with' do
       expect(player.data).to eq data
     end
   end

data/spec/models/video_category_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+require 'yt/models/video_category'
+
+describe Yt::VideoCategory do
+  subject(:video_category) { Yt::VideoCategory.new attrs }
+
+  describe '#id' do
+    context 'given fetching a video category returns an id' do
+      let(:attrs) { {id: "22"} }
+      it { expect(video_category.id).to eq '22' }
+    end
+  end
+
+  describe '#snippet' do
+    context 'given fetching a video category returns a snippet' do
+      let(:attrs) { {snippet: {"title": "People & Blogs", "assignable": true}} }
+
+      it { expect(video_category.snippet).to be_a Yt::Snippet }
+    end
+  end
+end

data/spec/requests/as_account/account_spec.rb

@@ -21,9 +21,10 @@ describe Yt::Account, :device_app do
   describe '.videos' do
     let(:video) { $account.videos.where(order: 'viewCount').first }
 
-    specify 'returns the videos uploaded by the account with their tags' do
+    specify 'returns the videos uploaded by the account with their tags and category ID' do
       expect(video).to be_a Yt::Video
       expect(video.tags).not_to be_empty
+      expect(video.category_id).not_to be_nil
     end
 
     describe '.where(q: query_string)' do

data/spec/requests/as_account/channel_spec.rb

@@ -24,7 +24,7 @@ describe Yt::Channel, :device_app do
     describe '.videos' do
       let(:video) { channel.videos.first }
 
-      specify 'returns the videos in the channel without their tags' do
+      specify 'returns the videos in the channel without tags or category ID' do
         expect(video).to be_a Yt::Video
         expect(video.snippet).not_to be_complete
       end
@@ -62,6 +62,14 @@ describe Yt::Channel, :device_app do
         end
       end
 
+      describe '.includes(:category)' do
+        let(:video) { channel.videos.includes(:category, :status).first }
+
+        specify 'eager-loads the category (id and title) of each video' do
+          expect(video.instance_variable_defined? :@snippet).to be true
+          expect(video.instance_variable_defined? :@video_category).to be true
+        end
+      end
 
       describe 'when the channel has more than 500 videos' do
         let(:id) { 'UCsmvakQZlvGsyjyOhmhvOsw' }

data/spec/requests/as_account/video_spec.rb

@@ -64,6 +64,7 @@ describe Yt::Video, :device_app do
       expect(video.scheduled_end_time).to be_nil
       expect(video.concurrent_viewers).to be_nil
       expect(video.embed_html).to be_a String
+      expect(video.category_title).to be_a String
     end
 
     it { expect{video.update}.to fail }
@@ -119,6 +120,7 @@ describe Yt::Video, :device_app do
     it { expect{video.rating}.to raise_error Yt::Errors::NoItems }
     it { expect{video.status}.to raise_error Yt::Errors::NoItems }
     it { expect{video.statistics_set}.to raise_error Yt::Errors::NoItems }
+    it { expect{video.file_detail}.to raise_error Yt::Errors::NoItems }
   end
 
   context 'given one of my own videos that I want to delete' do
@@ -280,7 +282,7 @@ describe Yt::Video, :device_app do
 
     it 'returns valid reports for video-related metrics' do
       # Some reports are only available to Content Owners.
-      # See content ownere test for more details about what the methods return.
+      # See content owner test for more details about what the methods return.
       expect{video.views}.not_to raise_error
       expect{video.comments}.not_to raise_error
       expect{video.likes}.not_to raise_error
@@ -389,4 +391,22 @@ describe Yt::Video, :device_app do
       it { expect{update}.to raise_error Yt::Errors::RequestError }
     end
   end
-end
+
+  # @note: This test is separated from the block above because YouTube only
+  #   returns file details for *some videos*: "The fileDetails object will
+  #   only be returned if the processingDetails.fileAvailability property
+  #   has a value of available.". Therefore, just to test fileDetails, we use a
+  #   different video that (for some unknown reason) is marked as 'available'.
+  #   Also note that I was not able to find a single video returning fileName,
+  #   therefore video.file_name is not returned by Yt, until it can be tested.
+  # @see https://developers.google.com/youtube/v3/docs/videos#processingDetails.fileDetailsAvailability
+  context 'given one of my own *available* videos' do
+    let(:id) { 'yCmaOvUFhlI' }
+
+    it 'returns valid file details' do
+      expect(video.file_size).to be_an Integer
+      expect(video.file_type).to be_a String
+      expect(video.container).to be_a String
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yt
 version: !ruby/object:Gem::Version
-  version: 0.15.2
+  version: 0.15.3
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -142,6 +142,7 @@ files:
 - lib/yt/collections/content_owner_details.rb
 - lib/yt/collections/content_owners.rb
 - lib/yt/collections/device_flows.rb
+- lib/yt/collections/file_details.rb
 - lib/yt/collections/ids.rb
 - lib/yt/collections/live_streaming_details.rb
 - lib/yt/collections/ownerships.rb
@@ -162,6 +163,7 @@ files:
 - lib/yt/collections/subscribers.rb
 - lib/yt/collections/subscriptions.rb
 - lib/yt/collections/user_infos.rb
+- lib/yt/collections/video_categories.rb
 - lib/yt/collections/videos.rb
 - lib/yt/collections/viewer_percentages.rb
 - lib/yt/config.rb
@@ -189,6 +191,7 @@ files:
 - lib/yt/models/content_owner_detail.rb
 - lib/yt/models/description.rb
 - lib/yt/models/device_flow.rb
+- lib/yt/models/file_detail.rb
 - lib/yt/models/id.rb
 - lib/yt/models/iterator.rb
 - lib/yt/models/live_streaming_detail.rb
@@ -212,6 +215,7 @@ files:
 - lib/yt/models/url.rb
 - lib/yt/models/user_info.rb
 - lib/yt/models/video.rb
+- lib/yt/models/video_category.rb
 - lib/yt/request.rb
 - lib/yt/version.rb
 - spec/collections/claims_spec.rb
@@ -239,6 +243,7 @@ files:
 - spec/models/content_detail_spec.rb
 - spec/models/content_owner_detail_spec.rb
 - spec/models/description_spec.rb
+- spec/models/file_detail_spec.rb
 - spec/models/live_streaming_detail_spec.rb
 - spec/models/ownership_spec.rb
 - spec/models/player_spec.rb
@@ -257,6 +262,7 @@ files:
 - spec/models/subscription_spec.rb
 - spec/models/url_spec.rb
 - spec/models/user_info_spec.rb
+- spec/models/video_category_spec.rb
 - spec/models/video_spec.rb
 - spec/requests/as_account/account_spec.rb
 - spec/requests/as_account/authentications_spec.rb
@@ -341,6 +347,7 @@ test_files:
 - spec/models/content_detail_spec.rb
 - spec/models/content_owner_detail_spec.rb
 - spec/models/description_spec.rb
+- spec/models/file_detail_spec.rb
 - spec/models/live_streaming_detail_spec.rb
 - spec/models/ownership_spec.rb
 - spec/models/player_spec.rb
@@ -359,6 +366,7 @@ test_files:
 - spec/models/subscription_spec.rb
 - spec/models/url_spec.rb
 - spec/models/user_info_spec.rb
+- spec/models/video_category_spec.rb
 - spec/models/video_spec.rb
 - spec/requests/as_account/account_spec.rb
 - spec/requests/as_account/authentications_spec.rb