youtube-g 0.4.1 → 0.4.9.9

data/History.txt

@@ -1,3 +1,27 @@
+== 0.4.9.9 / 2008-09-01
+
+* Add Geodata information (thanks Jose Galisteo)
+* Added :page and :per_page options, this allows easier usage of the will_paginate
+  plugin with the library. The :offset and :max_results options are no longer available. [Daniel Insley]
+* Added ability to get video responses on the instances of the YouTube::Model::Video object. [Daniel Insley]
+* Added and improved the existing documentation [Daniel Insley]
+* Fixed usage of deprecated yt:racy, now using media:rating [Daniel Insley]
+* Renamed can_embed? method to embeddable? [Daniel Insley]
+* Added ability for padingation and ordering on standard feeds. [Daniel Insley]
+* Add error-handling for video upload errors. [FiXato]
+* Add error-handling for authentication errors from YouTube during video upload. [FiXato]
+* Add support for making videos private upon video upload. [FiXato]
+* Fix issue with REXML parsing of video upload response. [FiXato]
+* Fix issue with response code comparison. [FiXato]
+* Authcode is now retrieved for video uploads. [FiXato]
+* Add basic support for uploading videos [thanks Joe Damato]
+* Add basic support for related videos [tmm1]
+* Improve docs for order_by attribute [thanks Jason Arora]
+* Added support for the "racy" parameter (choices are "include" or "exclude") [thanks Jason Arora]
+* Add missing attribute reader for description [tmm1]
+* Fix issue with missing yt:statistics and viewCount [tmm1]
+* Allow Client#video_by to take either a url or a video id [tmm1]
+
 == 0.4.1 / 2008-02-11
 
 * Added 3GPP video format [shane]

data/Manifest.txt

@@ -17,7 +17,11 @@ lib/youtube_g/model/user.rb
 lib/youtube_g/model/video.rb
 lib/youtube_g/parser.rb
 lib/youtube_g/record.rb
+lib/youtube_g/request/base_search.rb
+lib/youtube_g/request/standard_search.rb
+lib/youtube_g/request/user_search.rb
 lib/youtube_g/request/video_search.rb
+lib/youtube_g/request/video_upload.rb
 lib/youtube_g/response/video_search.rb
 test/test_client.rb
 test/test_video.rb

data/README.txt

@@ -1,6 +1,9 @@
 youtube-g
     by Shane Vitarana and Walter Korman
-    http://rubyforge.org/projects/youtube-g/
+
+  Rubyforge: http://rubyforge.org/projects/youtube-g/
+  RDoc: http://youtube-g.rubyforge.org/
+  Google Group: http://groups.google.com/group/ruby-youtube-library
 
 == DESCRIPTION:
 
@@ -23,13 +26,13 @@ http://code.google.com/apis/youtube/overview.html
 
 Create a client:
   
-  require 'rubygems'
   require 'youtube_g'
   client = YouTubeG::Client.new
   
 Basic queries:
 
   client.videos_by(:query => "penguin")
+  client.videos_by(:query => "penguin", :page => 2, :per_page => 15)
   client.videos_by(:tags => ['tiger', 'leopard'])
   client.videos_by(:categories => [:news, :sports])
   client.videos_by(:categories => [:news, :sports], :tags => ['soccer', 'football'])
@@ -38,6 +41,7 @@ Basic queries:
 Standard feeds:
 	
   client.videos_by(:most_viewed)
+  client.videos_by(:most_linked, :page => 3)
   client.videos_by(:top_rated, :time => :today)
 	
 Advanced queries (with boolean operators OR (either), AND (include), NOT (exclude)):

data/TODO.txt

@@ -1,12 +1,10 @@
 [ ] stub out http request/response cycle for tests
-[ ] consider defaulting the client to no-logger, rather than outputting to STDOUT.
 [ ] allow specifying values as single items where you don't need to wrap in a list, e.g. :tags => :chickens instead of :tags => [ 'chickens' ]
 [ ] make sure symbols will work as well as tags everywhere (again, :tags => :chickens is same as :tags => 'chickens')
 [ ] figure out better structure for class/file (either rename request/video_search.rb or split into one class per file again)
 [ ] restore spaces after method def names
 [ ] use a proxy for testing with static sample result xml so we have repeatable tests
 [ ] Clean up tests using Shoulda to define contexts
-[ ] Consolidate requires
 [ ] Allow :category and :categories for query DSL
 [ ] Exception handling
 

data/lib/youtube_g.rb

@@ -1,3 +1,10 @@
+require 'logger'
+require 'open-uri'
+require 'net/https'
+require 'digest/md5'
+require 'rexml/document'
+require 'cgi'
+
 require File.dirname(__FILE__) + '/youtube_g/client'
 require File.dirname(__FILE__) + '/youtube_g/record'
 require File.dirname(__FILE__) + '/youtube_g/parser'
@@ -10,9 +17,13 @@ require File.dirname(__FILE__) + '/youtube_g/model/rating'
 require File.dirname(__FILE__) + '/youtube_g/model/thumbnail'
 require File.dirname(__FILE__) + '/youtube_g/model/user'
 require File.dirname(__FILE__) + '/youtube_g/model/video'
+require File.dirname(__FILE__) + '/youtube_g/request/base_search'
+require File.dirname(__FILE__) + '/youtube_g/request/user_search'
+require File.dirname(__FILE__) + '/youtube_g/request/standard_search'
+require File.dirname(__FILE__) + '/youtube_g/request/video_upload'
 require File.dirname(__FILE__) + '/youtube_g/request/video_search'
 require File.dirname(__FILE__) + '/youtube_g/response/video_search'
 
-class YouTubeG
-  VERSION = '0.4.1'
+class YouTubeG #:nodoc:
+  VERSION = '0.4.9.9'
 end

data/lib/youtube_g/client.rb

@@ -1,35 +1,85 @@
-require 'logger'
-
 class YouTubeG
   class Client
     attr_accessor :logger
     
-    def initialize(logger=Logger.new(STDOUT))
-      @logger = logger
+    def initialize(logger=false)
+      @logger = Logger.new(STDOUT) if logger
     end
-
-    # Params can be one of :most_viewed, :top_rated, :recently_featured, :watch_on_mobile
-    # Or :tags, :categories, :query, :user
+    
+    # Retrieves an array of standard feed, custom query, or user videos.
+    # 
+    # === Parameters
+    # If fetching videos for a standard feed:
+    #   params<Symbol>:: Accepts a symbol of :top_rated, :top_favorites, :most_viewed, 
+    #                    :most_popular, :most_recent, :most_discussed, :most_linked, 
+    #                    :most_responded, :recently_featured, and :watch_on_mobile.
+    #  
+    #   You can find out more specific information about what each standard feed provides
+    #   by visiting: http://code.google.com/apis/youtube/reference.html#Standard_feeds                 
+    #   
+    #   options<Hash> (optional)::  Accepts the options of :time, :page (default is 1), 
+    #                               and :per_page (default is 25). :offset and :max_results
+    #                               can also be passed for a custom offset.
+    #  
+    # If fetching videos by tags, categories, query:
+    #   params<Hash>:: Accepts the keys :tags, :categories, :query, :order_by, 
+    #                  :author, :racy, :response_format, :video_format, :page (default is 1), 
+    #                  and :per_page(default is 25)
+    #                  
+    #   options<Hash>:: Not used. (Optional)
+    # 
+    # If fetching videos for a particular user:
+    #   params<Hash>:: Key of :user with a value of the username.
+    #   options<Hash>:: Not used. (Optional)
+    # === Returns
+    # YouTubeG::Response::VideoSearch
     def videos_by(params, options={})
+      request_params = params.respond_to?(:to_hash) ? params : options
+      request_params[:page] = integer_or_default(request_params[:page], 1)
+      
+      unless request_params[:max_results]
+        request_params[:max_results] = integer_or_default(request_params[:per_page], 25)
+      end
+      
+      unless request_params[:offset]
+        request_params[:offset] = calculate_offset(request_params[:page], request_params[:max_results] )
+      end
+      
       if params.respond_to?(:to_hash) and not params[:user]
-        request = YouTubeG::Request::VideoSearch.new(params)
-
+        request = YouTubeG::Request::VideoSearch.new(request_params)
       elsif (params.respond_to?(:to_hash) && params[:user]) || (params == :favorites)
-        request = YouTubeG::Request::UserSearch.new(params, options)
-
+        request = YouTubeG::Request::UserSearch.new(request_params, options)
       else
-        request = YouTubeG::Request::StandardSearch.new(params, options)
+        request = YouTubeG::Request::StandardSearch.new(params, request_params)
       end
       
-      logger.debug "Submitting request [url=#{request.url}]."
+      logger.debug "Submitting request [url=#{request.url}]." if logger
       parser = YouTubeG::Parser::VideosFeedParser.new(request.url)
       parser.parse
     end
     
-    def video_by(video_id)
+    # Retrieves a single YouTube video.
+    #
+    # === Parameters
+    #   vid<String>:: The ID or URL of the video that you'd like to retrieve.
+    # 
+    # === Returns
+    # YouTubeG::Model::Video
+    def video_by(vid)
+      video_id = vid =~ /^http/ ? vid : "http://gdata.youtube.com/feeds/videos/#{vid}"
       parser = YouTubeG::Parser::VideoFeedParser.new(video_id)
       parser.parse
     end
     
+    private
+    
+    def calculate_offset(page, per_page)
+      page == 1 ? 1 : ((per_page * page) - per_page + 1)
+    end
+    
+    def integer_or_default(value, default)
+      value = value.to_i
+      value > 0 ? value : default
+    end
   end
 end

data/lib/youtube_g/logger.rb

@@ -1,5 +1,3 @@
-require 'logger'
-
 class YouTubeG
   
   # TODO: Why is this needed? Does this happen if running standalone w/o Rails?

data/lib/youtube_g/model/author.rb

@@ -1,7 +1,10 @@
 class YouTubeG
   module Model
     class Author < YouTubeG::Record
+      # *String*: Author's YouTube username.
       attr_reader :name
+      
+      # *String*: Feed URL of the author.
       attr_reader :uri
     end
   end

data/lib/youtube_g/model/category.rb

@@ -1,7 +1,10 @@
 class YouTubeG
   module Model
     class Category < YouTubeG::Record
-      attr_reader :label
+      # *String*:: Name of the YouTube category
+      attr_reader :label 
+      
+      # *String*:: Identifies the type of item described.
       attr_reader :term
     end
   end

data/lib/youtube_g/model/contact.rb

@@ -1,7 +1,15 @@
 class YouTubeG
   module Model
     class Contact < YouTubeG::Record
+      # *String*:: Identifies the status of a contact.
+      #
+      # * The tag's value will be accepted if the authenticated user and the contact have marked each other as friends.
+      # * The tag's value will be requested if the contact has asked to be added to the authenticated user's contact list, but the request has not yet been accepted (or rejected).
+      # * The tag's value will be pending if the authenticated user has asked to be added to the contact's contact list, but the request has not yet been accepted or rejected.
+      #
       attr_reader :status
+      
+      # *String*:: The Youtube username of the contact.
       attr_reader :username
     end
   end

data/lib/youtube_g/model/content.rb

@@ -1,10 +1,15 @@
 class YouTubeG
   module Model
     class Content < YouTubeG::Record
+      # *Boolean*:: Description of the video.
       attr_reader :default
+      # *Fixnum*:: Length of the video in seconds.
       attr_reader :duration
+      # YouTubeG::Model::Video::Format:: Specifies the video format of the video object
       attr_reader :format
+      # *String*:: Specifies the MIME type of the media object.
       attr_reader :mime_type
+      # *String*:: Specifies the URL for the media object.
       attr_reader :url
       
       alias :is_default? :default

data/lib/youtube_g/model/playlist.rb

@@ -1,6 +1,7 @@
 class YouTubeG
   module Model
     class Playlist < YouTubeG::Record
+      # *String*:: User entered description for the playlist.
       attr_reader :description
     end
   end

data/lib/youtube_g/model/rating.rb

@@ -1,9 +1,16 @@
 class YouTubeG
   module Model
     class Rating < YouTubeG::Record
+      # *Float*:: Average rating given to the video
       attr_reader :average
+      
+      # *Fixnum*:: Maximum rating that can be assigned to the video
       attr_reader :max
+      
+      # *Fixnum*:: Minimum rating that can be assigned to the video
       attr_reader :min
+      
+      # *Fixnum*:: Indicates how many people have rated the video
       attr_reader :rater_count
     end
   end

data/lib/youtube_g/model/thumbnail.rb

@@ -1,9 +1,16 @@
 class YouTubeG
   module Model
     class Thumbnail < YouTubeG::Record
+      # *String*:: URL for the thumbnail image.
       attr_reader :url
+      
+      # *Fixnum*:: Height of the thumbnail image.
       attr_reader :height
+      
+      # *Fixnum*:: Width of the thumbnail image.
       attr_reader :width
+      
+      # *String*:: Specifies the time offset at which the frame shown in the thumbnail image appears in the video.
       attr_reader :time
     end
   end

data/lib/youtube_g/model/video.rb

@@ -1,87 +1,171 @@
+# TODO
+#  * self atom feed
+#  * alternate youtube watch url
+#  * comments feedLink
+
 class YouTubeG
   module Model
     class Video < YouTubeG::Record
       # Describes the various file formats in which a Youtube video may be
       # made available and allows looking them up by format code number.
-      #
       class Format
         @@formats = Hash.new
 
+        # Instantiates a new video format object.
+        #
+        # == Parameters
+        #   :format_code<Fixnum>:: The Youtube Format code of the object. 
+        #   :name<Symbol>:: The name of the format
+        #   
+        # == Returns
+        #   YouTubeG::Model::Video::Format: Video format object
         def initialize(format_code, name)
           @format_code = format_code
           @name = name
 
           @@formats[format_code] = self          
         end
-
+        
+        # Allows you to get the video format for a specific format code.
+        # 
+        # A full list of format codes is available at:
+        # 
+        # http://code.google.com/apis/youtube/reference.html#youtube_data_api_tag_media:content
+        #
+        # == Parameters
+        #   :format_code<Fixnum>:: The Youtube Format code of the object. 
+        #   
+        # == Returns
+        #   YouTubeG::Model::Video::Format: Video format object
         def self.by_code(format_code)
           @@formats[format_code]
         end
 
-        # Flash format on YouTube site. All videos are available in this
-        # format.
-        #
+        # Flash format on YouTube site. All videos are available in this format.
         FLASH = YouTubeG::Model::Video::Format.new(0, :flash)
 
-        # RTSP streaming URL for mobile video playback. H.263 video (176x144)
-        # and AMR audio.
-        #
+        # RTSP streaming URL for mobile video playback. H.263 video (176x144) and AMR audio.
         RTSP = YouTubeG::Model::Video::Format.new(1, :rtsp)
 
         # HTTP URL to the embeddable player (SWF) for this video. This format
         # is not available for a video that is not embeddable.
-        #
         SWF = YouTubeG::Model::Video::Format.new(5, :swf)
         
+        # RTSP streaming URL for mobile video playback. MPEG-4 SP video (up to 176x144) and AAC audio.
         THREE_GPP = YouTubeG::Model::Video::Format.new(6, :three_gpp)
       end
-
+      
+      # *Fixnum*:: Duration of a video in seconds.
       attr_reader :duration
+      
+      # *Boolean*:: Specifies that a video may or may not be embedded on other websites.
       attr_reader :noembed
+      
+      # *Fixnum*:: Specifies the order in which the video appears in a playlist.
       attr_reader :position
+      
+      # *Boolean*:: Specifies that a video is flagged as adult or not.
       attr_reader :racy
-      attr_reader :statistics
       
+      # *String*: Specifies a URI that uniquely and permanently identifies the video.
       attr_reader :video_id
+      
+      # *Time*:: When the video was published on Youtube.
       attr_reader :published_at
+      
+      # *Time*:: When the video's data was last updated.
       attr_reader :updated_at
+      
+      # *Array*:: A array of YouTubeG::Model::Category objects that describe the videos categories. 
       attr_reader :categories
+      
+      # *Array*:: An array of words associated with the video.
       attr_reader :keywords
+      
+      # *String*:: Description of the video.
+      attr_reader :description
+      
+      # *String*:: Title for the video.
       attr_reader :title
+      
+      # *String*:: Description of the video.
       attr_reader :html_content
+      
+      # YouTubeG::Model::Author:: Information about the YouTube user who owns a piece of video content.
       attr_reader :author
-
-      # YouTubeG::Model::Content records describing the individual media content
-      # data available for this video.  Most, but not all, videos offer this.
+      
+      # *Array*:: An array of YouTubeG::Model::Content objects describing the individual media content data available for this video.  Most, but not all, videos offer this.
       attr_reader :media_content
-
-      attr_reader :thumbnails         # YouTubeG::Model::Thumbnail records
+      
+      # *Array*:: An array of YouTubeG::Model::Thumbnail objects that contain information regarding the videos thumbnail images. 
+      attr_reader :thumbnails
+      
+      # *String*:: The link to watch the URL on YouTubes website.
       attr_reader :player_url
+      
+      # YouTubeG::Model::Rating:: Information about the videos rating.
       attr_reader :rating
+      
+      # *Fixnum*:: Number of times that the video has been viewed
       attr_reader :view_count
 
-      # TODO:
-      # self atom feed
-      # alternate youtube watch url
-      # responses feed
-      # related feed
-      # comments feedLink
-      
-      # For convenience, the video_id with the URL stripped out, useful for searching for the video again
-      # without having to store it anywhere. A regular query search, with this id will return the same video.
-      # http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o
+      # Geodata
+      attr_reader :where
+      attr_reader :position
+      attr_reader :latitude
+      attr_reader :longitude
+      
+      attr_reader :statistics
+      
+      # Videos related to the current video.
+      #
+      # === Returns
+      #   YouTubeG::Response::VideoSearch
+      def related
+        YouTubeG::Parser::VideosFeedParser.new("http://gdata.youtube.com/feeds/api/videos/#{unique_id}/related").parse
+      end
+      
+      # Video responses to the current video.
+      #
+      # === Returns
+      #   YouTubeG::Response::VideoSearch   
+      def responses
+        YouTubeG::Parser::VideosFeedParser.new("http://gdata.youtube.com/feeds/api/videos/#{unique_id}/responses").parse
+      end
+      
+      # The ID of the video, useful for searching for the video again without having to store it anywhere. 
+      # A regular query search, with this id will return the same video.
+      # 
+      # === Example
+      #   >> video.unique_id
+      #   => "ZTUVgYoeN_o"
+      #   
+      # === Returns
+      #   String: The Youtube video id.
       def unique_id
-        video_id.match(/videos\/([^<]+)/).captures.first
+        video_id[/videos\/([^<]+)/, 1]
       end
       
-      def can_embed?
+      # Allows you to check whether the video can be embedded on a webpage.
+      #
+      # === Returns
+      #   Boolean: True if the video can be embedded, false if not.
+      def embeddable?
         not @noembed
       end
       
+      # Provides a URL and various other types of information about a video.
+      # 
+      # === Returns
+      #   YouTubeG::Model::Content: Data about the embeddable video.
       def default_media_content
         @media_content.find { |c| c.is_default? }
       end
       
+      # Gives you the HTML to embed the video on your website.
+      #
+      # === Returns
+      #   String: The HTML for embedding the video on your website.
       def embed_html(width = 425, height = 350)
         <<EDOC
 <object width="#{width}" height="#{height}">
@@ -93,6 +177,10 @@ class YouTubeG
 EDOC
       end
 
+      # The URL needed for embedding the video in a page.
+      #
+      # === Returns
+      #   String: Absolute URL for embedding video
       def embed_url
         @player_url.sub('watch?', '').sub('=', '/')          
       end