crowdkit 0.1.0

data/lib/crowdkit.rb

@@ -0,0 +1,77 @@
+require 'sawyer'
+require 'crowdkit/version'
+require 'crowdkit/core_ext/hash'
+require 'crowdkit/core_ext/array'
+require 'crowdkit/core_ext/sawyer'
+require 'crowdkit/config'
+require 'crowdkit/api'
+require 'crowdkit/client'
+require 'crowdkit/error'
+require 'crowdkit/middleware/raise_error'
+
+module Crowdkit
+  def self.new(overrides={}, &block)
+    #Use the global config if no overrides present
+    if @configuration && overrides.empty? && !block_given?
+      Client.new(@configuration)
+    else
+      Client.new(overrides, &block)
+    end
+  end
+
+  def self.last_response
+    @last_response
+  end
+
+  def self.last_response=(last_response)
+    @last_response = last_response
+  end
+
+  def self.configure(overrides={}, &block)
+    @configuration = Config.new(overrides, &block)
+  end
+
+  def self.reset!
+    @last_response = nil
+    @configuration = nil
+  end
+
+  # This takes a response from a resource that processes something in the
+  # background (i.e. a 202 response) and will ping the status API until it timesout
+  # an error is returned, or the background process is completed.
+  def self.wait_on_status(resource, max_time_to_wait_in_seconds = 30)
+    raise ArgumentError, "This resource did not respond with a 202 status code and has no status to wait on." unless resource.last_response.status == 202
+    progressbar = ProgressBar.create(total: 100)
+    status = resource.current_status
+    wait = 1
+
+    max_time_to_wait_in_seconds.times do |i|
+      break if status.state == "completed"
+      raise StatusError.new(status) if ["failed", "killed"].include?(status.state)
+
+      #increase wait time to 5 seconds after 5 seconds
+      wait = 5 if i == 5
+      #increase wait time to 10 seconds after 30 seconds
+      wait = 10 if i == 30
+
+      if i % wait == 0
+        percents = status.percent_complete.to_i
+        progressbar.progress = percents if percents > 0
+        sleep(wait)
+        status = resource.current_status
+      end
+    end
+
+    raise StatusError.new(status, true) unless status.state == "completed"
+    progressbar.finish
+    status
+  end
+
+  private
+
+  #Not convinced we even want to support this...
+  def self.method_missing(method_name, *args, &block)
+    return super unless new.respond_to?(method_name)
+    new.send(method_name, *args, &block)
+  end
+end

data/lib/crowdkit/api.rb

@@ -0,0 +1,171 @@
+require 'crowdkit/api/arguments'
+require 'crowdkit/api/factory'
+require 'crowdkit/api/request_methods'
+require 'crowdkit/api/response_wrapper'
+
+module Crowdkit
+  class API
+    extend Forwardable
+    include RequestMethods
+    attr_accessor :stored_params
+    attr_reader :config, :client
+    attr_writer :auto_pagination
+
+    #We delegate last_response to the attr_accessor of the top level Client
+    def_delegators :client, :last_response, :last_response=
+
+    #This should only be called by API Factory to ensure _config, and _client
+    #get set.  We override this in Client as it's the root of the API.
+    def initialize(options, &block)
+      @config = options.delete(:_config)
+      @client = options.delete(:_client)
+      @stored_params = options
+      with(options)
+    end
+
+    def auto_pagination
+      @auto_pagination || @config.auto_paginate
+    end
+
+    # Acts as setter and getter for api requests arguments parsing.
+    #
+    # Returns Arguments instance.
+    #
+    def arguments(args=(not_set = true), options={}, &block)
+      if not_set
+        @arguments
+      else
+        @arguments = Arguments.new(self, options.symbolize_keys).parse(*args, &block)
+      end
+    end
+
+    # Set an option to a given value
+    #
+    # @param [String] option
+    # @param [Object] value
+    # @param [Boolean] ignore_setter
+    #
+    # @return [self]
+    #
+    # @api public
+    def set(option, value=(not_set=true), ignore_setter=false, &block)
+      raise ArgumentError, 'value not set' if block and !not_set
+      return self if !not_set and value.nil?
+
+      if not_set
+        set_options option
+        return self
+      end
+
+      if respond_to?("#{option}=") and not ignore_setter
+        return __send__("#{option}=", value)
+      end
+
+      define_accessors option, value
+      self
+    end
+
+    #overridden in children API's that have their own id's
+    def id_key
+      :job_id
+    end
+
+    # Scope for passing request required arguments.
+    #
+    def with(args)
+      case args
+      when Hash
+        #This happens when the job id is passed early in the chain
+        if (custom = args.delete(:_args)) && custom.first
+          stored_params[id_key] = custom.first
+          set id_key, custom.first
+        end
+        set args
+      when Fixnum, /^(\d+|([a-z])([a-z]|\d)*)$/
+        stored_params[id_key] = args
+        set id_key, args
+      else
+        ::Kernel.raise ArgumentError, 'This api does not support passed in arguments'
+      end
+    end
+
+    # Defines a namespace
+    #
+    # @param [Array[Symbol]] names
+    #   the name for the scope
+    #
+    # @return [self]
+    #
+    # @api public
+    def self.namespace(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      names   = names.map(&:to_sym)
+      name    = names.pop
+      return if public_method_defined?(name)
+
+      class_name = extract_class_name(name, options)
+      define_method(name) do |*args, &block|
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options[:_args] = args
+        options[:_config] = @config
+        options[:_client] = @client
+        API::Factory.new(class_name, stored_params.merge(options), &block)
+      end
+      self
+    end
+
+    # Extracts class name from options
+    #
+    # @return [String]
+    #
+    # @api private
+    def self.extract_class_name(name, options)
+      if !options[:class_name]
+        converted  = options.fetch(:full_name, name).to_s
+        converted  = converted.split('_').map(&:capitalize).join
+        class_name = options.fetch(:root, false) ? '': "#{self.name}::"
+        class_name += converted
+        class_name
+      else
+        options[:class_name]
+      end
+    end
+
+    private
+
+    # Set multiple options
+    #
+    # @api private
+    def set_options(options)
+      unless options.respond_to?(:each)
+        raise ArgumentError, 'cannot iterate over value'
+      end
+      options.each { |key, value| set(key, value) }
+    end
+
+    # Define setters and getters
+    #
+    # @api private
+    def define_accessors(option, value)
+      setter = proc { |val|  set option, val, true }
+      getter = proc { value }
+
+      define_singleton_method("#{option}=", setter) if setter
+      define_singleton_method(option, getter) if getter
+    end
+
+    # Dynamically define a method for setting request option
+    #
+    # @api private
+    def define_singleton_method(method_name, content=Proc.new)
+      (class << self; self; end).class_eval do
+        undef_method(method_name) if method_defined?(method_name)
+        if String === content
+          class_eval("def #{method_name}() #{content}; end")
+        else
+          define_method(method_name, &content)
+        end
+      end
+    end
+  end # API
+end # Crowdkit

data/lib/crowdkit/api/arguments.rb

@@ -0,0 +1,187 @@
+module Crowdkit
+  class API
+    # Request arguments handler
+    class Arguments
+      AUTO_PAGINATION = :auto_pagination
+
+      # Parameters passed to request
+      attr_reader :params
+
+      attr_reader :remaining
+
+      # The request api
+      #
+      attr_reader :api
+
+      # Required arguments
+      #
+      attr_reader :required
+      private :required
+
+      # Optional arguments
+      #
+      attr_reader :optional
+      private :optional
+
+      # Takes api, filters and required arguments
+      #
+      # = Parameters
+      #  :required - arguments that must be present before request is fired
+      #
+      def initialize(api, options={})
+        @api      = api
+        @required = options.fetch(:required, []).map(&:to_s)
+        @optional = options.fetch(:optional, []).map(&:to_s)
+      end
+
+      # Parse arguments to allow for flexible api calls.
+      # Arguments can be part of parameters hash or be simple string arguments.
+      #
+      def parse(*args, &block)
+        options = args.extract_options!
+
+        if !args.empty? && ![File, Array].include?(args.last.class)
+          parse_arguments *args
+        else
+          # Arguments are inside the parameters hash
+          parse_options options
+        end
+
+        @params = options
+        @remaining = extract_remaining(args)
+        extract_pagination(options)
+        yield_or_eval(&block)
+        self
+      end
+
+      # Check if required keys are present inside parameters hash.
+      #
+      def assert_required(required)
+        assert_required_keys required, params
+        self
+      end
+
+      # Check if parameters match expected values.
+      #
+      def assert_values(values, key=nil)
+        assert_valid_values values, (key.nil? ? params : params[key])
+        self
+      end
+
+      private
+
+      # Check and set all requried arguments.
+      #
+      def parse_arguments(*args)
+        assert_presence_of *args
+        required.each_with_index do |req, indx|
+          api.set req, args[indx]
+        end
+        check_requirement!(*args)
+      end
+
+      # Find remaining arguments
+      #
+      def extract_remaining(args)
+        args[required.size..-1]
+      end
+
+      # Fine auto_pagination parameter in options hash
+      #
+      def extract_pagination(options)
+        if (value = options.delete(AUTO_PAGINATION))
+          api.client.auto_pagination = value
+        end
+      end
+
+      # Remove required arguments from parameters and
+      # validate their presence(if not nil or empty string).
+      #
+      def parse_options(options)
+        options.each { |key, val| remove_required(options, key, val) }
+        provided_args = check_assignment!(options)
+        check_requirement!(*provided_args.keys)
+      end
+
+      # Remove required argument from parameters
+      #
+      def remove_required(options, key, val)
+        key = key.to_s
+        if required.include? key
+          assert_presence_of val
+          options.delete key.intern
+          api.set key, val
+        end
+      end
+
+      # Check if required arguments have been set on instance.
+      #
+      def check_assignment!(options)
+        result = required.inject({}) { |hash, arg|
+          if api.respond_to?(:"#{arg}")
+            hash[arg] = api.send(:"#{arg}")
+          else
+            hash[arg] = nil
+          end
+          hash
+        }
+        assert_presence_of result
+        result
+      end
+
+      # Check if required arguments are present.
+      #
+      def check_requirement!(*args)
+        args_length     = args.length
+        required_length = required.length
+
+        if args_length < required_length
+          ::Kernel.raise ArgumentError, "wrong number of arguments (#{args_length} for #{required_length})"
+        end
+      end
+
+      # Ensure that esential arguments are present before request is made.
+      #
+      # == Parameters
+      #  Hash/Array of arguments to be checked against nil and empty string
+      #
+      # == Example
+      #  assert_presence_of user: '...', repo: '...'
+      #  assert_presence_of user, repo
+      #
+      def assert_presence_of(*args)
+        hash = args.last.is_a?(::Hash) ? args.pop : {}
+
+        errors = hash.select { |key, val| val.to_s.empty? }
+        raise Crowdkit::ValidationError.new(errors) unless errors.empty?
+
+        args.each do |arg|
+          raise ArgumentError, "parameter cannot be nil" if arg.nil?
+        end
+      end
+
+      # Validate all keys present in a provided hash against required set,
+      # on mismatch raise CrowdKit::Error::RequiredParams
+      # Note that keys need to be in the same format i.e. symbols or strings,
+      # otherwise the comparison will fail.
+      #
+      def assert_required_keys(required, provided)
+        result = required.all? do |key|
+          provided.deep_key? key
+        end
+        if !result
+          raise CrowdKit::RequiredParams.new(provided, required)
+        end
+        result
+      end
+
+      # Evaluate block
+      #
+      def yield_or_eval(&block)
+        return unless block
+        block.arity > 0 ? yield(self) : self.instance_eval(&block)
+      end
+
+    end # Arguments
+  end # Api
+end # Crowdkit

data/lib/crowdkit/api/factory.rb

@@ -0,0 +1,29 @@
+module Crowdkit
+  class API
+    class Factory
+
+      # Instantiates a new CrowdFlower api object
+      #
+      def self.new(klass, options={}, &block)
+        return create_instance(klass, options, &block) if klass
+        raise ArgumentError, 'must provide API class to be instantiated'
+      end
+
+      # Passes configuration options to instantiated class
+      #
+      def self.create_instance(klass, options, &block)
+        options.symbolize_keys!
+        convert_to_constant(klass.to_s).new options, &block
+      end
+
+      # Convert name to constant
+      #
+      def self.convert_to_constant(classes)
+        classes.split('::').inject(Crowdkit) do |constant, klass|
+          constant.const_get klass
+        end
+      end
+
+    end # Factory
+  end # Api
+end # Crowdkit