partigirb 0.2.7

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Alvaro Bautista & Fernando Blat
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,110 @@
+# partigirb
+
+A Ruby wrapper for the Partigi API, adapted from [Grackle](http://github.com/hayesdavis/grackle/tree/master) by Hayes Davis.
+
+## What is Partigi?
+
+[Partigi](http://www.partigi.com) is a service that helps you choose your next cultural items, share short reviews and keep track of what you have consumed and own.
+
+The Partigi API is an almost-REST based Atom API where we offer you almost all data and functionality that you have in the website.
+
+There is also a [complete documentation of the API](http://partigi.pbworks.com/).
+
+## Install
+
+    gem install partigirb -s http://gemcutter.org
+
+## Usage
+
+### Creating a client
+
+#### Without Authentication
+
+    client = Partigirb::Client.new
+
+#### With Authentication
+
+    client = Partigirb::Client.new(:auth => {:login => 'SOMEUSERLOGIN', :api_secret => 'SECRETGENERATEDFORTHEUSER'})
+  
+#### With specific API version
+  
+    client = Partigirb::Client.new(:api_version => 2)
+  
+### Request methods
+
+A request to Partigi servers is done by translating Partigi URL paths into a set of chained method calls, just changing slashes by dots. Each call is used to build the request URL until a format call is found which causes the request to be sent. In order to specify the HTTP method use:
+
+- `?` for HTTP GET
+- `!` for HTTP POST (in this case you will need to use a client with authentication)
+
+A request is not performed until either you add the above signs to your last method call or you use a format method call.
+
+**Note:** Any method call that is not part of a valid API request path will be chained to the  request that Partigirb sends to the server, so that when the client finds a format call (method call ending with ? or !) a wrong request will be sent and a PartigiError will be raised. For example:
+
+      client.wrong.items.index?
+      
+or
+      
+      client.wrong
+      client.items.index?
+
+In the second case we do the wrong call and the right one in separated sentences, however the wrong call is chained anyway (in that case the client method `clear` may be used to flush the chain).
+
+### Formats
+
+The response format is specified by a method call with the format name (atom, json or xml). Notice that the only format fully implemented on Partigi API at the moment is atom, which is the default used by the wrapper.
+
+### Example requests
+
+The simplest way of executing a GET request is to use the `?` notation, using the default format.
+
+    client.users.show? :id => 'johnwayne'     # http://www.partigi.com/api/v1/users/show.atom?id=johnwayne
+  
+Also you can force the format:
+  
+    client.users.show.json? :id => 'johnwayne' # http://www.partigi.com/api/v1/users/show.json?id=johnwayne
+
+For POST requests just change `?` by `!`:
+  
+    client.reviews.update! :id => 123, :status => 1 # POST to http://www.partigi.com/api/v1/reviews/update.atom
+  
+
+### Parameter handling
+
+- All parameters are URL encoded as necessary.
+- If you use a File object as a parameter it will be POSTed to Partigi in a multipart request.
+- If you use a Time object as a parameter, .httpdate will be called on it and that value will be used
+
+### Return values
+
+The returned values are always OpenStruct objects (wrapped in Partigirb::PartigiStruct) containing the response values as attributes. 
+
+If the response contains several entries the client returns an Array of OpenStruct objects.
+
+When using Atom format Partigi returns some XML elements using namespaces. In those cases the elements are mapped to attributes by convention, for example: `namespaceName:attribute` becomes `namespaceName_attribute`
+
+#### Special cases
+
+There are two special cases to be aware of in regard to PartigiStruct:
+
+- Every attribute which name is equal to any of the Ruby Object methods (e.g `type`) will be mapped to a method on the struct starting with an underscore (e.g `_type`).
+
+- XML elements that appear repeated with different type values will turn into a unique struct with one method per type. For instance:
+
+        <content type="text">Some text</content>
+        <content type="html"><p>Some html</p></content>
+  
+  Will be accessed by `result.content.text` and `result.content.html`, both returning a ruby string.
+
+### Error handling
+
+In case Partigi returns an error response, this is turned into a PartigiError object which message attribute is set to the error string returned in the XML response.
+
+## Requirements
+
+- json
+- mime-types
+
+## Copyright
+
+Copyright (c) 2009 Alvaro Bautista & Fernando Blat, released under MIT license

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "partigirb"
+    gem.summary = %q{A Ruby wrapper for the Partigi API}
+    gem.email = ["alvarobp@gmail.com", "ferblape@gmail.com"]
+    gem.homepage = "http://github.com/partigi/partigirb"
+    gem.authors = ["Alvaro Bautista", "Fernando Blat"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "partigirb #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.7

data/examples/last_reviews_summary.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/../lib/partigirb'
+
+if ARGV.empty?
+  puts "\nUsage: ruby #{__FILE__} user_id_or_login\n\n"
+  exit
+end
+
+user_id = ARGV.first
+
+def show_reviews(client, reviews, title)
+  puts
+  puts title 
+  puts "-" * title.size
+  puts
+  
+  reviews.each do |review|
+      film = client.items.show? :id => review.ptItem_id, :type => 'film'
+      puts "- #{film.title}"
+      puts "  Comment: #{review.content.text}"
+      puts
+  end
+  puts
+end
+
+client = Partigirb::Client.new
+
+reviews = client.reviews.index? :user_id => user_id, :per_page => 5, :status => 0, :order => 'desc'
+show_reviews(client, reviews, "Latest 5 films you want to watch")
+
+reviews = client.reviews.index? :user_id => user_id, :per_page => 5, :status => 1, :order => 'desc'
+show_reviews(client, reviews, "Latest 5 films you have seen")
+
+reviews = client.reviews.index? :user_id => user_id, :per_page => 5, :status => 2, :order => 'desc'
+show_reviews(client, reviews, "Latest 5 films you own")

data/examples/who_ignores_me.rb

@@ -0,0 +1,35 @@
+require File.dirname(__FILE__) + '/../lib/partigirb'
+
+if ARGV.empty?
+  puts "\nUsage: #{__FILE__} user_id_or_login\n\n"
+  exit
+end
+
+user_id = ARGV.first
+
+client = Partigirb::Client.new
+
+traitors = []
+
+page = 1
+friends = []
+
+# Get logins of people user is following
+begin
+  friends = client.friendships.index? :user_id => user_id, :type => 'follows', :page => page
+  
+  friends.each do |friend|
+    relationship = client.friendships.show? :source_id => user_id, :target_id => friend.ptUser_id
+    traitors << friend.ptUser_login if relationship.ptRelationship_source.ptRelationship_followed_by == 'false'
+  end
+  
+  page += 1
+end while !friends.empty?
+
+if traitors.empty?
+  "Everything is fine. Everyone you follow is following you."
+else
+  puts "Those are the ones that don't want to know about you:"
+  puts
+  traitors.each {|t| puts "  - #{t}"}
+end

data/lib/partigirb/client.rb

@@ -0,0 +1,190 @@
+module Partigirb
+  
+  class PartigiStruct < OpenStruct
+    attr_accessor :id 
+  end
+  
+  # Raised by methods which call the API if a non-200 response status is received 
+  class PartigiError < StandardError
+  end
+  
+  class Client
+    class Request #:nodoc:
+      attr_accessor :client, :path, :method, :api_version
+      
+      def initialize(client,api_version=Partigirb::CURRENT_API_VERSION)
+        self.client = client
+        self.api_version = api_version
+        self.method = :get
+        self.path = ''
+      end
+      
+      def <<(path)
+        self.path << path
+      end
+      
+      def path?
+        path.length > 0
+      end
+    
+      def url
+        "#{scheme}://#{host}/api/v#{self.api_version}#{path}"
+      end
+         
+      def host
+        client.api_host
+      end
+    
+      def scheme
+        'http'
+      end
+    end
+    
+    VALID_METHODS = [:get,:post,:put,:delete]
+    VALID_FORMATS = [:atom,:xml,:json]
+
+    PARTIGI_API_HOST = "www.partigi.com"
+    TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%SZ'
+    
+    attr_accessor :default_format, :headers, :api_version, :transport, :request, :api_host, :auth, :handlers
+    
+    def initialize(options={})
+      self.transport = Transport.new
+      self.api_host = PARTIGI_API_HOST.clone
+      self.api_version = options[:api_version] || Partigirb::CURRENT_API_VERSION
+      self.headers = {"User-Agent"=>"Partigirb/#{Partigirb::VERSION}"}.merge!(options[:headers]||{})
+      self.default_format = options[:default_format] || :atom
+      self.handlers = {
+        :json => Partigirb::Handlers::JSONHandler.new,
+        :xml => Partigirb::Handlers::XMLHandler.new,
+        :atom => Partigirb::Handlers::AtomHandler.new,
+        :unknown => Partigirb::Handlers::StringHandler.new
+      }
+      self.handlers.merge!(options[:handlers]||{})
+      
+      # Authentication param should be a hash with keys:
+      # login (required)
+      # api_secret (required)
+      # nonce (optional, would be automatically generated if missing)
+      # timestamp (optional, current timestamp will be automatically used if missing)
+      self.auth = options[:auth]
+    end
+    
+    def method_missing(name,*args)
+      # If method is a format name, execute using that format
+      if format_invocation?(name)
+        return call_with_format(name,*args)
+      end
+      # If method ends in ! or ? use that to determine post or get
+      if name.to_s =~ /^(.*)(!|\?)$/
+        name = $1.to_sym
+        # ! is a post, ? is a get
+        self.request.method = ($2 == '!' ? :post : :get)          
+        if format_invocation?(name)
+          return call_with_format(name,*args)
+        else
+          self.request << "/#{$1}"
+          return call_with_format(self.default_format,*args)
+        end
+      end
+      # Else add to the request path
+      self.request << "/#{name}"
+      self
+    end
+    
+    # Clears any pending request built up by chained methods but not executed
+    def clear
+      self.request = nil
+    end
+    
+    def request
+      @request ||= Request.new(self,api_version)
+    end
+    
+    protected
+    
+    def call_with_format(format,params={})
+      request << ".#{format}"
+      res = send_request(params)
+      process_response(format,res)
+    ensure
+      clear
+    end
+    
+    def send_request(params)
+      begin
+        set_authentication_headers
+        
+        transport.request(
+          request.method, request.url, :headers=>headers, :params=>params
+        )
+      rescue => e
+        puts e
+      end        
+    end
+    
+    def process_response(format, res)
+      fmt_handler = handler(format)
+      
+      begin
+        if res.code.to_i != 200
+          handle_error_response(res, Partigirb::Handlers::XMLHandler.new)
+        else
+          fmt_handler.decode_response(res.body)
+        end
+      end
+    end
+    
+    # TODO: Test for errors
+    def handle_error_response(res, handler)
+      # Response for errors is an XML document containing an error tag as a root,
+      # having a text node with error name. As XMLHandler starts building the Struct
+      # on root node the returned value from the handler will always be the error name text.
+      raise PartigiError.new(handler.decode_response(res.body))
+    end
+    
+    def format_invocation?(name)
+      self.request.path? && VALID_FORMATS.include?(name)
+    end
+    
+    def handler(format)
+      handlers[format] || handlers[:unknown]
+    end
+    
+    # Adds the proper WSSE headers if there are the right authentication parameters
+    def set_authentication_headers
+      unless self.auth.nil? || self.auth === Hash || self.auth.empty?
+        auths = self.auth.stringify_keys
+      
+        if auths.has_key?('login') &&  auths.has_key?('api_secret')
+          if !auths['timestamp'].nil?
+            timestamp = case auths['timestamp']
+            when Time
+              auths['timestamp'].strftime(TIMESTAMP_FORMAT)
+            when String
+              auths['timestamp']
+            end
+          else
+            timestamp = Time.now.strftime(TIMESTAMP_FORMAT) if timestamp.nil?
+          end
+        
+          nonce = auths['nonce'] || generate_nonce
+          password_digest = generate_password_digest(nonce, timestamp, auths['login'], auths['api_secret'])
+          headers.merge!({
+            'Authorization' => "WSSE realm=\"#{PARTIGI_API_HOST}\", profile=\"UsernameToken\"",
+            'X-WSSE' => "UsernameToken Username=\"#{auths['login']}\", PasswordDigest=\"#{password_digest}\", Nonce=\"#{nonce}\", Created=\"#{timestamp}\""
+          })
+        end
+      end
+    end
+    
+    def generate_nonce
+      o =  [('a'..'z'),('A'..'Z')].map{|i| i.to_a}.flatten
+      Digest::MD5.hexdigest((0..10).map{o[rand(o.length)]}.join)
+    end
+    
+    def generate_password_digest(nonce, timestamp, login, secret)
+      Base64.encode64(Digest::SHA1.hexdigest("#{nonce}#{timestamp}#{login}#{secret}")).chomp
+    end
+  end
+end

data/lib/partigirb/core_ext.rb

@@ -0,0 +1,78 @@
+# Ruby Hash extensions from ActiveSupport
+
+class Hash
+  # Return a new hash with all keys converted to strings.
+  def stringify_keys
+    inject({}) do |options, (key, value)|
+      options[key.to_s] = value
+      options
+    end
+  end
+
+  # Destructively convert all keys to strings.
+  def stringify_keys!
+    keys.each do |key|
+      self[key.to_s] = delete(key)
+    end
+    self
+  end
+end
+
+class Object
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} are blank.
+  #
+  # This simplifies
+  #
+  #   if !address.nil? && !address.empty?
+  #
+  # to
+  #
+  #   if !address.blank?
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+    
+  # An object is present if it's not blank.
+  def present?
+    !blank?
+  end
+end
+
+class NilClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class FalseClass #:nodoc:
+  def blank?
+    true
+  end
+end
+
+class TrueClass #:nodoc:
+  def blank?
+    false
+  end
+end
+
+class Array #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class Hash #:nodoc:
+  alias_method :blank?, :empty?
+end
+
+class String #:nodoc:
+  def blank?
+    self !~ /\S/
+  end
+end
+
+class Numeric #:nodoc:
+  def blank?
+    false
+  end
+end

data/lib/partigirb/handlers/atom_handler.rb

@@ -0,0 +1,24 @@
+module Partigirb
+  module Handlers
+    class AtomHandler < XMLHandler
+      def decode_response(body)
+        return REXML::Document.new if body.blank?
+        xml = REXML::Document.new(body.gsub(/>\s+</,'><'))
+        
+        if xml.root.name == 'feed'
+          entries = xml.root.get_elements('entry')
+          
+          # Depending on whether we have one or more entries we return an PartigiStruct or an array of PartigiStruct
+          if entries.size == 1
+            load_recursive(entries.first)
+          else
+            entries.map{|e| load_recursive(e)}
+          end
+        else
+          # We just parse as a common XML
+          load_recursive(xml.root)
+        end
+      end
+    end
+  end
+end

data/lib/partigirb/handlers/json_handler.rb

@@ -0,0 +1,10 @@
+module Partigirb
+  module Handlers
+    class JSONHandler
+      def decode_response( body )
+        # TODO: Implement when API JSON format is ready
+        body
+      end
+    end
+  end
+end

data/lib/partigirb/handlers/string_handler.rb

@@ -0,0 +1,9 @@
+module Partigirb
+  module Handlers
+    class StringHandler
+      def decode_response( body )
+        body
+      end
+    end
+  end
+end

data/lib/partigirb/handlers/xml_handler.rb

@@ -0,0 +1,111 @@
+module Partigirb
+  module Handlers
+    class XMLHandler
+      def decode_response(body)
+        return REXML::Document.new if body.blank?
+        xml = REXML::Document.new(body.gsub(/>\s+</,'><'))
+        load_recursive(xml.root)
+      end
+      
+      private
+        def load_recursive(node)
+          if array_node?(node)
+            node.elements.map {|e| load_recursive(e)}
+          elsif cdata_node?(node)
+            node.cdatas.first.to_s
+          elsif raw_node?(node)
+            node.text
+          elsif (node.elements.size > 0 || node.attributes.size > 0) && !ignore_attributes?(node)
+            build_struct(node)          
+          else
+            value = node.text
+            fixnum?(value) ? value.to_i : value
+          end
+        end
+      
+        def build_struct(node)
+          ts = PartigiStruct.new
+          
+          node.attributes.each do |a,v|
+            # In case the Struct object already responds to a method 
+            # with same name like type case
+            if ts.respond_to?(a) 
+              ts.send("_#{a}=",v)
+            else
+              ts.send("#{a}=", v) unless a =~ /^xmlns/
+            end
+          end
+          
+          links = node.elements.delete_all('link')
+          
+          node.elements.each do |e|
+            property = ""
+            
+            if ns = node_namespace(e)
+              property << "#{ns}_" unless ns == 'xmlns'
+            end
+            
+            property << e.name
+            
+            # Multiple type is the case of content elements, which appear twice, with type="text" and type="html"
+            if multiple_type?(e)
+              if ts.respond_to?(property)
+                ts.send(property).send("#{e.attributes['type']}=", load_recursive(e))
+              else
+                ts.send("#{property}=", PartigiStruct.new)
+                ts.send(property).send("#{e.attributes['type']}=", load_recursive(e))
+              end
+            else
+              ts.send("#{property}=", load_recursive(e))
+            end
+          end
+          
+          unless links.empty?
+            ts.send("links=", links.map{|l| build_struct(l)})
+          end
+          
+          ts
+        end
+        
+        # Most of the time Twitter specifies nodes that contain an array of 
+        # sub-nodes with a type="array" attribute. There are some nodes that 
+        # they dont' do that for, though, including the <ids> node returned 
+        # by the social graph methods. This method tries to work in both situations.
+        def array_node?(node)
+          node.attributes['type'] == 'collection'
+        end
+        
+        # Nodes which content must not be processed
+        def cdata_node?(node)
+          ['xhtml', 'html'].include?(node.attributes['type']) && !node.cdatas.empty?
+        end
+        
+        def raw_node?(node)
+          node.name == 'content' && node.attributes['type'] == 'text'
+        end
+        
+        # Nodes corresponding to an element repeated with different types
+        def multiple_type?(node)
+          node.name == 'content' && !node.attributes['type'].nil?
+        end
+        
+        def fixnum?(value)
+          value =~ /^\d+$/
+        end
+        
+        def node_namespace(node)
+          node.namespace.blank? ? nil : node.namespaces.invert[node.namespace]
+        end
+        
+        def ignore_attributes?(node)
+          element_name = node.name
+          ns = node_namespace(node)
+          element_name.insert(0, "#{ns}:") if ns
+          
+          IGNORE_ATTRIBUTES_FOR.include?(element_name)
+        end
+        
+        IGNORE_ATTRIBUTES_FOR = ['ptItem:synopsis', 'ptItem:title']
+    end
+  end
+end