eve_badger 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d466155cb066385f95d91b504852a9e926229b7
-  data.tar.gz: f20836c0e7d123b9d3f841300b1178ec38eded52
+  metadata.gz: 7106375fe68a66fd53f03bff72a195bd64d98e7b
+  data.tar.gz: 3c1a5413f29c173d50dd79d2ec8393e129014e0a
 SHA512:
-  metadata.gz: a6309c1516bf5e704f878ba241e9480d47ab9609e4be1e48404c19fdeb39c05c8dd3dc11e21edec7c96837591abc9bb338fa115c9bfb15bc77e7ec13e7deb97c
-  data.tar.gz: 85a43012be2168f6f89e11a79be09a60054467445a9974619d882fb054c2383d1bd1dbdec8e2f8a8827e51f1313105ad333bcb430faed7aa9248055a37849dc6
+  metadata.gz: 8e45cc78bef49f7b6afaca5bbc2ca6cf1a3a902f840bef7caf9a76cce47ccbbf734e074357dceb0c7a06d0be4d7b267674a78a6bce3a1c761959fe41a50666f3
+  data.tar.gz: b62c670fd8059cbf02ada0e30b93e7917ee64430970d47e2c12ac98477731300f81214f1042e08c4ed891fbc40d26757e0b740cd241fc06bde49a1a2aa8ba73e

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/lib/eve_badger.rb

@@ -9,14 +9,17 @@ module EveBadger
     @version ||= File.read(File.expand_path(File.join(File.dirname(__FILE__), '..', 'VERSION'))).chomp
   end
 
+  # provides the default user agent for EveAPI objects, it's a good idea to customize your user agent string to identify your application
   def self.default_user_agent
     "EveBadger-#{EveBadger.version}/Ruby-#{RUBY_VERSION}"
   end
 
+  # provides the default domain for the tranquility (live game server) api
   def self.default_tq_domain
     'https://api.eveonline.com/'
   end
 
+  # provides the detault domain for the singularity (public test server, nicknamed "sisi") api
   def self.default_sisi_domain
     'https://api.testeveonline.com/'
   end

data/lib/eve_badger/cache.rb

@@ -18,18 +18,22 @@ module EveBadger
       @cache = Moneta.new(*args, **kwargs)
     end
 
+    # disable request caching
     def self.disable
       @cache = nil
     end
 
+    # test whether request caching is enabled
     def self.enabled?
       @cache ? true : false
     end
 
+    # return the class type of the enabled cache, caches adapters which don't natively support expiration will all appear as Moneta::Expires
     def self.type
       @cache.class
     end
 
+    # store a value in the cache if it is enabled
     def self.store(key, value, options={})
       if @cache
         @cache.store(key, value, options)
@@ -38,6 +42,7 @@ module EveBadger
       end
     end
 
+    # retrieve a value from the cache it if is enabled
     def self.get(key)
       if @cache
         @cache[key]

data/lib/eve_badger/endpoints.rb

@@ -4,52 +4,63 @@ module EveBadger
   class Endpoint
     attr_reader :path, :access_mask, :detail_id
 
+    # initialize with :path, :access_mask and optionally :detail_id
     def initialize(data)
       @path = data[:path]
       @access_mask = data[:access_mask]
       @detail_id = data[:detail_id] if data[:detail_id]
     end
 
+    # test whether a given api key bitmask is sufficient to make a request against this endpoint
     def permitted?(other_mask)
       @access_mask.zero? or (other_mask & @access_mask != 0)
     end
   end
 
+  # loads endpoint data from JSON files packaged with the gem, these JSON files are easily edited if API endpoints are added or changed in the future
   module Endpoints
+    # load account endpoint data
     open(File.join(File.dirname(__FILE__), 'json', 'account_endpoints.json'), 'r') do |file|
       @account_endpoints = JSON.parse(file.read.to_s, :symbolize_names => true)
     end
 
+    # load character endpoint data
     open(File.join(File.dirname(__FILE__), 'json', 'character_endpoints.json'), 'r') do |file|
       @character_endpoints = JSON.parse(file.read.to_s, :symbolize_names => true)
     end
 
+    # load corporation endpoint data
     open(File.join(File.dirname(__FILE__), 'json', 'corporation_endpoints.json'), 'r') do |file|
       @corporation_endpoints = JSON.parse(file.read.to_s, :symbolize_names => true)
     end
 
+    # load detail endpoint data
     open(File.join(File.dirname(__FILE__), 'json', 'detail_endpoints.json'), 'r') do |file|
       @detail_endpoints = JSON.parse(file.read.to_s, :symbolize_names => true)
     end
 
+    # takes an account endpoint name and returns an endpoint data object
     def self.account(endpoint)
       data = @account_endpoints[endpoint]
       raise ArgumentError, "unsupported endpoint: #{endpoint}" unless data
       Endpoint.new(data)
     end
 
+    # takes a character endpoint name and returns an endpoint data object
     def self.character(endpoint)
       data = @character_endpoints[endpoint]
       raise ArgumentError, "unsupported endpoint: #{endpoint}" unless data
       Endpoint.new(data)
     end
 
+    # takes a corporation endpoint name and returns an endpoint data object
     def self.corporation(endpoint)
       data = @corporation_endpoints[endpoint]
       raise ArgumentError, "unsupported endpoint: #{endpoint}" unless data
       Endpoint.new(data)
     end
 
+    # takes a detail endpoint name and returns an endpoint data object
     def self.detail(endpoint)
       data = @detail_endpoints[endpoint]
       raise ArgumentError, "unsupported endpoint: #{endpoint}" unless data

data/lib/eve_badger/eve_api.rb

@@ -18,40 +18,49 @@ module EveBadger
       @key_type = args[:key_type].to_sym if args[:key_type]
     end
 
+    # sets key_it, coerces to string
     def key_id=(id)
       @key_id = id ? id.to_s : nil
     end
 
+    # sets vcode, coerces to string
     def vcode=(code)
       @vcode = code ? code.to_s : nil
     end
 
+    # sets character_id, coerces to string
     def character_id=(id)
       @character_id = id ? id.to_s : nil
     end
 
+    # sets access_mask, coerces to integer
     def access_mask=(mask)
       @access_mask = mask ? mask.to_i : nil
     end
 
+    # sets key_type, coerces to symbol
     def key_type=(type)
       @key_type = type ? type.to_sym : nil
     end
 
+    # access or retrieve access_mask, will also set key_type if an automatic fetch is triggered
     def access_mask
       @access_mask ||= get_access_mask
     end
 
+    # access or retrieve key_type, will also set access_mask if an automatic fetch is triggered
     def key_type
       @key_type ||= get_key_type
     end
 
+    # takes an account endpoint name and returns a response object, raises an APIKeyError if the request would fail
     def account(endpoint_name)
       raise EveBadger::APIKeyError, 'missing required key_id or vcode' unless @key_id && @vcode
       endpoint = EveBadger::Endpoints.account(endpoint_name.to_sym)
       api_request(endpoint)
     end
 
+    # takes a character endpoint name and returns a response object, raises an APIKeyError if the request would fail
     def character(endpoint_name)
       raise EveBadger::APIKeyError, 'missing required character_id key_id or_vcode' unless @character_id && @key_id && @vcode
       raise EveBadger::APIKeyError, 'wrong key type' unless [:Character, :Account].include?(key_type)
@@ -59,6 +68,7 @@ module EveBadger
       api_request(endpoint)
     end
 
+    # takes a corporation endpoint name and returns a response object, raises an APIKeyError if the request would fail
     def corporation(endpoint_name)
       raise EveBadger::APIKeyError, 'missing required character_id key_id or_vcode' unless @character_id && @key_id && @vcode
       raise EveBadger::APIKeyError, 'wrong key type' unless key_type == :Corporation
@@ -66,6 +76,7 @@ module EveBadger
       api_request(endpoint)
     end
 
+    # takes a detail endpoint name and id of interest then returns a response from the given endpoint name, raises an APIKeyError if the request would fail
     def details(endpoint_name, id_of_interest, fromid=nil, rowcount=nil)
       raise EveBadger::APIKeyError, 'wrong key type' unless [:Character, :Corporation, :Account].include?(key_type)
       endpoint = EveBadger::Endpoints.detail(endpoint_name.to_sym)
@@ -81,6 +92,7 @@ module EveBadger
     end
 
     private
+    # takes an endpoint hash and makes an api request to it, raises an APIKeyError if the request would fail
     def api_request(endpoint)
       if endpoint.access_mask.zero? or endpoint.permitted?(access_mask)
         get_response(build_uri(endpoint))
@@ -89,41 +101,49 @@ module EveBadger
       end
     end
 
+    # returns the access mask for a key and will retrieve it if not present
     def get_access_mask
       fetch_key_info unless @access_mask
       @access_mask
     end
 
+    # returns api key type as a symbol example: :Account, :Character, :Corporation
     def get_key_type
       fetch_key_info unless @key_type
       @key_type
     end
 
+    # sets @access_mask and @key_type from the public :api_key_info endpoint
     def fetch_key_info
       info = account(:api_key_info).result_as_json
       @access_mask = info['key']['@accessMask'].to_i
       @key_type = info['key']['@type'].to_sym
     end
 
+    # builds a uri string for a given endpoint
     def build_uri(endpoint)
       "#{@domain}#{endpoint.path}.xml.aspx#{params}"
     end
 
+    # builds the default params string for most requests
     def params
       "?keyID=#{@key_id}&vCode=#{@vcode}#{"&characterID=#{@character_id}" if @character_id}"
     end
 
+    # attempts to get a http response from the request cache first, then makes an http request if not found
     def get_response(uri)
       response = cache_get(uri) || http_get(uri)
       EveBadger::Response.new(response)
     end
 
+    # get an http response from the cache if is enabled, returns nil if expired or not found
     def cache_get(uri)
       if EveBadger::Cache.enabled?
         EveBadger::Cache.get(hash_of(uri))
       end
     end
 
+    # get a uri via http
     def http_get(uri)
       begin
         response = open(uri) { |res| res.read }
@@ -134,6 +154,7 @@ module EveBadger
       response || cache_get(uri)
     end
 
+    # store an http response in the cache if it is enabled
     def store_response(uri, response)
       if EveBadger::Cache.enabled?
         EveBadger::Cache.store(hash_of(uri), response, expires: cached_until(response))
@@ -145,6 +166,7 @@ module EveBadger
       Digest::SHA1.hexdigest(uri)
     end
 
+    # returns the number of seconds until the cachedUntil value in the xml response from the the API
     def cached_until(xml)
       noko = Nokogiri::XML xml
       seconds_until_expire = Time.parse(noko.xpath('//cachedUntil').text)

data/lib/eve_badger/response.rb

@@ -8,26 +8,27 @@ module EveBadger
       @content = content
     end
 
-    # returns json in badgerfish notation
+    # returns the response content as ruby hash representing badgerfish notation JSON
     def as_json
       Badgerfish::Parser.new.load(@content)
     end
 
-    # returns the response content as xml string
+    # returns the response content as raw XML which you can feed into your favorite parser
     def as_xml
       @content
     end
 
-    # same as #as_xml but truncates to just <result> data
+    # same as #as_xml, but only returns the content of the <result> tag
     def result_as_xml
       Nokogiri::XML(@content).xpath("//result/*").to_s
     end
 
-    # same as #as_json but truncates to just <result> data
+    # same as #as_json, but only returns the content of the <result> tag
     def result_as_json
       Badgerfish::Parser.new.load(@content)['eveapi']['result']
     end
 
+    # fetch any <error> tag in the document, helpful for api error checking
     def api_errors
       document = Nokogiri::XML(@content)
       document.xpath('//error')

data/lib/eve_badger/throttle.rb

@@ -2,24 +2,25 @@ require 'slowweb'
 
 module EveBadger
   module Throttle
+    # disable request throttling
     def self.disable
       SlowWeb.reset
     end
 
-    # enables the default rate limit of 30 requests per minute which ccp expects users to obey
+    # enables the default rate limit of 30 requests per second
     def self.enable_default
-      SlowWeb.limit(EveBadger.default_tq_domain, 30, 60)
-      SlowWeb.limit(EveBadger.default_sisi_domain, 30, 60)
+      SlowWeb.limit(EveBadger.default_tq_domain, 30, 1)
+      SlowWeb.limit(EveBadger.default_sisi_domain, 30, 1)
     end
 
-    #
-    def self.enable_custom(requests_per_minute)
+    # set a custom rate limit if ccp has granted your application an exception
+    def self.enable_custom(requests_per_second)
       SlowWeb.reset
-      SlowWeb.limit(EveBadger.default_tq_domain, requests_per_minute, 60)
-      SlowWeb.limit(EveBadger.default_sisi_domain, requests_per_minute, 60)
+      SlowWeb.limit(EveBadger.default_tq_domain, requests_per_second, 1)
+      SlowWeb.limit(EveBadger.default_sisi_domain, requests_per_second, 1)
     end
 
-
+    # test if request throttling is currently enabled
     def self.enabled?
      if SlowWeb.get_limit(EveBadger.default_tq_domain) || SlowWeb.get_limit(EveBadger.default_sisi_domain)
        true
@@ -28,4 +29,4 @@ module EveBadger
      end
     end
   end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eve_badger
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Corey Smedstad
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-15 00:00:00.000000000 Z
+date: 2015-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.7.0
+        version: '5.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.7.0
+        version: '5.7'
 - !ruby/object:Gem::Dependency
   name: load_path
   requirement: !ruby/object:Gem::Requirement