entrez 0.1.1 → 0.2.0

data/README.rdoc

@@ -2,6 +2,17 @@
 
 Entrez is a simple API for making HTTP requests to Entrez utilities (eutils: http://eutils.ncbi.nlm.nih.gov/).
 
+== Installation
+
+  gem install entrez
+
+or if you use Bundler awesomeness:
+
+  # Gemfile
+  gem 'entrez'
+
+It requires httparty.
+
 == Usage
 
 Entrez.efetch(<database>, parameters)
@@ -20,9 +31,19 @@ Email is obtained from an environment variable ENTREZ_EMAIL on your computer.
 I set mine in my ~/.bash_profile:
   export ENTREZ_EMAIL='jared@redningja.com'
 
+== NCBI query limits
+
+NCBI recommends no more than 3 URL requests per second: http://www.ncbi.nlm.nih.gov/books/NBK25497/#chapter2.Usage_Guidelines_and_Requiremen
+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".
+
 == What about EInfo, ESummary, EPost, ESearch, ELink, EGQuery, and ESpell?
 
 For my purposes, I only needed EFetch.
 But if you would like to contribute, please feel free.
 After seeing the code, assuming you know how to submit requests to einfo et al,
-It should be trivial to implement them here.
+It should be easy to implement them here.
+
+== Compatibility
+
+http://test.rubygems.org/gems/entrez

data/Rakefile

@@ -1,2 +1,9 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+
+task :default => :test
+
+desc 'Run rspec tests'
+task :test do
+  sh 'rspec spec/'
+end

data/lib/entrez.rb

@@ -9,9 +9,29 @@ class Entrez
   class << self
 
     def efetch(db, params = {})
+      respect_query_limit
+      request_times << Time.now.to_f
       get '/efetch.fcgi', :query => {db: db}.merge(params)
     end
 
+    def request_times
+      @request_times ||= []
+    end
+
+    private
+
+    def respect_query_limit
+      three_requests_ago = request_times[-3]
+      return unless three_requests_ago
+      three_requests_ago = three_requests_ago.to_f
+      now = Time.now.to_f
+      enough_time_has_passed = now > three_requests_ago + 1
+      unless enough_time_has_passed
+        STDERR.puts "sleeping #{now - three_requests_ago}"
+        sleep(now - three_requests_ago)
+      end
+    end
+
   end
 
 end

data/lib/entrez/version.rb

@@ -1,3 +1,3 @@
 module Entrez
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/entrez_spec.rb

@@ -8,8 +8,12 @@ describe Entrez do
   end
 
   it 'should efetch results' do
-    rs_number = 9268480.to_s
-    Entrez.efetch('snp', {id: rs_number, retmode: 'xml'}).should eq(file_fixture('efetch.xml'))
+    Entrez.efetch('snp', {id: 9268480, retmode: 'xml'}).should eq(file_fixture('efetch.xml'))
+  end
+
+  it 'should respect query limit' do
+    requests = proc { 4.times { Entrez.efetch('snp', id: 9268480) } }
+    requests.should take_longer_than(1.0)
   end
 
 end

data/spec/support/macros.rb

@@ -4,4 +4,12 @@ module Macros
     File.open(File.join(File.dirname(__FILE__), 'fixtures/', file_name)).read
   end
 
+  # Return how long it takes to run block.
+  def timer
+    start_time = Time.now
+    yield
+    end_time = Time.now
+    end_time - start_time
+  end
+
 end

data/spec/support/matchers.rb

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

metadata

@@ -1,12 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: entrez
 version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
+  prerelease: 
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jared Ning
@@ -14,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-03 00:00:00 -06:00
+date: 2011-03-07 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -25,8 +21,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 0
         version: "0"
   type: :runtime
   version_requirements: *id001
@@ -38,10 +32,6 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 2
-        - 4
-        - 0
         version: 2.4.0
   type: :development
   version_requirements: *id002
@@ -55,6 +45,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- .gemtest
 - .gitignore
 - .rvmrc
 - Gemfile
@@ -67,6 +58,7 @@ files:
 - spec/spec_helper.rb
 - spec/support/fixtures/efetch.xml
 - spec/support/macros.rb
+- spec/support/matchers.rb
 has_rdoc: true
 homepage: https://github.com/ordinaryzelig/entrez
 licenses: []
@@ -81,21 +73,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: entrez
-rubygems_version: 1.3.7
+rubygems_version: 1.6.1
 signing_key: 
 specification_version: 3
 summary: HTTP requests to Entrez E-utilities
@@ -104,3 +92,4 @@ test_files:
 - spec/spec_helper.rb
 - spec/support/fixtures/efetch.xml
 - spec/support/macros.rb
+- spec/support/matchers.rb