yourub 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f4ebd119d0c0ca1c91826ac02c6fd172fc0f9119
-  data.tar.gz: 5c4ceed6b992398e35b173e44a3b29f31b065ca0
+  metadata.gz: 3dd41972b4391d0680edfb6a53c4ffac3251ec10
+  data.tar.gz: 56d7304673339a8ee102c0ac93e5736f877453f4
 SHA512:
-  metadata.gz: 4a460508012396828652e043c2f2bc5f90c61651145a78117e2f962b3a6ad545fe79722c188037f8430802eaa4209f99543b932db574c669aa5b931eb72f31a7
-  data.tar.gz: 947f855feac11c2ce095c102dbd01a42898750dae9f3411afb0c2fbf354928c6c5a073b41c5b1b0911c38cd9eebcc1595ca21193cb7251bb4a27d0e213f9a280
+  metadata.gz: 197357a9f8930cf34a8230c871d7315df3361b3db59f6c42df6ace9e5308770fd9cff323b961fd02d4936006d6dd9e7edbeeb3fe7bc1f3d8636350538c909e35
+  data.tar.gz: e69618e8f18d5aa6eb9d8a76bf0f949cac2ed1effcd57ccce6a837917e1628d8966338c41bc7c7391b6bb9b3f825e99d8026d02b10cf9871b49bca9402376736

data/.gitignore

@@ -1,20 +1,17 @@
 *.gem
 *.rbc
 *.sublime-workspace
+spec/yourub/integration_spec.rb
 .bundle
 .config/*
 .yardoc
 Gemfile.lock
 InstalledFiles
 _yardoc
-coverage
-doc/
+coverage/*
+doc/*
 lib/bundler/man
 lib/yourub/DEVELOPER_KEY
 lib/yourub/cli.rb
 pkg
 rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp

data/Gemfile

@@ -1,5 +1,19 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in yourub.gemspec
+gem 'rake'
+gem 'yard'
+
+group :development do
+  gem 'byebug'
+end
+
+group :test do
+  gem 'coveralls'
+  gem 'rspec', '>= 3.00'
+  gem 'rubocop', '>= 0.27'
+  gem 'simplecov', '>= 0.9'
+  gem 'webmock'
+end
+
 gemspec
 

data/README.md

@@ -20,7 +20,8 @@ Or install it yourself as:
 ## Usage
 
 Get a developer key as explained [here](http://www.youtube.com/watch?v=Im69kzhpR3I)
-If you are using rails, create a app/config/yourub.yml file as follow:
+After that, you have 2 ways to use the client. If you want to use it in your
+rails app,  create a app/config/yourub.yml file as follow:
 ```
 yourub_defaults: &yourub_defaults
   developer_key: 'YoUrDevEl0PerKey'
@@ -40,44 +41,57 @@ test:
   <<: *yourub_defaults
 ```
 
-### Available parameters
-`:query` String, example `aliens`
-
-`:id` Sting, a valid youtube video id, example `NisCkxU544c`. If this parameter is set, tha others are ignored
-
-`:country` String, one or more alpha-2 country codes [ISO 3166-1](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm), example `US` or `IT, DE`. The default one is `US`
-
-`:category` String, example `comedy`. It accept the wildcard `all`, that retrieves videos for all the category for the given nation, or the default one (US) if no one is given
-
-`:count_filter` Hash, example `{views: ">= 100"}` or `{views: "== 600"}`
+If you want to use it from the console, or in another program, you can simply
+pass an hash containing the needed option
+```ruby
+options = { developer_key: 'mySecretKey',
+             application_name: 'yourub',
+             application_version: 2.0,
+             log_level: 3 }
 
-`:max_results` Integer, between 1 and 50
+client = Yourub::Client.new(options)
+```
 
-`:order` String, one of these: 'date', 'rating', 'relevance', 'title', 'videocount', 'viewcount'. The default one is `'relevance'`
 
-It's necessary at least one of this parameters to start a search: `:country`, `:category`, `:query`, `:id`
- 
 ### Examples
 
 For example, to find the most recent videos in the category "sports" in Germany
 ```ruby
 client = Yourub::Client.new
-client.search(country: "DE", category: "sports", order: 'date')
-client.videos
+client.search(country: "DE", category: "sports", order: 'date') do |v|
+  puts v
+end
 ```
 
 To find video for a specific thema, use the parameter query
 
 ```ruby
 client = Yourub::Client.new
-client.search(query: "aliens")
-client.videos
+client.search(query: "aliens") do |v|
+  puts v
+end
 ```
 that is the content of the response:
 ```
 [{"kind"=>"youtube#video", "etag"=>"\"N5Eg36Gl054SUNiWWc-Su3t5O-k/U6AzLXvcnZt2WFqpnq9_dksV7DA\"", "id"=>"NisCkxU544c", "snippet"=>{"publishedAt"=>"2009-04-05T05:20:10.000Z", "channelId"=>"UCCHcEUksSVKsRDH86j77Ntg", "title"=>"Like A Boss (ft. Seth Rogen) - Uncensored Version", "description"=>"http://www.itunes.com/thelonelyisland\r\n\r\nThe new single from The Lonely Island's debut album \"INCREDIBAD\" In stores now!\r\n\r\nFeaturing Seth Rogen.\r\n\r\nThe Lonely Island is Andy Samberg, Akiva Schaffer & Jorma Taccone.", "thumbnails"=>{"default"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/default.jpg", "width"=>120, "height"=>90}, "medium"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/mqdefault.jpg", "width"=>320, "height"=>180}, "high"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/hqdefault.jpg", "width"=>480, "height"=>360}, "standard"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/sddefault.jpg", "width"=>640, "height"=>480}, "maxres"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/maxresdefault.jpg", "width"=>1280, "height"=>720}}, "channelTitle"=>"thelonelyisland", "categoryId"=>"23", "liveBroadcastContent"=>"none"}, "statistics"=>{"viewCount"=>"120176425", "likeCount"=>"594592", "dislikeCount"=>"15121", "favoriteCount"=>"0", "commentCount"=>"208109"}}]
 ```
+### Available parameters
+`:query` String, example `aliens`
+
+`:id` Sting, a valid youtube video id, example `NisCkxU544c`. If this parameter is set, tha others are ignored
+
+`:country` String, one or more alpha-2 country codes [ISO 3166-1](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm), example `US` or `IT, DE`. The default one is `US`
+
+`:category` String, example `comedy`. It accept the wildcard `all`, that retrieves videos for all the category for the given nation, or the default one (US) if no one is given
+
+`:count_filter` Hash, example `{views: ">= 100"}` or `{views: "== 600"}`
 
+`:max_results` Integer, between 1 and 50
+
+`:order` String, one of these: 'date', 'rating', 'relevance', 'title', 'videocount', 'viewcount'. The default one is `'relevance'`
+
+It's necessary at least one of this parameters to start a search: `:country`, `:category`, `:query`, `:id`
+ 
 ### Methods
 `search`, search youtube videos for the given parameters
 ```ruby
@@ -93,13 +107,10 @@ client.get_views("G2b0OIkTraI")
 ```
 
 
-To have more values back, use the option `extended_info`
-##TODO
 
-1. adding a CLI
-2. the result should be yield, and not saved in an instance variable
-3. replace GoogleApiClient
-4. Implementing playlist
+##TODO
+* the result should be yield, and not saved in an instance variable
+* Implementing playlist
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,19 @@
 require "bundler/gem_tasks"
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task :erd do
+  FORMAT = 'svg'
+  `bundle exec ruby ./etc/erd.rb > ./etc/erd.dot`
+  `dot -T #{FORMAT} ./etc/erd.dot -o ./etc/erd.#{FORMAT}`
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task test: :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+task default: [:spec]

data/config/yourub.yml

@@ -1,5 +1,5 @@
 yourub_defaults: &yourub_defaults
-  developer_key: 'YOURDEVELOPERKEY'
+  developer_key: 'YourDeveloperKey'
   youtube_api_service_name: 'youtube'
   youtube_api_version: 'v3'
   application_name: "yourub"

data/lib/yourub/client.rb

@@ -1,14 +1,39 @@
-require 'yourub/rest/api'
+require 'yourub/meta_search'
 require 'google/api_client'
 
 module Yourub
   class Client < Google::APIClient
-    include Yourub::REST::API
+    include Yourub::MetaSearch
 
     attr_reader :videos
-    attr_accessor :config
 
-    def initialize()
+    # The Yourub::Client is a subclass of the Google::APIClient.
+    #
+    # @see http://www.rubydoc.info/github/google/google-api-ruby-client/Google/APIClient
+    # In order to initialize the client, you have either to provide
+    # a configuration file 'config/yourub.yml' in your main application folder
+    # or to pass an hash in the initialization.
+    # @example
+    #    #passing an hash
+    #    options = { developer_key: "a_secret_key",
+    #                application_name: "my_app",
+    #                application_version: 2.0,
+    #                log_level: "INFO"}
+    #    client = Yourub::Client.new(options)
+    #
+    # If you don't provide all the values, default values will be used.The only
+    # mandatory value is the developer_key
+    #
+    # @example
+    #   #assuming that you have a file in config/yourub.yml (see the example in
+    #   #the source repository)
+    #   client = Yourub::Client.new()
+
+    def initialize(options = {})
+      unless options.empty?
+        Yourub::Config.override_config_file(options)
+      end
+
       args = {
         :key => config.developer_key,
         :application_name => config.application_name,
@@ -18,18 +43,21 @@ module Yourub
       super(args)
     end
 
-    def config
-      Yourub::Config
-    end
-
+    # @return countries [Array] contain a list of the available alpha-2 country codes ISO 3166-1
     def countries
       Yourub::Validator.available_countries
     end
 
+    # it returns the youtube service object
+    # @see http://www.rubydoc.info/github/google/google-api-ruby-client/Google/APIClient#discovered_api-instance_method
     def youtube_api
-      @youtube_api ||= self.discovered_api(config.youtube_api_service_name,
-        config.youtube_api_version)
+      @youtube_api ||= self.discovered_api(
+        config.youtube_api_service_name, config.youtube_api_version
+      )
     end
 
+    def config
+      Yourub::Config
+    end
   end
 end

data/lib/yourub/config.rb

@@ -12,10 +12,43 @@ module Yourub
       def_delegators :@config, :developer_key,:youtube_api_service_name, :log_level,
                     :youtube_api_version, :application_name, :application_version
 
+      MANDATORY_KEYS = [:developer_key, :application_name, :application_version, :log_level]
+
+      # It loads the configuration file
+      # this method is used in the railtie.rb and in the default.rb files
+      # @example
+      #   Yourub::Config.load!(File.join("config", "yourub.yml"), 'yourub_defaults')
       def load!(file_path, environment)
         @config = OpenStruct.new YAML.load_file(file_path)[environment]
       end
-    end
 
+
+      def override_config_file(hash)
+        opt = valid_options(hash)
+        @config = OpenStruct.new opt
+      end
+
+private
+
+      def valid_options(hash)
+        opt = default_options.merge(hash)
+        raise ArgumentError.new(
+          "please provide an hash containing at least a valid developer_key"
+        ) if opt[:developer_key].empty?
+        return opt
+      end
+
+      def default_options
+        {
+          developer_key: "",
+          youtube_api_service_name: "youtube",
+          youtube_api_version: "v3",
+          application_name: "yourub",
+          application_version: Yourub::VERSION,
+          log_level: "WARN"
+        }
+      end
+
+    end
   end
 end

data/lib/yourub/default.rb

@@ -3,4 +3,4 @@ Yourub::Config.load!(File.join("config", "yourub.yml"), 'yourub_defaults')
 logger = Logger.new(STDOUT)
 logger.level = Logger.const_get(Yourub::Config.log_level.upcase)
 
-Yourub.logger = logger
+Yourub.logger = logger

data/lib/yourub/meta_search.rb

@@ -0,0 +1,134 @@
+require 'yourub/rest/api'
+
+module Yourub
+  module MetaSearch
+    include Yourub::REST::API
+
+    # Search through the youtube API, executing multiple queries where necessary
+    # @param criteria [Hash]
+    # @example
+    #   client = Yourub::Client.new
+    #   client.search(country: "DE", category: "sports", order: 'date')
+    def search(criteria)
+      begin
+        @api_options= {
+          :part            => 'snippet',
+          :type            => 'video',
+          :order           => 'relevance',
+          :safeSearch      => 'none',
+         }
+        @categories = []
+        @count_filter = {}
+        @criteria = Yourub::Validator.confirm(criteria)
+        search_by_criteria do |result|
+          yield result
+        end
+      rescue ArgumentError => e
+        Yourub.logger.error "#{e}"
+      end
+    end
+
+    # return the number of times a video was watched
+    # @param video_id[Integer]
+    # @example
+    #   client = Yourub::Client.new
+    #   client.get_views("G2b0OIkTraI")
+    def get_views(video_id)
+      params = { :id => video_id, :part => 'statistics' }
+      request = Yourub::REST::Videos.list(self,params)
+      v = Yourub::Result.format(request).first
+      v ? Yourub::CountFilter.get_views_count(v) : nil
+    end
+
+    # return an hash containing the metadata for the given video
+    # @param video_id[Integer]
+    # @example
+    #   client = Yourub::Client.new
+    #   client.get("G2b0OIkTraI")
+    def get(video_id)
+      params = {:id => video_id, :part => 'snippet,statistics'}
+      request = Yourub::REST::Videos.list(self,params)
+      Yourub::Result.format(request).first
+    end
+
+private
+
+    def search_by_criteria
+      merge_criteria_with_api_options
+      retrieve_categories
+      retrieve_videos do |res|
+        yield res
+      end
+    end
+
+    def merge_criteria_with_api_options
+      mappings = {query: :q, max_results: :maxResults, country: :regionCode}
+      @api_options.merge! @criteria
+      @api_options.keys.each do |k|
+        @api_options[ mappings[k] ] = @api_options.delete(k) if mappings[k]
+      end
+    end
+
+    def retrieve_categories
+      if @criteria.has_key? :category
+        @categories = Yourub::REST::Categories.for_country(self,@criteria[:country])
+        @categories = Yourub::Validator.valid_category(@categories, @criteria[:category])
+      end
+    end
+
+    def retrieve_videos
+      consume_criteria do |criteria|
+        begin
+          req = Yourub::REST::Search.list(self, criteria)
+          get_details_for_each_video(req) do |v|
+            yield v
+          end
+        rescue StandardError => e
+          Yourub.logger.error "Error #{e} retrieving videos for the criteria: #{criteria.to_s}"
+        end
+      end
+    end
+
+    def consume_criteria
+      to_consume = @api_options
+      if @criteria[:country]
+        @criteria[:country].each do |country|
+          to_consume[:regionCode] = country
+          consume_categories(to_consume) do |cat|
+            yield cat
+          end
+        end
+      else
+        yield to_consume
+      end
+    end
+
+    def consume_categories(to_consume)
+      if @categories.size > 0
+        @categories.each do |cat|
+          to_consume[:videoCategoryId] = cat.keys[0].to_i
+          yield to_consume
+        end
+      else
+        yield to_consume
+      end
+    end
+
+    def get_details_for_each_video(video_list)
+      video_list.data.items.each do |video_item|
+        v = Yourub::REST::Videos.single_video(self, video_item.id.videoId)
+        v = Yourub::Result.format(v)
+        if v && Yourub::CountFilter.accept?(v.first)
+          yield v.first
+        end
+      end
+    end
+
+    def add_video_to_search_result(entry)
+      if Yourub::CountFilter.accept?(entry)
+        @videos.push(entry)
+      end
+    end
+
+  end
+end

data/lib/yourub/rest/api.rb

@@ -1,4 +1,8 @@
+#require 'yourub/rest/search'
+require 'yourub/rest/request'
+require 'yourub/rest/categories'
 require 'yourub/rest/search'
+require 'yourub/rest/videos'
 
 module Yourub
   module REST
@@ -7,6 +11,8 @@ module Yourub
       # include Yourub::REST::Playlists
       # include Yourub::REST::Channels
       include Yourub::REST::Search
+      include Yourub::REST::Categories
+      include Yourub::REST::Videos
     end
   end
 end

data/lib/yourub/rest/categories.rb

@@ -0,0 +1,39 @@
+require 'yourub/rest/request'
+
+module Yourub
+  module REST
+    module Categories
+      class << self
+        # it returns an Array containing the categories for the given country,
+        # or the DEFAULT_COUNTRY if no countries was given.
+        # @param client[Yourub::Client]
+        # @param country[Array]
+        #
+        #
+        # @example
+        #   client = Yourub::Client.new
+        #   categories = Yourub::REST::Categories.for_country(client, ["US"])
+        #
+        def for_country(client, country)
+          categories = []
+          param = {"part" => "snippet","regionCode" => country }
+          categories_list = video_categories_list_request(client, param)
+          categories_list.data.items.each do |cat_result|
+            category_name = parse_name(cat_result["snippet"]["title"])
+            categories.push(cat_result["id"] => category_name)
+          end
+          return categories
+        end
+
+  private
+        def video_categories_list_request(client, params)
+          Yourub::REST::Request.new(client,"video_categories", "list", params)
+        end
+
+        def parse_name(name)
+          return name.gsub("/", "-").downcase.gsub(/\s+/, "")
+        end
+      end
+    end
+  end
+end

data/lib/yourub/rest/request.rb

@@ -2,25 +2,43 @@ module Yourub
   module REST
     class Request
       attr_reader :data, :status
-
+      #
+      # Once initializated, the Request object forward a request to 
+      # youtube api, once the request is completed, the variables @status and @data are populated
+      #
       # @param client [Yourub::Client]
       # @param resource_type [String]
       # @param method [String]
       # @param params [Hash]
+      #
       # @return [Youtube::Request]
+      # @example
+      #   Yourub::REST::Request.new(client,"video_categories", "list", param)
+      #
       def initialize(client, resource_type, method, params)
         @client = client 
-        @resource_type = resource_type
-        @method = method
+        @resource_type = resource_type.to_sym
+        @method = method.to_sym
         @params = params
         perform
       end
 
+private
+      #
+      # call the 'execute!' method on the client
+      #
+      # == Returns :
+      # The Request object with the variable @status and @data initialized
+      # @status [Int]
+      # @data [String]
+      #
       def perform
+        api_method =@client.youtube_api.send(@resource_type).send(@method) 
         r = @client.execute!(
-          :api_method => @client.youtube_api.send(@resource_type.to_sym).send(@method.to_sym),
+          :api_method => api_method,
           :parameters => @params
         )    
+        #byebug
         @data = r.data
         @status = r.status
       end