gendered 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 45dd165cc82b4c0d37492943c3e0b404df8a8001
-  data.tar.gz: 2dfab03e1dcf771e14e25ed8addc0db487ceb746
+  metadata.gz: 1af845c196c001b0efd2690158669dba52ada027
+  data.tar.gz: 4e014c3a1de5f4a10249682f652cb892a3d20271
 SHA512:
-  metadata.gz: ad9be58b9a724ec1d1bdbbc02b6b1ea0d97b433b9fc09bfc8d47afa5fc014cfaea1c473a83065dafe2ce3606e26fd85239d65a4e66f6cedd64d61aaf029abd75
-  data.tar.gz: afe8c2d93528556df06443068e38b537c2641bfe411fe1250facea51547523294a0415670119daccbd66429ac34a171f17f4384118f285efce1ce351457446f5
+  metadata.gz: 25bfd3b3bcf1edcbe8d7a5fbaba079282999b0ebdd5cb8defd8ffea517e90d5256c44783e4d095c52faceefc168f80a4fe06fb2fdf48860f366c65f1bb11c3c0
+  data.tar.gz: cd8e3243ea578a02eb7893ef59223ad1c37e1d90407bb5dd9752244bcab341f8c7fde2b19d0c3eefe3bd93ba130aabfbf9e94c2f2ab9de4c85d7cb8a2c6b0861

data/README.md

@@ -43,3 +43,20 @@ Or batch up a list of names (which sends only one request per hundred names to t
 > name_list["Sean"].gender
 => :male
 ```
+
+Options can be passed in too...
+```ruby
+options = { :apikey => "X123Y456", :country_id => "dk" }
+name = Gendered::Name.new("Sean")
+name.guess!(options)
+name_list = Gendered::NameList.new(["Kim", "Theresa"], options)
+```
+
+Or set globally, as defaults...
+```ruby
+Gendered.configure do |config|
+  config.apikey = "X123Y456"
+  config.language_id = "pt"
+  # ...
+end
+```

data/lib/gendered.rb

@@ -1,4 +1,4 @@
-require 'bigdecimal'
+require "bigdecimal"
 
 require "http"
 
@@ -8,5 +8,32 @@ require "gendered/name_list"
 require "gendered/guesser"
 
 module Gendered
+  GenderedError = Class.new(StandardError)
+  class RateLimitError < GenderedError
+    attr_reader :limit, :remaining, :reset
 
+    def initialize(message, limit, remaining, reset)
+      super(message)
+      @limit = limit
+      @remaining = remaining
+      @reset = reset
+    end
+  end
+
+  class Config < Struct.new(:apikey, :country_id, :language_id, :connection)
+    def merge(other)
+      hash = respond_to?(:to_h) ? to_h : Hash[each_pair.to_a]
+      hash.merge!(other)
+      hash.reject! { |k,v| v.nil? }
+    end
+  end
+
+  def self.configure
+    raise ArgumentError, "configuration block required" unless block_given?
+    yield config
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
 end

data/lib/gendered/guesser.rb

@@ -1,51 +1,84 @@
+require "json"
+
 module Gendered
   class Guesser
+    ENDPOINT = "https://api.genderize.io".freeze
+    USAGE_HEADERS = {
+      "X-Rate-Limit-Limit" => :limit,
+      "X-Rate-Limit-Remaining" => :remaining,
+      "X-Rate-Reset" => :reset
+    }.freeze
 
-    attr_accessor :names, :country_id
+    attr_reader :usage
+    attr_accessor :names, :options
 
-    def initialize(values, country_id = nil)
-      raise ArgumentError, "cannot be empty" if Array(values).empty?
+    def initialize(names, options = {})
+      @names = Array(names)
+      raise ArgumentError, "names cannot be empty" if @names.empty?
 
-      @names = Array(values)
-      @country_id = country_id
+      @options = Gendered.config.merge(options || {})
+      @options[:connection] ||= {}
+      @usage = { :limit => nil, :remaining => nil, :reset => nil }
     end
 
     def guess!
-      response = HTTP.get(url)
+      response = request(request_options)
+      update_usage(response)
+      body = parse(response.body)
       case response.code
       when 200
+        create_names(body)
+      when 429
+        raise RateLimitError.new(body["error"], *@usage.values_at(:limit, :remaining, :reset))
+      else
+        raise GenderedError.new(body["error"])
+      end
+    end
 
-        guesses = JSON.parse(response.body)
-
-        names.collect do |name|
-          name = Name.new(name) if name.is_a?(String)
+    private
 
-          guess = case
-          when guesses.is_a?(Array)
-            guesses.find { |g| g["name"] == name.value }
-          else
-            guesses
-          end
+    def update_usage(response)
+      USAGE_HEADERS.each { |header, key| @usage[key] = response[header].to_i }
+    end
 
-          if guess["gender"]
-            name.gender = guess["gender"].to_sym
-            name.probability = guess["probability"]
-            name.sample_size = guess["count"]
-          end
+    def create_names(guesses)
+      names.collect do |name|
+        name = Name.new(name) if name.is_a?(String)
+        guess = case
+                when guesses.is_a?(Array)
+                  guesses.find { |g| g["name"] == name.value }
+                else
+                  guesses
+                end
 
-          name
+        if guess["gender"]
+          name.gender = guess["gender"].to_sym
+          name.probability = guess["probability"]
+          name.sample_size = guess["count"]
         end
+
+        name
       end
     end
 
-    def url
-      url = "https://api.genderize.io/?"
-      url += "country_id=#{country_id}&" if country_id
+    def request_options
+      options = {}
+      options[:params] = @options.reject { |k, v| k == :connection || v.nil? }
+      options[:params]["name[]"] = @names
+      options[:connection] = @options[:connection] unless @options[:connection].empty?
+      options
+    end
 
-      name_queries = names.collect.with_index do |name, index|
-        "name[#{index}]=#{CGI.escape(name.to_s)}"
-      end
-      url + name_queries.join("&")
+    def request(options)
+      HTTP.get(ENDPOINT, options)
+    rescue => e
+      raise GenderedError, "request failed: #{e}"
+    end
+
+    def parse(response)
+      JSON.parse(response)
+    rescue JSON::ParserError => e
+      raise GenderedError, "cannot parse response JSON: #{e}"
     end
   end
 end

data/lib/gendered/name.rb

@@ -1,6 +1,6 @@
 module Gendered
   class Name
-    VALID_GENDERS = %i(male female)
+    VALID_GENDERS = [:male, :female]
 
     attr_reader :value
 
@@ -16,8 +16,8 @@ module Gendered
       !!@gender
     end
 
-    def guess!(country_id = nil)
-      Guesser.new(self, country_id).guess!
+    def guess!(options = {})
+      Guesser.new(self, options).guess!
       gender
     end
 

data/lib/gendered/name_list.rb

@@ -4,18 +4,20 @@ module Gendered
 
     attr_reader :names
 
-    def initialize(values)
+    def initialize(values, options = {})
       @names = Array(values).collect do |value|
         case value
         when String then Name.new(value)
         when Name then value
         end
       end
+
+      @options = options || {}
     end
 
-    def guess!(country_id = nil)
+    def guess!
       names.each_slice(100).each do |slice|
-        Guesser.new(slice).guess!(country_id)
+        Guesser.new(slice, @options).guess!
       end
       names.collect(&:gender)
     end

data/lib/gendered/version.rb

@@ -1,3 +1,3 @@
 module Gendered
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/spec/lib/config_spec.rb

@@ -0,0 +1,39 @@
+module Gendered
+  describe ".configure" do
+    let :settings do
+      {
+        :apikey      => "key",
+        :country_id  => "us",
+        :language_id => "en",
+        :connection  => { :foo => "bar" }
+      }
+    end
+
+    it "allows configuration via a block" do
+      Gendered.configure do |config|
+        settings.each do |name, value|
+          config[name] = value
+        end
+      end
+
+      settings.each do |name, value|
+        expect(Gendered.config[name]).to eq value
+      end
+    end
+  end
+
+  describe Config do
+    subject do
+      Gendered.config
+    end
+
+    describe "#merge" do
+      it "overrides the default config" do
+        subject[:country_id] = "us"
+        subject[:language_id] = "en"
+
+        expect(subject.merge(:language_id => "pt")).to eq(:country_id => "us", :language_id => "pt")
+      end
+    end
+  end
+end

data/spec/lib/gendered/guesser_spec.rb

@@ -1,8 +1,7 @@
 module Gendered
   describe Guesser do
-
     let :names do
-      ["Sean","Theresa"]
+      ["Sean", "Theresa"]
     end
 
     subject do
@@ -13,19 +12,81 @@ module Gendered
       expect(subject.names).to eq names
     end
 
-    it "is initialized with country id" do
-      guesser = Guesser.new(names, 'us')
-      expect(guesser.country_id).to eq 'us'
-    end
-
-    it "creates the correct url" do
-      expect(subject.url).to eq "https://api.genderize.io/?name[0]=Sean&name[1]=Theresa"
+    it "creates the correct request" do
+      params = { "name[]" => names }
+      expect(subject).to receive(:request).with(:params => params).and_return(fake_response)
+      subject.guess!
     end
 
     it "cannot be initialized with an empty array" do
       expect{described_class.new([])}.to raise_error ArgumentError
     end
 
+    it "raises an error when over the rate limit" do
+      response = fake_response(:code => 429, :usage => { :limit => 1, :remaining => 0, :reset => 2 })
+      expect(subject).to receive(:request).and_return(response)
+      expect { subject.guess! }.to raise_error(RateLimitError) { |error|
+        expect(error.remaining).to eq 0
+        expect(error.limit).to eq 1
+        expect(error.reset).to eq 2
+      }
+    end
+
+    describe "options" do
+      [:country_id, :language_id, :apikey].each do |option|
+        context "given the #{option} option" do
+          subject do
+            Guesser.new(names, option => option)
+          end
+
+          it "is initialized correctly" do
+            expect(subject.options[option]).to eq option
+          end
+
+          it "creates the correct request" do
+            params = hash_including(:params => { "name[]" => names, option => option })
+            expect(subject).to receive(:request).with(params).and_return(fake_response)
+            subject.guess!
+          end
+        end
+      end
+
+      context "given the :connection option" do
+        subject do
+          options = { :apikey => "key", :connection => { :foo => "bar" } }
+          Guesser.new(names, options)
+        end
+
+        it "is passed to the connection" do
+          params = hash_including(:connection => { :foo => "bar" })
+          expect(subject).to receive(:request).with(params).and_return(fake_response)
+          subject.guess!
+        end
+      end
+    end
+
+    describe "#usage" do
+      let :usage do
+        { :limit => nil, :remaining => nil, :reset => nil }
+      end
+
+      it "has no values until a request is made" do
+        expect(subject.usage).to eq usage
+      end
+
+      it "is populated after each request" do
+        usage.keys.each_with_index { |k, i| usage[k] = i }
+        expect(subject).to receive(:request).and_return(fake_response(:usage => usage))
+        subject.guess!
+        expect(subject.usage).to eq usage
+
+        usage.keys.each { |k| usage[k] += 1 }
+        expect(subject).to receive(:request).and_return(fake_response(:usage => usage))
+        subject.guess!
+        expect(subject.usage).to eq usage
+      end
+    end
+
     describe "#guess!" do
       it "returns a valid guesses hash" do
         names = subject.guess!
@@ -39,8 +100,9 @@ module Gendered
       let :names do
         ["Evat"]
       end
+
       it "does not error" do
-        expect{subject.guess!}.to_not raise_error
+        expect{ subject.guess! }.to_not raise_error
       end
     end
 
@@ -48,6 +110,7 @@ module Gendered
       let :names do
         ["Sean","Sean"]
       end
+
       it "guesses them both" do
         guesses = subject.guess!
         expect(guesses.collect(&:gender).uniq.size).to eq 1

data/spec/lib/gendered/name_list_spec.rb

@@ -3,24 +3,28 @@ module Gendered
     subject do
       described_class.new values
     end
+
     let :values do
-      ["Sean","Theresa"] * 50
+      ["Sean", "Theresa"] * 50
     end
+
     describe "#guess!" do
       it "guesses correctly" do
         guesser = double(Guesser)
         expect(guesser).to receive(:guess!)
-        expect(Guesser).to receive(:new).with(subject.names).and_return(guesser)
+        expect(Guesser).to receive(:new).with(subject.names, {}).and_return(guesser)
         subject.guess!
       end
 
-      it 'guesses correctly with country id' do
+      it "guesses correctly with country_id" do
+        subject = described_class.new(values, :country_id => "us")
         guesser = double(Guesser)
-        expect(guesser).to receive(:guess!).with('us')
-        expect(Guesser).to receive(:new).with(subject.names).and_return(guesser)
-        subject.guess!('us')
+        expect(guesser).to receive(:guess!)
+        expect(Guesser).to receive(:new).with(subject.names, :country_id => "us").and_return(guesser)
+        subject.guess!
       end
     end
+
     context "when the values are strings" do
       it "sets the names" do
         subject.names.each.with_index do |name, index|
@@ -28,10 +32,12 @@ module Gendered
         end
       end
     end
+
     context "when the values are names" do
       let :values do
-        [Name.new("Sean"),Name.new("Theresa")]
+        [Name.new("Sean"), Name.new("Theresa")]
       end
+
       it "sets the names" do
         expect(subject.names).to eq values
       end

data/spec/lib/gendered/name_spec.rb

@@ -20,14 +20,29 @@ module Gendered
     end
 
     describe "guess!" do
+      it "sets the gender" do
+        subject.guess!
+        expect(subject.gender).to eq :male
+      end
+
+      it "sets the probability" do
+        subject.guess!
+        expect(subject.probability).to be_a BigDecimal
+      end
+
+      it "sets the sample size" do
+        subject.guess!
+        expect(subject.sample_size).to be_a Integer
+      end
+
       it "returns the gender" do
         expect(subject.guess!).to eq :male
       end
 
-      it 'returns gender by country id' do
-        name = Gendered::Name.new('kim')
+      it "returns gender by country id" do
+        name = Gendered::Name.new("kim")
         expect(name.guess!).to eq :female
-        expect(name.guess!('dk')).to eq :male
+        expect(name.guess!(:country_id => "dk")).to eq :male
       end
     end
 
@@ -38,6 +53,7 @@ module Gendered
           expect(subject.gender).to eq value
         end
       end
+
       it "raises an argument error if the gender is set to something invalid" do
         %w(eunich).each do |value|
           expect{subject.gender = value}.to raise_error(ArgumentError)

data/spec/spec_helper.rb

@@ -1,5 +1,39 @@
 require "gendered"
 
 RSpec.configure do |config|
+  config.after :each do
+    Gendered.config.members.each do |name|
+      Gendered.config[name] = nil
+    end
+  end
 
+  config.include Module.new {
+    SUCCESS_RESPONSE = {
+      :count => 100,
+      :gender => "male",
+      :name => "Sean",
+      :probability => 1.0
+    }
+
+    FAILURE_RESPONSE = {
+      :error => "Some thang went wrong"
+    }
+
+    def fake_response(options = {})
+      code = options[:code] || 200
+      body = (code == 200 ? SUCCESS_RESPONSE : FAILURE_RESPONSE).merge(options[:body] || {})
+
+      headers = {}
+      usage = options[:usage] || {}
+
+      Gendered::Guesser::USAGE_HEADERS.each do |header, key|
+        headers[header] = usage.include?(key) ? usage[key] : header.object_id
+      end
+
+      response = double(:code => code, :body => JSON.dump(body))
+      allow(response).to receive(:[]) { |name| headers[name] }
+
+      response
+    end
+  }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gendered
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
 platform: ruby
 authors:
 - Sean Devine
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-23 00:00:00.000000000 Z
+date: 2015-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -91,6 +91,7 @@ files:
 - lib/gendered/name.rb
 - lib/gendered/name_list.rb
 - lib/gendered/version.rb
+- spec/lib/config_spec.rb
 - spec/lib/gendered/guesser_spec.rb
 - spec/lib/gendered/name_list_spec.rb
 - spec/lib/gendered/name_spec.rb
@@ -115,13 +116,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Guess the gender of a name.
 test_files:
+- spec/lib/config_spec.rb
 - spec/lib/gendered/guesser_spec.rb
 - spec/lib/gendered/name_list_spec.rb
 - spec/lib/gendered/name_spec.rb
 - spec/spec_helper.rb
-has_rdoc: