party_resource 0.0.1 → 0.0.2

data/README.md

@@ -0,0 +1,68 @@
+# party_resource
+
+Simple REST interface for ruby objects.
+
+party_resource is a framework for building ruby objects which interact with a REST api. Built on top of HTTParty.
+
+HTTParty is great for adding a couple of methods that fetch data from an HTTP api, but becomes cumbersome if you have
+lots of objects that all need to connect to several routes on the api. ActiveResource doesn't give you enough control.
+
+## Usage
+
+For detailed usage instructions, please see the [API Documentation](http://yardoc.org/docs/edendevelopment-party_resource).
+
+    PartyResource::Connector.add(:library, :base_uri => 'http://www.example.com/library')
+
+    class Author
+      include PartyResource
+
+      property :name
+      property :slug
+
+      connect :books, :get => '/authors/:slug/books', :as => Book, :on => :instance
+
+      def initialize(params = {})
+        populate_properties(params)
+      end
+    end
+
+    class Book
+      include PartyResource
+
+      property :title
+      property :author, :as => Author
+
+      connect :search, :get => '/search/:query', :with => :query
+
+      def initialize(params = {})
+        populate_properties(name)
+      end
+    end
+
+    book = Book.search('Lord of the Rings')
+
+    book.title #=> 'Lord of the Rings Trilogy'
+    book.author.class #=> Author
+    book.author.name #=> 'J. R. R. Tolkein'
+
+    author = book.author
+
+    author.books.map(&:title) #=> ['Lord of the Rings Trilogy', 'The Hobbit', 'The Silmarillion']
+
+## Issues
+
+Please use the [github issues tracker](http://github.com/edendevelopment/party_resource/issues).
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Eden Development (UK) LTD. See LICENSE for details.

data/lib/party_resource/connector/base.rb

@@ -13,7 +13,7 @@ module PartyResource
       def fetch(request)
         response = HTTParty.send(request.verb, request.path, request.http_data(options))
         unless (200..399).include? response.code
-          raise PartyResource::ConnectionError.build(response)
+          raise PartyResource::Exceptions::ConnectionError.build(response)
         end
         response
       end

data/lib/party_resource/connector.rb

@@ -1,27 +1,29 @@
 require 'party_resource/connector/base'
 module PartyResource
-  def self.Connector(name = nil)
-    Connector.lookup(name)
-  end
-
   module Connector
-    def self.lookup(name)
-      name ||= repository.default
-      connector = repository.connectors[name]
-      raise NoConnector.new(name) if connector.nil?
-      connector
-    end
+    class << self
+      # Find connector by name
+      # @return [Connector::Base] the requested connector
+      def lookup(name)
+        name ||= repository.default
+        connector = repository.connectors[name]
+        raise Exceptions::NoConnector.new(name) if connector.nil?
+        connector
+      end
 
-    def self.default=(name)
-      repository.default = name
-    end
+      # Add a new named connector
+      def add(name, options)
+        repository.new_connector(name, options)
+      end
 
-    def self.add(name, options)
-      repository.new_connector(name, options)
-    end
+      private
+      def default=(name)
+        repository.default = name
+      end
 
-    def self.repository
-      @repository ||= Repository.new
+      def repository
+        @repository ||= Repository.new
+      end
     end
 
     class Repository

data/lib/party_resource/exceptions.rb

@@ -1,57 +1,59 @@
 module PartyResource
 
-  Error = Class.new(StandardError)
+  module Exceptions
+    Error = Class.new(StandardError)
 
-  class MissingParameter < Error
-    def initialize(parameter, context)
-      @parameter = parameter
-      @context = context
-    end
+    class MissingParameter < Error
+      def initialize(parameter, context)
+        @parameter = parameter
+        @context = context
+      end
 
-    def to_s
-      "No value for #{@parameter} is available in #{@context}"
+      def to_s
+        "No value for #{@parameter} is available in #{@context}"
+      end
     end
-  end
 
-  class NoConnector < Error
-    def initialize(name)
-      @name = name
-    end
+    class NoConnector < Error
+      def initialize(name)
+        @name = name
+      end
 
-    def to_s
-      "Connector '#{@name}' has not been defined"
+      def to_s
+        "Connector '#{@name}' has not been defined"
+      end
     end
-  end
 
-  class ConnectionError < Error;
-    attr_reader :data
-
-    def self.build(data=nil)
-      klass = case data.code
-        when 404: ResourceNotFound
-        when 422: ResourceInvalid
-        when 400..499: ClientError
-        when 500..599: ServerError
-        else self
+    class ConnectionError < Error;
+      attr_reader :data
+
+      def self.build(data=nil)
+        klass = case data.code
+          when 404: ResourceNotFound
+          when 422: ResourceInvalid
+          when 400..499: ClientError
+          when 500..599: ServerError
+          else self
+        end
+        klass.new(data)
       end
-      klass.new(data)
-    end
 
-    def initialize(data=nil)
-      super()
-      @data = data
-    end
+      def initialize(data=nil)
+        super()
+        @data = data
+      end
 
-    def to_s
-      code = ''
-      code = "#{data.code} " rescue nil
-      "A #{code}connection error occured"
+      def to_s
+        code = ''
+        code = "#{data.code} " rescue nil
+        "A #{code}connection error occured"
+      end
     end
-  end
 
-  ClientError = Class.new(ConnectionError) # 4xx
-  ServerError = Class.new(ConnectionError) # 5xx
+    ClientError = Class.new(ConnectionError) # 4xx
+    ServerError = Class.new(ConnectionError) # 5xx
 
-  ResourceNotFound = Class.new(ClientError) # 404
-  ResourceInvalid = Class.new(ClientError) # 422
+    ResourceNotFound = Class.new(ClientError) # 404
+    ResourceInvalid = Class.new(ClientError) # 422
+  end
 end

data/lib/party_resource/party_resource.rb

@@ -6,6 +6,8 @@ module PartyResource
   module ClassMethods
     include MethodDefine
 
+    # Connect a method call to a restful uri
+    # @return [nil]
     def connect(name, options={})
       level = options.delete(:on)
       options = {:as => :self, :connector => @party_connector}.merge(options)
@@ -14,8 +16,35 @@ module PartyResource
       define_method_on(level, name) do |*args|
         route.call(self, *args)
       end
+      nil
     end
 
+    # Define a property
+    # @overload property(*names, options={})
+    #   @param [Symbol] names list of property names
+    #   @param [Hash] options the options to use to create the property
+    #   @option options :as (:self) How to build property
+    #
+    #     :raw - raw data
+    #
+    #     :self - self.new(data)
+    #
+    #     class - class.new(data)
+    #
+    #     Array(class, :method) - class.method(data)
+    #
+    #     lambda - lambda.call(data)
+    #   @option options :from (property name) where to find property value in incomming data hash
+    #
+    #     symbol - name
+    #
+    #     array - list of nested hash keys
+    #   @option options :to (from value) where to put property value in outgoing incomming data hash
+    #
+    #     symbol - name
+    #
+    #     array - list of nested hash keys
+    #   @return [nil]
     def property(*names)
       options = names.pop if names.last.is_a?(Hash)
       names.each do |name|
@@ -26,10 +55,14 @@ module PartyResource
         @property_list ||= []
         @property_list << Property.new(name, options)
       end
+      nil
     end
 
+    # Set the name of the connector to use for this class
+    # @return [nil]
     def party_connector(name)
       @party_connector = name
+      nil
     end
 
     private
@@ -49,19 +82,22 @@ module PartyResource
         begin
           out[var] = send(var)
         rescue
-          raise MissingParameter.new(var, self)
+          raise Exceptions::MissingParameter.new(var, self)
         end
         out
       end
     end
   end
 
+  # Converts the objects properties to a hash
+  # @return [Hash] a hash of all the properties
   def to_properties_hash
     self.class.send(:property_list).inject({}) do |hash, property|
       hash.merge(property.to_hash(self))
     end
   end
 
+  # Test if all properties are equal
   def properties_equal?(other)
     begin
       self.class.send(:property_list).all? {|property| self.send(property.name) == other.send(property.name) }

data/lib/party_resource/route.rb

@@ -15,7 +15,7 @@ module PartyResource
       raise ArgumentError, "wrong number of arguments (#{args.size} for #{expected_args.size})" unless expected_args.size == args.size
       begin
         builder.call(connector.fetch(request(context, args, options)), context, included(context))
-      rescue Error => e
+      rescue Exceptions::Error => e
         name = e.class.name.split(/::/).last
         return @options[:rescue][name] if @options[:rescue].has_key?(name)
         raise
@@ -23,7 +23,7 @@ module PartyResource
     end
 
     def connector
-      PartyResource::Connector(@options[:connector])
+      PartyResource::Connector.lookup(@options[:connector])
     end
 
     private

data/spec/integration/integration_spec.rb

@@ -71,22 +71,22 @@ describe TestClass do
     context 'error cases' do
       it 'raises ResourceNotFound' do
         stub_request(:delete, "http://fred:pass@myserver/path/delete").to_return(:status => 404)
-        lambda { TestClass.destroy }.should raise_error(PartyResource::ResourceNotFound)
+        lambda { TestClass.destroy }.should raise_error(PartyResource::Exceptions::ResourceNotFound)
       end
 
       it 'raises ResourceInvalid' do
         stub_request(:delete, "http://fred:pass@myserver/path/delete").to_return(:status => 422)
-        lambda { TestClass.destroy }.should raise_error(PartyResource::ResourceInvalid)
+        lambda { TestClass.destroy }.should raise_error(PartyResource::Exceptions::ResourceInvalid)
       end
 
       it 'raises ClientError' do
         stub_request(:delete, "http://fred:pass@myserver/path/delete").to_return(:status => 405)
-        lambda { TestClass.destroy }.should raise_error(PartyResource::ClientError)
+        lambda { TestClass.destroy }.should raise_error(PartyResource::Exceptions::ClientError)
       end
 
       it 'raises ServerError' do
         stub_request(:delete, "http://fred:pass@myserver/path/delete").to_return(:status => 501)
-        lambda { TestClass.destroy }.should raise_error(PartyResource::ServerError)
+        lambda { TestClass.destroy }.should raise_error(PartyResource::Exceptions::ServerError)
       end
 
       it 'rescues exceptions' do

data/spec/unit/connector/base_spec.rb

@@ -74,7 +74,7 @@ describe PartyResource::Connector::Base do
       it 'raises an exception' do
         return_data = mock(:data, :code => 404)
         HTTParty.should_receive(:get).and_return(return_data)
-        lambda{ subject.fetch(request) }.should raise_error(PartyResource::ConnectionError)
+        lambda{ subject.fetch(request) }.should raise_error(PartyResource::Exceptions::ConnectionError)
       end
     end
 

data/spec/unit/connector_spec.rb

@@ -8,7 +8,7 @@ describe PartyResource::Connector do
     let(:connectors) { { :test => test_connector, :other => default_connector } }
 
     before do
-      PartyResource::Connector.repository.stub(:connectors => connectors)
+      PartyResource::Connector.send(:repository).stub(:connectors => connectors)
     end
 
     it "returns the named connectors" do
@@ -16,21 +16,13 @@ describe PartyResource::Connector do
     end
 
     it "returns the default connector for nil name" do
-      PartyResource::Connector.repository.stub(:default => :other)
+      PartyResource::Connector.send(:repository).stub(:default => :other)
 
       PartyResource::Connector.lookup(nil).should == default_connector
     end
 
     it 'raises a NoConnector error it the connector could not be found' do
-      lambda { PartyResource::Connector.lookup(:missing_name) }.should raise_error(PartyResource::NoConnector)
-    end
-  end
-
-  describe '#default=' do
-    it 'sets the default connector name' do
-      name = mock(:name)
-      PartyResource::Connector.default = name
-      PartyResource::Connector.repository.default.should == name
+      lambda { PartyResource::Connector.lookup(:missing_name) }.should raise_error(PartyResource::Exceptions::NoConnector)
     end
   end
 
@@ -49,16 +41,16 @@ describe PartyResource::Connector do
     it 'creates a new connector' do
       PartyResource::Connector::Base.should_receive(:new).with(name, options).and_return(connector)
       PartyResource::Connector.add(name, options)
-      PartyResource::Connector(name).should == connector
+      PartyResource::Connector.lookup(name).should == connector
     end
 
     it 'sets the default if it is currently unset' do
       name2 = mock(:name2)
       PartyResource::Connector.add(name, options)
-      PartyResource::Connector.repository.default.should == name
+      PartyResource::Connector.send(:repository).default.should == name
 
       PartyResource::Connector.add(name2, options)
-      PartyResource::Connector.repository.default.should == name
+      PartyResource::Connector.send(:repository).default.should == name
     end
 
     it 'sets the default if the default option is set' do

data/spec/unit/exceptions_spec.rb

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 describe 'Exceptions' do
 
-  describe PartyResource::ConnectionError do
-    subject { PartyResource::ConnectionError }
+  describe PartyResource::Exceptions::ConnectionError do
+    subject { PartyResource::Exceptions::ConnectionError }
 
     describe 'build' do
       let(:built) { subject.build(data) }
@@ -11,22 +11,22 @@ describe 'Exceptions' do
 
       it 'builds ResourceNotFound' do
         data.stub(:code => 404)
-        built.should be_a(PartyResource::ResourceNotFound)
+        built.should be_a(PartyResource::Exceptions::ResourceNotFound)
       end
 
       it 'builds ResourceInvalid' do
         data.stub(:code => 422)
-        built.should be_a(PartyResource::ResourceInvalid)
+        built.should be_a(PartyResource::Exceptions::ResourceInvalid)
       end
 
       it 'builds ClientError' do
         data.stub(:code => 400)
-        built.should be_a(PartyResource::ClientError)
+        built.should be_a(PartyResource::Exceptions::ClientError)
       end
 
       it 'builds ServerError' do
         data.stub(:code => 500)
-        built.should be_a(PartyResource::ServerError)
+        built.should be_a(PartyResource::Exceptions::ServerError)
       end
     end
   end

data/spec/unit/party_resource_spec.rb

@@ -84,25 +84,6 @@ describe "PartyResource" do
     end
   end
 
-  describe '.Connector' do
-    context 'with name == nil' do
-      it 'returns the default connector' do
-        connector = mock(:connector)
-        PartyResource::Connector.should_receive(:lookup).with(nil).and_return(connector)
-        PartyResource::Connector(nil).should == connector
-      end
-    end
-
-    context 'with a name given' do
-      it 'returns the requested connector' do
-        connector = mock(:connector)
-        name = mock(:name)
-        PartyResource::Connector.should_receive(:lookup).with(name).and_return(connector)
-        PartyResource::Connector(name).should == connector
-      end
-    end
-  end
-
   describe '.parameter_values' do
     let_mock(:v1)
     let_mock(:v2)
@@ -114,7 +95,7 @@ describe "PartyResource" do
 
     it 'raises a MissingParameter error' do
       subject.stub(:v1 => v1)
-      lambda { subject.parameter_values([:v1, :vx]) }.should raise_error(PartyResource::MissingParameter)
+      lambda { subject.parameter_values([:v1, :vx]) }.should raise_error(PartyResource::Exceptions::MissingParameter)
     end
   end
 

data/spec/unit/route_spec.rb

@@ -12,7 +12,7 @@ describe PartyResource::Route do
   let(:options) { { :get => path, :as => klass } }
 
   before do
-    PartyResource.stub(:Connector => connector)
+    PartyResource::Connector.stub(:lookup => connector)
   end
 
   describe ".call" do

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Tristan Harris
@@ -19,8 +19,6 @@ date: 2010-05-26 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: httparty
-  prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
@@ -30,11 +28,11 @@ dependencies:
         - 5
         - 2
         version: 0.5.2
+  name: httparty
+  prerelease: false
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: activesupport
-  prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
@@ -44,11 +42,11 @@ dependencies:
         - 3
         - 5
         version: 2.3.5
+  name: activesupport
+  prerelease: false
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: rspec
-  prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
@@ -58,11 +56,11 @@ dependencies:
         - 2
         - 9
         version: 1.2.9
+  name: rspec
+  prerelease: false
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: yard
-  prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
@@ -70,11 +68,11 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  name: yard
+  prerelease: false
   type: :development
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: webmock
-  prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
@@ -82,6 +80,8 @@ dependencies:
         segments: 
         - 0
         version: "0"
+  name: webmock
+  prerelease: false
   type: :development
   version_requirements: *id005
 description: party_resource is a framework for building ruby objects which interact with a REST api. Built on top of HTTParty.
@@ -92,7 +92,7 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.rdoc
+- README.md
 files: 
 - lib/party_resource.rb
 - lib/party_resource/buildable.rb
@@ -105,7 +105,7 @@ files:
 - lib/party_resource/request.rb
 - lib/party_resource/route.rb
 - LICENSE
-- README.rdoc
+- README.md
 has_rdoc: true
 homepage: http://github.com/edendevelopment/party_resource.git
 licenses: []

data/README.rdoc

@@ -1,19 +0,0 @@
-= party_resource
-
-Simple REST interface for ruby objects.
-
-party_resource is a framework for building ruby objects which interact with a REST api. Built on top of HTTParty.
-
-== Note on Patches/Pull Requests
- 
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-== Copyright
-
-Copyright (c) 2010 Eden Development (UK) LTD. See LICENSE for details.