donors_choose 0.9.0 → 1.0.0

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/cassettes/1.8/DonorsChoose_Request.yml

@@ -0,0 +1,109 @@
+--- 
+- !ruby/struct:VCR::HTTPInteraction 
+  request: !ruby/struct:VCR::Request 
+    method: :get
+    uri: http://api.donorschoose.org:80/common/json_feed.html?APIKey=DONORSCHOOSE&community=1007:3&state=NC
+    body: 
+    headers: 
+  response: !ruby/struct:VCR::Response 
+    status: !ruby/struct:VCR::ResponseStatus 
+      code: 200
+      message: OK
+    headers: 
+      server: 
+        - nginx
+      content-type: 
+        - text/plain;charset=UTF-8
+      content-language: 
+        - en-US
+      cache-control: 
+        - private, max-age=582
+      expires: 
+        - Wed, 15 Feb 2012 21:43:28 GMT
+      date: 
+        - Wed, 15 Feb 2012 21:33:46 GMT
+      content-length: 
+        - "796"
+      connection: 
+        - keep-alive
+      x-n: 
+        - S
+    body: |
+      
+       
+      
+      
+      
+      
+      
+      
+       
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      	
+      
+      	  	
+      
+      
+      
+      
+      
+      
+      
+      {"searchTerms":"+cityid:1007 AND +statecode:NC AND +historical:fall +_val_:"add(product(10.0,staticNewbie),add(product(100.0,recal(add(ms(NOW,explorationth),3.16911),3.16e-11,1,1)),add(product(10000.0,add(product(1.25,sun(5.0, static)),product(0.75,stationor))),add(product(100000.0,stationeri),add(product(1000000.0,sun(10.0,staticNeedBinary)),0)))))" > Many Farms, Arizona","searchURL":"http://www.donorschoose.org/donors/search.html?community=1007%3a3&state=NC&utm_source=api&utm_medium=feed&utm_content=searchlink&utm_campaign=DONORSCHOOSE","totalProposals":"0","index":"0","max":"10","proposals":[]}
+
+    http_version: "1.1"

data/cassettes/{DonorsChoose_Request.yml → not_1.8/DonorsChoose_Request.yml}

@@ -19,9 +19,9 @@
       cache-control:
       - private, max-age=600
       expires:
-      - Tue, 14 Feb 2012 20:01:14 GMT
+      - Wed, 15 Feb 2012 21:43:36 GMT
       date:
-      - Tue, 14 Feb 2012 19:51:14 GMT
+      - Wed, 15 Feb 2012 21:33:36 GMT
       content-length:
       - '796'
       connection:

data/donors_choose.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rspec"
   gem.add_development_dependency "vcr"
   gem.add_development_dependency "webmock"
+  gem.add_development_dependency "yard"
 end

data/lib/donors_choose.rb

@@ -1,19 +1,19 @@
 require 'donors_choose/version'
 require 'donors_choose/request'
+require 'donors_choose/project'
 
+# This module provides the entry point for the library. Everything here
+# is considered public, the rest of the objects are essentially internal.
 module DonorsChoose
-  extend self
-
-  attr_writer :api_key
-  def api_key
-    @api_key || "DONORSCHOOSE"
+  # An API key is needed to make requests. Get one
+  # [here](http://developer.donorschoose.org/help-contact).
+  def self.api_key=(key)
+    @api_key = key
   end
 
-  def projects_near_me(latitude, longitude)
-    Request.get(:centerLat => latitude, :centerLong => longitude)
-  end
-
-  def projects_by_zip(zipcode)
-    Request.get(:keyword => zipcode)
+  # We default to the development key that works for everyone. Set it to
+  # something else in production environments.
+  def self.api_key
+    @api_key || "DONORSCHOOSE"
   end
 end

data/lib/donors_choose/project.rb

@@ -0,0 +1,14 @@
+# This API allows us to find information about DonorsChoose projects,
+# so a Project is the main class of the gem.
+class DonorsChoose::Project
+
+  # This method finds all projects near a given latitude and longitude.
+  def self.near_me(latitude, longitude)
+    DonorsChoose::Request.get(:centerLat => latitude, :centerLong => longitude)
+  end
+
+  # This method allows you to look up all projects by a zip code.
+  def self.by_zip(zipcode)
+    DonorsChoose::Request.get(:zip => zipcode)
+  end
+end

data/lib/donors_choose/request.rb

@@ -4,26 +4,43 @@ require 'net/http'
 require 'json'
 require 'ostruct'
 
+# This class provides a wrapper around all of the external interaction
+# we'll be doing. It's kinda important, given we're wrapping an API. ;)
 class DonorsChoose::Request
-   def self.get(params)
-    new(params).get
+
+  # This method is a convenient factory method, and is the easiest way
+  # to make a single request and get the data back.
+  def self.get(params)
+    new(params).process
   end
 
+  # This API operates through making GET requests to an endpoint. It takes
+  # a few different parameters to control how the data is acquired. We'll
+  # just take those so we can properly construct the request.
   def initialize(params)
     @params = params
   end
 
-  def get
-    data = JSON.parse(fetch)["proposals"]
+  # This method is the main business process of this class: get the data,
+  # parse the JSON it returns, grab the proposal list, and then build a
+  # list of objects with the data.
+  def process
+    data = JSON.parse(get)["proposals"]
     data.collect {|datum| OpenStruct.new(datum)}
   end
 
-  def fetch
+  # This method wraps Net::HTTP, basically. We build up our own parameter
+  # list, construct our URI, and fetch it.
+  def get
     base_uri = 'http://api.donorschoose.org/common/json_feed.html'
-    uri_params = @params.collect do |key, value|
+    Net::HTTP.get(URI(base_uri + "?" + uri_params))
+  end
+
+  def uri_params
+    params = @params.dup.collect do |key, value|
       "#{key}=#{CGI.escape(value.to_s)}"
     end
-    uri_params = [uri_params, "APIKey=#{DonorsChoose.api_key}"].join("&")
-    Net::HTTP.get(URI(base_uri + "?" + uri_params))
+    params << "APIKey=#{DonorsChoose.api_key}"
+    params.join("&")
   end
 end

data/lib/donors_choose/version.rb

@@ -1,3 +1,4 @@
 module DonorsChoose
-  VERSION = "0.9.0"
+  # The current version of the gem.
+  VERSION = "1.0.0"
 end

data/spec/donors_choose_spec.rb

@@ -5,30 +5,6 @@ describe DonorsChoose do
   it "is able to have an API key set" do
     key = "this isn't an API key"
     DonorsChoose.api_key = key
-    DonorsChoose.api_key.should eql(key)
-  end
-
-  context "requesting data" do
-    let(:test_title) { "A test project" }
-
-    it "is able to find projects near me" do
-      projects = [double]
-      DonorsChoose::Request.should_receive(:get).
-        with(:centerLat => "40.4405556", :centerLong => "-79.9961111").
-        and_return(projects)
-
-      results = DonorsChoose.projects_near_me("40.4405556", "-79.9961111")
-      results.should eq(projects)
-    end
-
-    it "is able to find projects by zip code" do
-      projects = [double]
-      DonorsChoose::Request.should_receive(:get).
-        with(:keyword => "15232").
-        and_return(projects)
-
-      results = DonorsChoose.projects_by_zip("15232")
-      results.should eq(projects)
-    end
+    DonorsChoose.api_key.should eq(key)
   end
 end

data/spec/project_spec.rb

@@ -0,0 +1,26 @@
+$:.unshift("lib")
+require 'donors_choose'
+
+describe DonorsChoose::Project do
+  let(:test_title) { "A test project" }
+
+  it "is able to find projects near me" do
+    projects = [double]
+    DonorsChoose::Request.should_receive(:get).
+      with(:centerLat => "40.4405556", :centerLong => "-79.9961111").
+      and_return(projects)
+
+    results = DonorsChoose::Project.near_me("40.4405556", "-79.9961111")
+    results.should eq(projects)
+  end
+
+  it "is able to find projects by zip code" do
+    projects = [double]
+    DonorsChoose::Request.should_receive(:get).
+      with(:zip => "15232").
+      and_return(projects)
+
+    results = DonorsChoose::Project.by_zip("15232")
+    results.should eq(projects)
+  end
+end

data/spec/request_spec.rb

@@ -3,9 +3,10 @@ require 'donors_choose/request'
 
 require 'vcr'
 require 'webmock'
+YAML_SERIALIZATION_VERSION = RUBY_VERSION =~ /1\.8/ ? '1.8' : 'not_1.8'
 VCR.config do |c|
+  c.cassette_library_dir = File.join(File.dirname(__FILE__), '..', 'cassettes', YAML_SERIALIZATION_VERSION)
   c.stub_with :webmock
-  c.cassette_library_dir = 'cassettes'
 end
 
 RSpec.configure do |config|
@@ -20,6 +21,6 @@ describe DonorsChoose::Request do
 
     request = DonorsChoose::Request.new({:state => "NC",
                                          :community => "1007:3"})
-    request.fetch.should_not be_nil
+    request.process.should_not be_nil
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: donors_choose
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-14 00:00:00.000000000 Z
+date: 2012-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70326897943640 !ruby/object:Gem::Requirement
+  requirement: &70192143544040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70326897943640
+  version_requirements: *70192143544040
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70326897943120 !ruby/object:Gem::Requirement
+  requirement: &70192143543600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70326897943120
+  version_requirements: *70192143543600
 - !ruby/object:Gem::Dependency
   name: vcr
-  requirement: &70326897942580 !ruby/object:Gem::Requirement
+  requirement: &70192143543140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70326897942580
+  version_requirements: *70192143543140
 - !ruby/object:Gem::Dependency
   name: webmock
-  requirement: &70326897941960 !ruby/object:Gem::Requirement
+  requirement: &70192143542700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70326897941960
+  version_requirements: *70192143542700
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70192143542260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70192143542260
 description: A gem to wrap the DonorsChoose.org API.
 email:
 - steve@steveklabnik.com
@@ -65,16 +76,20 @@ files:
 - .gitignore
 - .rvmrc
 - .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
-- cassettes/DonorsChoose_Request.yml
+- cassettes/1.8/DonorsChoose_Request.yml
+- cassettes/not_1.8/DonorsChoose_Request.yml
 - donors_choose.gemspec
 - lib/donors_choose.rb
+- lib/donors_choose/project.rb
 - lib/donors_choose/request.rb
 - lib/donors_choose/version.rb
 - spec/donors_choose_spec.rb
+- spec/project_spec.rb
 - spec/request_spec.rb
 homepage: http://github.com/jumpstartlab/donors_choose
 licenses: []
@@ -102,4 +117,6 @@ specification_version: 3
 summary: A gem to wrap the DonorsChoose.org API.
 test_files:
 - spec/donors_choose_spec.rb
+- spec/project_spec.rb
 - spec/request_spec.rb
+has_rdoc: