entrez 0.5.7 → 0.5.8

data/README.rdoc

@@ -93,6 +93,21 @@ NCBI recommends no more than 3 URL requests per second: http://www.ncbi.nlm.nih.
 This gem respects this limit. It will delay the next request if the last 3 have been made within 1 second.
 The amount of delay time is no more than what is necessary to make the next request "respectful".
 
+=== Ignore query limits for testing
+
+If you use something like FakeWeb for testing, and you don't want to slow down your tests, tell Entrez to ignore the query limit:
+
+  require 'entrez/spec_helpers'
+  it 'does something that I promise will not bother NCBI' do
+    Entrez.ignore_query_limit do
+      # Anything that happens within this block will ignore the query limit.
+      # So make sure you do not actually request queries from NCBI.
+      # For example:
+      FakeWeb.allow_net_connect = false
+    end
+    # Query limits are respected again outside of the block.
+  end
+
 == Compatibility
 
 http://test.rubygems.org/gems/entrez

data/lib/entrez.rb

@@ -1,14 +1,18 @@
 require 'httparty'
 require 'httparty/response_ext'
 require 'query_string_normalizer'
+require 'entrez/options'
+require 'entrez/query_limit'
 
-class Entrez
+module Entrez
 
   include HTTParty
   base_uri 'http://eutils.ncbi.nlm.nih.gov/entrez/eutils'
   default_params tool: 'ruby', email: (ENV['ENTREZ_EMAIL'] || raise('please set ENTREZ_EMAIL environment variable'))
   query_string_normalizer QueryStringNormalizer
 
+  extend QueryLimit
+
   class << self
 
     # E.g. Entrez.EFetch('snp', id: 123, retmode: :xml)
@@ -35,8 +39,7 @@ class Entrez
     end
 
     def perform(utility_path, db, params = {})
-      respect_query_limit
-      request_times << Time.now.to_f
+      respect_query_limit unless ignore_query_limit?
       get utility_path, :query => {db: db}.merge(params)
     end
 
@@ -55,27 +58,6 @@ class Entrez
       str
     end
 
-    private
-
-    # NCBI does not allow more than 3 requests per second.
-    # Unless 3 requests ago was more than 1 second ago,
-    # sleep for enough time to honor limit.
-    def respect_query_limit
-      three_requests_ago = request_times[-3]
-      return unless three_requests_ago
-      time_for_last_3_requeests = Time.now.to_f - three_requests_ago
-      enough_time_has_passed = time_for_last_3_requeests >= 1
-      unless enough_time_has_passed
-        sleep_time = 1 - time_for_last_3_requeests
-        STDERR.puts "sleeping #{sleep_time}"
-        sleep(sleep_time)
-      end
-    end
-
-    def request_times
-      @request_times ||= []
-    end
-
   end
 
   class UnknownOperator < StandardError

data/lib/entrez/options.rb

@@ -0,0 +1,11 @@
+module Entrez
+
+  class << self
+
+    def options
+      @options ||= {respect_query_limit: true}
+    end
+
+  end
+
+end

data/lib/entrez/query_limit.rb

@@ -0,0 +1,35 @@
+module Entrez
+  module QueryLimit
+
+    private
+
+    # NCBI does not allow more than 3 requests per second.
+    # If the last 3 requests happened within the last 1 second,
+    # sleep for enough time to let a full 1 second pass before the next request.
+    # Add current time to queue.
+    def respect_query_limit
+      now = Time.now.to_f
+      three_requests_ago = request_times[-3]
+      request_times << now
+      return unless three_requests_ago
+      time_for_last_3_requeests = now - three_requests_ago
+      enough_time_has_passed = time_for_last_3_requeests >= 1.0
+      unless enough_time_has_passed
+        sleep_time = 1 - time_for_last_3_requeests
+        STDERR.puts "sleeping #{sleep_time}"
+        sleep(sleep_time)
+      end
+    end
+
+    def request_times
+      @request_times ||= []
+    end
+
+    # Only way to set this should be through requiring entrez/spec_helpers and
+    # calling Entrez.ignore_query_limit(&block).
+    def ignore_query_limit?
+      !!@ignore_query_limit
+    end
+
+  end
+end

data/lib/entrez/spec_helpers.rb

@@ -0,0 +1,12 @@
+Entrez.extend(Module.new do
+
+  # For the duration of the block, Entrez requests will ignore query limit.
+  # FOR TESTING ONLY WHERE NO REQUESTS ARE MADE TO NCBI.
+  # REQUESTS MUST BE STUBBED/FAKED.
+  def ignore_query_limit(&block)
+    @ignore_query_limit = true
+    block.call
+    @ignore_query_limit = false
+  end
+
+end)

data/lib/entrez/version.rb

@@ -1,3 +1,3 @@
 module Entrez
-  VERSION = "0.5.7"
+  VERSION = "0.5.8"
 end

data/spec/entrez_spec.rb

@@ -41,13 +41,6 @@ describe Entrez do
 
   end
 
-  it 'should respect query limit' do
-    fake_service :ESearch, 'esearch_empty.xml' do
-      requests = proc { 4.times { Entrez.ESearch('asdf') } }
-      requests.should take_longer_than(1.0)
-    end
-  end
-
   it 'should convert search term hash into query string with AND operator by default' do
     query_string = {TITL: 'BRCA1', ORGN: 'human'}
     Entrez.convert_search_term_hash(query_string).should == 'BRCA1[TITL]+AND+human[ORGN]'

data/spec/query_limit_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe 'Entrez#respect_query_limit' do
+
+  it 'should not perform more than 3 queries per second' do
+    fake_service :ESearch, 'esearch_empty.xml', ignore_query_limit: false do
+      requests = proc { 4.times { Entrez.ESearch('asdf') } }
+      requests.should take_longer_than(1.0)
+    end
+  end
+
+  it 'can be disabled for testing such as when FakeWeb is used' do
+    Entrez.ignore_query_limit do
+      fake_service :ESearch, 'esearch_empty.xml' do
+        requests = proc { 4.times { Entrez.ESearch('asdf') } }
+        requests.should_not take_longer_than(1.0)
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -2,11 +2,18 @@ require 'awesome_print'
 require 'fakeweb'
 require 'pathname'
 
+# Require the gem source.
 require File.join(Pathname(__FILE__).dirname.expand_path, '../lib/entrez')
-Entrez.default_params(
-  retmode: :xml,
-)
+require 'entrez/spec_helpers'
+
+# Require spec/support files.
 Dir[File.expand_path("../support/**/*.rb", __FILE__)].each {|f| require f}
+
 RSpec.configure do |config|
   config.include(Macros)
 end
+
+# Default return mode to XML.
+Entrez.default_params(
+  retmode: :xml,
+)

data/spec/support/macros.rb

@@ -16,10 +16,15 @@ module Macros
   # Since the generated URL is a bit difficult to capture,
   # Faked uri will just match regular expression of service.
   # When block ends, clean registry.
-  def fake_service(service, fixture_file_name)
+  # Ignore Entrez query limit unless told not to.
+  def fake_service(service, fixture_file_name, options = {}, &block)
     file_contents = fixture_file(fixture_file_name).read
     FakeWeb.register_uri(:get, Regexp.new(service.to_s.downcase), body: file_contents, content_type: 'text/xml')
-    yield
+    if options.fetch(:ignore_query_limit, true)
+      Entrez.ignore_query_limit(&block)
+    else
+      block.call
+    end
   ensure
     FakeWeb.clean_registry
   end

data/spec/support/matchers.rb

@@ -1,7 +1,7 @@
 RSpec::Matchers.define :take_longer_than do |seconds|
   match do |process|
     @elapsed_time = timer(&process)
-    @elapsed_time.should > seconds
+    @elapsed_time > seconds
   end
   failure_message_for_should do
     "Expected process to take longer than #{seconds} seconds (actual: #{@elapsed_time})"

metadata

@@ -2,7 +2,7 @@
 name: entrez
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors: 
 - Jared Ning
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-15 00:00:00 -05:00
+date: 2011-08-17 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -76,11 +76,15 @@ files:
 - Rakefile
 - entrez.gemspec
 - lib/entrez.rb
+- lib/entrez/options.rb
+- lib/entrez/query_limit.rb
+- lib/entrez/spec_helpers.rb
 - lib/entrez/version.rb
 - lib/httparty/response/ids.rb
 - lib/httparty/response_ext.rb
 - lib/query_string_normalizer.rb
 - spec/entrez_spec.rb
+- spec/query_limit_spec.rb
 - spec/query_string_normalizer_spec.rb
 - spec/response_ids_spec.rb
 - spec/spec_helper.rb
@@ -119,6 +123,7 @@ specification_version: 3
 summary: HTTP requests to Entrez E-utilities
 test_files: 
 - spec/entrez_spec.rb
+- spec/query_limit_spec.rb
 - spec/query_string_normalizer_spec.rb
 - spec/response_ids_spec.rb
 - spec/spec_helper.rb