kiva 0.0.1 → 0.0.2

data/CHANGELOG

@@ -1,3 +1,7 @@
+= Version 0.0.2
+=== Mon Mar 23 16:51:54 CET 2009
+* nicer documentation
+
 = Version 0.0.1
 === Wed Mar 18 17:59:23 CET 2009
 * initial version, hope everything works 

data/README

@@ -1,33 +1,98 @@
 = kiva -- wrapper to the kiva rest API
 
-You can find more information about the API here[http://developers.wiki.kiva.org/KivaAPI]
+This is a wrapper to the Kiva Web API. You can find more information
+about the API here[http://developers.wiki.kiva.org/KivaAPI].
 
-== Installing
 
-You have to deal with this yourself. Everything seems to work, but it still needs to be
-tested and gemified, made beautiful and all the other boring stuff.
+== Example
 
+The following is an example of retrieving the last 20 loans on Kiva.
+This is about as difficult as things get:
 
+    require 'kiva'
+    
+    newest = Kiva::Loan.load_newest
+    newest.each{ |loan|
+      puts "#{loan.name} loaned $#{loan.funded_amount} for
+			#{loan.activity} in #{loan.location["country"]}"
+    }
 
-== Mailing List
+Running the above script yields something similar to the following:
+
+    $ ruby -rubygems examples/newest.rb 
+
+    Angela Okosun loaned $225 for Cement in Nigeria
+    Vitaliy Konovalenko loaned $1650 for Retail in Ukraine
+		(...)
+    Thi Thoa Do's Group loaned $300 for Food Production/Sales in Viet Nam
+    Thi Hoa Nguyen loaned $900 for General Store in Viet Nam
+
+
+== Prerequisites
+
+Kiva doesn't require an account or an API key in order to use their API,
+so there are no prerequisites to using it. This library does depend on
+SimpleHTTP[http://simplehttp.rubyforge.org/] and
+json[http://json.rubyforge.org/] to handle the web api. These should be
+installed automatically if you used +gem+ to install the library, else,
+you'll need to install them manually.
 
-In case you discover bugs, spelling errors, offer suggestions for
-improvements or would like to help out with the project, you can contact
-me directly (tim@kuriositaet.de).
-	
 
+== Basic Usage
 
+This library consists of number of classes modelling the data
+objects which the web api returns. Each class is similar, consisting of
+class methods used to call webapi functions and attributes which provide
+access to the (unpacked) json data the webapi returns.
 
+These classes are (in no particular order) :
 
+* <code>Kiva::Loan</code>
+* <code>Kiva::Lender</code>
+* <code>Kiva::LendingAction</code>
+* <code>Kiva::Partner</code>
+* <code>Kiva::JournalEntry</code>
+* <code>Kiva::Comment</code>
+* <code>Kiva::Release</code>
 
+Each of these classes has attributes containing the data returned from
+the web api. For example, a +Comment+ has the attributes:
 
+* <code>author</code>
+* <code>body</code>
+* <code>date</code>
+* <code>id</code>
+* <code>whereabouts</code>
 
+Each class has one or more class methods, corresponding to web api
+calls, which may be used to create and load instances of the class. For
+example, +Loan+ has the following list of class methods:
 
+* +load+ : loans/&lt;ids&gt;[http://developers.wiki.kiva.org/KivaAPI#loans/ltidsgt]
+* +load_for_lender+ : loans/&lt;id&gt;/lenders[http://developers.wiki.kiva.org/KivaAPI#loans/ltidgt/lenders]
+* +load_newest+ : loans/newest[http://developers.wiki.kiva.org/KivaAPI#loans/newest]
+* +search+ : loans/search[http://developers.wiki.kiva.org/KivaAPI#loans/search]
 
 
 
+== Installing
+
+You should be able to `gem install kiva`. Alternatively, download a distribution
+at rubyforge: http://rubyforge.org/frs/?group_id=8034 
+
+Finally you can grab the sources from the rubyforge or github  repositories:
 
+git clone git://rubyforge.org/kiva.git
 
+or
 
+http://github.com/a2800276/kiva/tree/master#
 
-=
+
+
+== Mailing List
+
+In case you discover bugs, spelling errors, offer suggestions for
+improvements or would like to help out with the project, you can contact
+me directly (tim@kuriositaet.de).
+	

data/Rakefile

@@ -9,7 +9,7 @@ require "rubygems"
 
 SHORTNAME	='kiva'	# this should be the rubyforge project name
 DESC		= 'wrapper to kiva api'
-PKG_VERSION 	='0.0.1'
+PKG_VERSION 	='0.0.2'
 LONG_DESC	= <<END_DESC
 	Wrapper to the kiva web api. The API is described in
 	more detail here:

data/TODO

@@ -4,7 +4,5 @@ Just about everything. Off the top of my head:
 * multiple search parameters
 
 * nicer handling of paging.
-* nicer documentation
 
-* gem stuff ?
 

data/examples/newest.rb

@@ -0,0 +1,8 @@
+require 'kiva'
+
+require 'kiva'
+
+newest = Kiva::Loan.load_newest
+newest.each{ |loan|
+   puts "#{loan.name} loaned $#{loan.funded_amount} for #{loan.activity} in #{loan.location["country"]}"
+}

data/lib/kiva.rb

@@ -1,12 +1,22 @@
 require 'json'
 require 'simplehttp'
 
+# The Kiva module is a namespace to contain all the classes and contains
+# some utility functions to handle json and http.
 
 module Kiva
 
   #
-  # central location to perform webservice query
-  # hook into here for error handling, etc.
+  # This is central location where the webservice query
+  # is performed. You probably won't need to change this, but in case you
+  # you need special error handling or some other behaviour, you can
+  # modify everything in one place HERE.
+  # 
+  # For examples on how to do this, have a look at the files: `test/generate_fixtures.rb`
+  # and `test/test_kiva.rb`.
+  #
+  # ===Error Handling
+  #
   # currently the normal HttpExceptions are just passed
   # on, which should be ok for starters.
   #
@@ -88,7 +98,18 @@ module Kiva
     res
   end
 
-
+  # Represents a Loan (whoda guessed.) The accessible parameters are all
+  # all there is to this. Depending on how a particular instance of loan
+  # was loaded, not all of the attributes need have a value, so remember
+  # to check for +nil+.
+  #
+  # Use one of the class functions:
+  # * +load+
+  # * +load_for_lender+
+  # * +load_newest+
+  # * +search+
+  #
+  # to load loans from Kiva.
   class Loan
     attr_accessor :id
     attr_accessor :status
@@ -122,14 +143,15 @@ module Kiva
       #
       # Returns details for one or more loans. 
       #
-      # PARAMS
-      #   `ids` : an instance of `Loan` or a loan id or an array `Loan`s/loan IDs
+      # ====Paramaters
+      # +ids+ : an instance of +Loan+ or a loan id or an array +Loan+'s
+      # or loan id's
       #
-      # RETURNS
-      #   an array of `Loan` instances
+      # ====Returns
+      # an array of +Loan+ instances
       #
-      # CORRESPONDS
-      #  http://developers.wiki.kiva.org/KivaAPI#loans/ltidsgt 
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#loans/ltidsgt
       #
       def load ids
         case ids
@@ -153,14 +175,14 @@ module Kiva
       #
       # Search for loans matching specific criteria. 
       #
-      # PARAMS
-      #   `filter` : an instance of `Filter` describing the search parameter 
+      # ====Parameters
+      # +filter+ : an instance of +Filter+ describing the search parameter 
       #
-      # RETURNS
-      #   an array of `Loan` instances
+      # ====Returns
+      # an array of +Loan+ instances
       #
-      # CORRESPONDS
-      #  http://developers.wiki.kiva.org/KivaAPI#loans/search 
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#loans/search 
       #
       def search filter, page=nil
         url = SEARCH
@@ -178,14 +200,14 @@ module Kiva
       #
       # Returns the most recent fundraising loans. 
       #
-      # PARAMS
-      #   `page` : the page position
+      # ====Parameters
+      # +page+ : the page position
       #
-      # RETURNS
-      #   an array of `Loan` instances
+      # ====Returns
+      # an array of +Loan+ instances
       #
-      # CORRESPONDS
-      #   http://developers.wiki.kiva.org/KivaAPI#loans/newest
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#loans/newest
       #
       def load_newest page=nil
         url = LOAD_NEWEST
@@ -199,18 +221,18 @@ module Kiva
      
 
       # 
-      # Returns loans sponsored by Lender
+      # Returns loans sponsored by a specified lender
       # 
-      # PARAMS
-      # `id` : id of lender or instance of `Lender`
-      # `sort_by`: one of :newest, :oldest
-      # `page` : page position
+      # ====Parameters
+      # * +id+ : id of lender or instance of +Lender+
+      # * +sort_by+: one of <code>:newest, :oldest</code>
+      # * +page+ : page position
       #
-      # RETURNS
-      #   array of `Loan`s
+      # ====Returns
+      # array of +Loan+'s
       #
-      # CORRESPONDS
-      #   http://developers.wiki.kiva.org/KivaAPI#lenders/ltlenderidgt/loans
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#lenders/ltlenderidgt/loans
       #
 
       def load_for_lender id, sort_by=nil, page=nil
@@ -230,6 +252,17 @@ module Kiva
     end
 
   end
+  
+  # Represents a Lender (whoda guessed.) The accessible parameters are all
+  # all there is to this. Depending on how a particular instance of loan
+  # was loaded, not all of the attributes need have a value, so remember
+  # to check for +nil+.
+  #
+  # Use one of the class functions:
+  # * +load+
+  # * +load_for_loan+
+  #
+  # to load lender information from Kiva.
 
   class Lender
     # url = "http://api.kivaws.org/v1/lenders/%s.json"
@@ -257,14 +290,14 @@ module Kiva
       #
       # List public lenders of a loan.
       #
-      # PARAMS
-      # `loan` : a loan id or an instance of `Loan` 
+      # ====Parameters
+      # +loan+ : a loan id or an instance of +Loan+ 
       #
-      # RETURNS
-      #   an array of `Lender` instances.
+      # ====Returns
+      # an array of +Lender+ instances.
       #
-      # CORRESPONDS TO
-      #   http://developers.wiki.kiva.org/KivaAPI#loans/ltidgt/lenders
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#loans/ltidgt/lenders
       #
       def load_for_loan loan, page = nil
         loan = loan.id if loan.is_a?(Loan)
@@ -283,14 +316,14 @@ module Kiva
       #
       # Load details for one or more Lenders.
       #
-      # PARAMS
-      # `ids` : a lender id or and array of id's
+      # ====Parameters
+      # +ids+ : a lender id or and array of id's
       #
-      # RETURNS
-      #   an array of `Lender` instances.
+      # ====Returns
+      # an array of +Lender+ instances.
       #
-      # CORRESPONDS TO
-      #   http://developers.wiki.kiva.org/KivaAPI#lenders/ltlenderidsgt
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#lenders/ltlenderidsgt
       #
       def load ids
         ids  = ids.join(",") if ids.is_a?(Array)
@@ -305,6 +338,10 @@ module Kiva
 
   end
 
+  # +LendingAction+ are basically a showcase of recent Kiva activity.
+  # Use the class method +load+ to loan the last 100 lenders and the
+  # loan they sponsored.
+
   class LendingAction
     attr_accessor :id
     attr_accessor :date
@@ -318,11 +355,11 @@ module Kiva
       #
       # Returns the last 100 public actions from Kiva.
       #
-      # RETURNS
-      #   an array of `LendingAction` instances
+      # ====Returns
+      # an array of +LendingAction+ instances
       #
-      # CORRESPONDS
-      #   http://developers.wiki.kiva.org/KivaAPI#lendingactions/recent
+      # ====corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#lendingactions/recent
       #
       def load 
         raw = Kiva.execute(LOAD_RECENT)
@@ -333,7 +370,11 @@ module Kiva
       end
     end
   end
-
+  
+  # Journal entries are attached to loans. Using the class method +load+
+  # you can retrieve all entries attached to a particular loan.
+  #
+  
   class JournalEntry
     attr_accessor :id
     attr_accessor :body
@@ -345,6 +386,22 @@ module Kiva
     attr_accessor :image
     attr_accessor :recommendation_count
 
+    #
+    # Retrieve an array of +Comment+ instances
+    # associated with this entry. N.B. this leads to
+    # a further network call.
+    def comments
+      unless @comments 
+        return nil if id.is_nil?
+        if @comment_count != 0
+          @comments = Comment.load(this)
+        else
+          @commetns = []
+        end
+      end
+      @comments
+    end
+
     class << self
       KEY  = "journal__entries"
       LOAD = "http://api.kivaws.org/v1/loans/%s/journal_entries.json?"
@@ -352,14 +409,14 @@ module Kiva
       #
       # Load journal entries for a loan. 
       #
-      # PARAMS
-      # `id` : a loan id or an instance of `Loan`
+      # ====Parameters
+      # +id+ : a loan id or an instance of +Loan+
       #
-      # RETURNS
-      #   an array of `JournalEntry` instances.  
+      # ====Returns
+      # an array of +JournalEntry+ instances.  
       #
-      # CORRESPONDS TO
-      #   http://developers.wiki.kiva.org/KivaAPI#loans/ltidgt/journalentries
+      # ====Corresponds 
+      # http://developers.wiki.kiva.org/KivaAPI#loans/ltidgt/journalentries
       #
       def load id, page = nil, include_bulk = nil
         id = id.id if id.is_a? Loan
@@ -375,7 +432,8 @@ module Kiva
       end 
     end
   end
-
+  
+  # User comment made in response to a JournalEntry.
   class Comment
     # http://api.kivaws.org/v1/journal_entries/<id>/comments.json
     attr_accessor :body
@@ -391,12 +449,14 @@ module Kiva
       #
       # Loads an array of comments for a JournalEntry.
       #
-      # `id`  : the numerical id of a Journal Entry or an instance of
-      #        the class `JournalEntry`
-      # `page`: which page of comments to load, default is the first.
+      # ====Parameters
+      # * +id+  : the numerical id of a Journal Entry or an instance of the class +JournalEntry+
+      # * +page+: which page of comments to load, default is the first.
       #
-      # Corresponds to the API:
+      # ====Returns
+      # array of +Comments+
       #
+      # ====Corresponds
       # http://developers.wiki.kiva.org/KivaAPI#journalentries/ltidgt/comments
       #
       def load id, page=nil
@@ -412,6 +472,7 @@ module Kiva
     end
   end
 
+  # Kiva field Partner
   class Partner
     attr_accessor :start_date
     attr_accessor :rating
@@ -432,14 +493,14 @@ module Kiva
       #
       # Load an alphabetically sorted list of partners.
       #
-      # PARAMS
-      #   `page`: page position 
+      # ====Parameters
+      # +page+: page position 
       #
-      # RETURNS
-      #   an array of `Partner` instances
+      # ====Returns
+      # an array of +Partner+ instances
       #
-      # CORRESPONDS
-      #   http://developers.wiki.kiva.org/KivaAPI#partners 
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#partners 
       #
 
       def load page=nil
@@ -452,6 +513,8 @@ module Kiva
     end
   end
 
+  # Release information concerning the webapi. This is not the
+  # release number of the ruby library!
   class Release
 
     attr_accessor :date
@@ -461,12 +524,11 @@ module Kiva
       #
       # Returns release information 
       #
+      # ====Returns
+      #   an array of +Partner+ instances
       #
-      # RETURNS
-      #   an array of `Partner` instances
-      #
-      # CORRESPONDS
-      #   http://developers.wiki.kiva.org/KivaAPI#releases/api/current 
+      # ====Corresponds
+      # http://developers.wiki.kiva.org/KivaAPI#releases/api/current 
       #
      
       def load
@@ -477,6 +539,7 @@ module Kiva
     end
   end
 
+  # Templates which may be used to construct html image tags.
   class Templates
     attr_accessor :id
     attr_accessor :pattern
@@ -489,100 +552,120 @@ module Kiva
     end
   end
 
+  # Filter to be used in order to describe the intended search results
+  # of <code>Loan.search</code>
   class Filter
     attr_accessor :params
+
+    # Create a new instance of filter with no attributes.
     def initialize
       @params = {}
     end
     
-    #sort_by
+    # sort_by
     def popularity
       @params["sort_by"]="popularity"
       return self
     end
+    # sort_by
     def loan_amount
       @params["sort_by"]="loan_amount"
       return self
     end
+    # sort_by
     def oldest
       @params["sort_by"]="oldest"
       return self
     end
+    # sort_by
     def expiration
       @params["sort_by"]="expiration"
       return self
     end
+    # sort_by
     def newest
       @params["sort_by"]="newest"
       return self
     end
+    # sort_by
     def amount_remaining
       @params["sort_by"]="amount_remaining"
       return self
     end
+    # sort_by
     def repayment_term
       @params["sort_by"]="repayment_term"
       return self
     end
 
-    # GENDER
+    # restrict to male loan recipients
     def male
       @params["gender"]="male"
       return self
     end
+    # restrict to female loan recipients
     def female
       @params["gender"]="female"
       return self
     end
 
-    # STATUS
+    # restrict status
     def fundraising
       @params["status"]="fundraising"
       return self
     end
+    # restrict status
     def funded
       @params["status"]="funded"
       return self
     end
+    # restrict status
     def in_repayment
       @params["status"]="in_repayment"
       return self
     end
+    # restrict status
     def paid
       @params["status"]="paid"
       return self
     end
+    # restrict status
     def defaulted
       @params["status"]="defaulted"
       return self
     end
      
-    #REGION
-
+    #restrict region
     def north_america
       @params["region"]="na"
       return self
     end
+    #restrict region
     def central_america
       @params["region"]="ca"
       return self
     end
+    #restrict region
     def south_america
       @params["region"]="sa"
       return self
     end
+    #restrict region
     def africa
       @params["region"]="af"
       return self
     end
+    #restrict region
     def asia
       @params["region"]="as"
       return self
     end
+    #restrict region
     def middle_east
       @params["region"]="me"
       return self
     end
+    #restrict region
     def eastern_europe
       @params["region"]="ee"
       return self

data/test/generate_fixtures.rb

@@ -4,6 +4,7 @@ require 'pp'
 require File.dirname(__FILE__) + '/../lib/kiva'
 
 module Kiva
+	# Modified `execute` method to generate fixtures!
   def Kiva.execute url, query=nil
     result = SimpleHttp.get(url, query)
     key = [url, query]

data/test/test_kiva.rb

@@ -3,11 +3,12 @@ require 'pp'
 require File.dirname(__FILE__) + '/../lib/kiva'
 
 
-# Patch up execute method to use dummies and not connect to real web api.
 module Kiva
   fixtures = File.open(File.dirname(__FILE__)+"/fixtures.rbf").readlines.join
   $fixtures = eval(fixtures)
 
+	# Modified `execute` method for TESTING!
+  # Patch up execute method to use dummies and not connect to real web api.
   def Kiva.execute url, query=nil
     key = [url, query]
     $fixtures[key]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: kiva
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: []
 
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-20 00:00:00 +01:00
+date: 2009-03-23 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,6 +40,7 @@ extra_rdoc_files: []
 
 files: 
 - lib/kiva.rb
+- examples/newest.rb
 - AUTHORS
 - CHANGELOG
 - COPYING