metal_archives 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 07ba21e5ea2f91a35d841543732f2cad9faf3943
+  data.tar.gz: fd48c5f0ae010184778ed9d6137004684beb1c64
+SHA512:
+  metadata.gz: ed2595557edfcb18ff9d74822039e6d8d846e9d9348ba73ffd41dd1d4bc8d06dddd48472ab833c2afd17cd120b3cd4e63c1ddb7f081a780a95b87c8bb4279149
+  data.tar.gz: 87d80f9d69daa76339513028aba3c6d0179b130847c9e1314ce40c9fe7a1a8f993370dd488e424fb1734bde1dc0fff48cce0540595e5fc8d546059803b01f638

data/.gitignore

@@ -0,0 +1,11 @@
+# Ruby version
+.ruby-version
+.ruby-gemset
+
+# Temp files
+.byebug_history
+
+# RDoc
+html/
+
+Gemfile.lock

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,88 @@
+# Metal Archives Web Service Wrapper
+
+## Installation
+
+```shell
+$ gem install metal_archives
+```
+
+or add it to your Gemfile
+
+```ruby
+gem 'metal_archives'
+```
+
+```shell
+$ bundle install
+```
+
+## Configuration
+
+```ruby
+require 'active_support/cache'
+
+MetalArchives.configure do |c|
+  # Application identity (required)
+  c.app_name = "My App"
+  c.app_version = "1.0"
+  c.app_contact = "support@mymusicapp.com"
+
+  # Cache config (optional)
+  c.enable_cache = true
+  c.cache_store = ActiveSupport::Cache.lookup_store(:file_store, '/tmp/metal_archives-cache')
+
+  # Request throttling (optional, overrides defaults)
+  c.request_rate = 1
+  c.request_timeout = 3
+
+  # Print debugging information
+  c.debug = false
+end
+```
+
+## Usage
+
+```ruby
+require 'metal_archives'
+
+# Search for bands
+@alquimia_list = MetalArchives::Band.search('Alquimia')
+
+# Find bands by name
+@iron_maiden = MetalArchives::Band.find_by(:name => 'Iron Maiden')
+
+# Find bands by attributes
+require 'countries'
+
+@bands_in_belgium = MetalArchives::Band.search_by :country => ISO3166::Country['BE']
+@bands_formed_in_1990 = MetalArchives::Band.search_by :year => Range.new(Date.new(1990))
+
+# Metal Archives' usual tips apply
+
+@bands_containing_hell = MetalArchives::Band.search_by :name => '*hell*'
+@non_melodic_death_bands = MetalArchives::Band.search_by :genre => 'death -melodic'
+```
+
+Refer to the model's RDoc documentation for full documentation.
+
+## Debugging
+
+Turn on `debug` in the configuration block to enable logging HTTP requests and responses.
+
+```
+$ irb -r metal_archives
+```
+
+## Testing
+```
+$ bundle exec rake test
+```
+
+## Documentation
+```
+$ bundle exec rake rdoc
+```
+
+## Copyright
+
+Copyright 2016 Florian Dejonckheere. See `LICENSE` for further details.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*/*_test.rb']
+  t.verbose = true
+end
+
+require 'rdoc/task'
+RDoc::Task.new do |rdoc|
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("README.md", "lib/**/*.rb")
+end

data/lib/metal_archives.rb

@@ -0,0 +1,22 @@
+require 'metal_archives/version'
+require 'metal_archives/configuration'
+require 'metal_archives/error'
+
+require 'metal_archives/models/base_model'
+require 'metal_archives/models/range'
+require 'metal_archives/models/label'
+require 'metal_archives/models/artist'
+require 'metal_archives/models/band'
+
+require 'metal_archives/parsers/parser_helper'
+require 'metal_archives/parsers/label'
+require 'metal_archives/parsers/artist'
+require 'metal_archives/parsers/band'
+
+require 'metal_archives/http_client'
+
+##
+# Metal Archives Ruby API
+#
+module MetalArchives
+end

data/lib/metal_archives/configuration.rb

@@ -0,0 +1,81 @@
+module MetalArchives
+  class << self
+    ##
+    # API configuration
+    #
+    # Instance of rdoc-ref:MetalArchives::Configuration
+    #
+    attr_accessor :config
+
+    ##
+    # Configure API options.
+    #
+    # A block must be specified, to which a
+    # rdoc-ref:MetalArchives::Configuration parameter will be passed.
+    #
+    # Raises rdoc-ref:InvalidConfigurationException
+    #
+    def configure
+      raise MetalArchives::Errors::InvalidConfigurationError, 'No configuration block given' unless block_given?
+      yield MetalArchives.config ||= MetalArchives::Configuration.new
+
+      raise MetalArchives::Errors::InvalidConfigurationError, 'app_name has not been configured' unless MetalArchives.config.app_name and not MetalArchives.config.app_name.empty?
+      raise MetalArchives::Errors::InvalidConfigurationError, 'app_version has not been configured' unless MetalArchives.config.app_version and not MetalArchives.config.app_version.empty?
+      raise MetalArchives::Errors::InvalidConfigurationError, 'app_contact has not been configured' unless MetalArchives.config.app_contact and not MetalArchives.config.app_contact.empty?
+
+    end
+  end
+
+  ##
+  # Contains configuration options
+  #
+  class Configuration
+    ##
+    # *Required.* Application name (used in request header)
+    #
+    attr_accessor :app_name
+
+    ##
+    # *Required.* Application version (used in request header)
+    #
+    attr_accessor :app_version
+
+    ##
+    # *Required.* Application contact email (used in request header)
+    #
+    attr_accessor :app_contact
+
+    ##
+    # Whether to enable the cache
+    #
+    attr_accessor :enable_cache
+
+    ##
+    # ActiveSupport::Cache compatible store
+    #
+    attr_accessor :cache_store
+
+    ##
+    # Request throttling rate (in seconds per request per path)
+    #
+    attr_accessor :request_rate
+
+    ##
+    # Request timeout (in seconds per request per path)
+    #
+    attr_accessor :request_timeout
+
+    ##
+    # Print debug information
+    #
+    attr_accessor :debug
+
+    ##
+    # Default configuration values
+    #
+    def initialize
+      @throttle_rate = 1
+      @throttle_wait = 3
+    end
+  end
+end

data/lib/metal_archives/error.rb

@@ -0,0 +1,35 @@
+module MetalArchives
+##
+# MetalArchives gem specific errors
+#
+module Errors
+  ##
+  # Generic error
+  #
+  class Error < StandardError; end
+
+  ##
+  # Error in data
+  #
+  class DataError < Error; end
+
+  ##
+  # No or invalid configuration found
+  #
+  class InvalidConfigurationError < Error; end
+
+  ##
+  # Error parsing value
+  #
+  class ParserError < Error; end
+
+  ##
+  # Functionality not implemented (yet)
+  class NotImplementedError < Error; end
+
+  ##
+  # Error in backend response
+  #
+  class APIError < Error; end
+end
+end

data/lib/metal_archives/http_client.rb

@@ -0,0 +1,75 @@
+require 'faraday'
+require 'faraday-http-cache'
+require 'faraday_throttler'
+
+module MetalArchives
+  ##
+  # HTTP request client
+  #
+  class HTTPClient # :nodoc:
+    class << self
+
+      ##
+      # Retrieve a HTTP resource
+      #
+      def get(*params)
+        response = client.get *params
+
+        raise Errors::APIError, response.status if response.status >= 400
+
+        response
+      rescue Faraday::Error::ClientError => e
+        raise Errors::APIError, e
+      end
+
+      private
+        ##
+        # Retrieve a HTTP client
+        #
+        def client
+          raise Errors::InvalidConfigurationError, 'Not configured yet' unless MetalArchives.config
+
+          @faraday ||= Faraday.new do |f|
+            f.request   :url_encoded            # form-encode POST params
+            f.response  :logger if !!MetalArchives.config.debug      # log requests to STDOUT
+
+            f.use       MetalArchives::Middleware
+            f.use       Faraday::HttpCache,
+                                        :store => MetalArchives.config.cache_store if !!MetalArchives.config.enable_cache
+            f.use       :throttler,
+                                :rate => MetalArchives.config.request_rate,
+                                :wait => MetalArchives.config.request_timeout
+
+            f.adapter   Faraday.default_adapter
+          end
+        end
+    end
+  end
+
+  ##
+  # Faraday middleware
+  #
+  class Middleware < Faraday::Middleware # :nodoc:
+    def call(env)
+      env[:request_headers].merge!(
+        'User-Agent'  => user_agent_string,
+        'Via'         => via_string,
+        'Accept'      => accept_string
+      )
+      @app.call(env)
+    end
+
+    private
+      def user_agent_string
+        "#{MetalArchives.config.app_name}/#{MetalArchives.config.app_version} ( #{MetalArchives.config.app_contact} )"
+      end
+
+      def accept_string
+        'application/json'
+      end
+
+      def via_string
+        "gem metal_archives/#{VERSION}"
+      end
+  end
+end

data/lib/metal_archives/models/artist.rb

@@ -0,0 +1,216 @@
+require 'date'
+require 'countries'
+
+module MetalArchives
+
+  ##
+  # Represents a single performer (but not a solo artist)
+  #
+  class Artist < BaseModel
+    ##
+    # :attr_reader: id
+    #
+    # Returns +Integer+
+    #
+    property :id, :type => Integer
+
+    ##
+    # :attr_reader: name
+    #
+    # Returns +String+
+    #
+    property :name
+
+    ##
+    # :attr_reader: aliases
+    #
+    # Returns +Array+ of +String+
+    #
+    property :aliases, :multiple => true
+
+    ##
+    # :attr_reader: country
+    #
+    # Returns +ISO3166::Country+
+    #
+    property :country, :type => ISO3166::Country
+
+    ##
+    # :attr_reader: location
+    #
+    # Returns +String+
+    #
+    property :location
+
+    ##
+    # :attr_reader: date_of_birth
+    #
+    # Returns +Date+
+    #
+    property :date_of_birth, :type => Date
+
+    ##
+    # :attr_reader: date_of_death
+    #
+    # Returns +Date+
+    #
+    property :date_of_death, :type => Date
+
+    ##
+    # :attr_reader: cause_of_death
+    #
+    # Returns +String+
+    #
+    property :cause_of_death
+
+    ##
+    # :attr_reader: gender
+    #
+    # Returns +Symbol+, either +:male+ or +:female+
+    #
+    enum :gender, :values => [:male, :female]
+
+    ##
+    # :attr_reader: biography
+    #
+    # Returns raw HTML +String+
+    #
+    property :biography
+
+    ##
+    # :attr_reader: trivia
+    #
+    # Returns raw HTML +String+
+    #
+    property :trivia
+
+    ##
+    # :attr_reader: links
+    #
+    # Returns +Array+ of +Hash+ containing the following keys
+    #
+    # [+similar+]
+    #     - +:url+: +String+
+    #     - +:type+: +Symbol+, either +:official+, +:unofficial+ or +:unlisted_bands+
+    #     - +:title+: +String+
+    #
+    property :links, :multiple => true
+
+    # TODO: active bands/albums
+    # TODO: past bands/albums
+    # TODO: guest bands/albums
+    # TODO: misc bands/albums
+
+    protected
+      ##
+      # Fetch the data and assemble the model
+      #
+      # Raises rdoc-ref:MetalArchives::Errors::APIError
+      #
+      def assemble # :nodoc:
+        ## Base attributes
+        url = "http://www.metal-archives.com/artist/view/id/#{id}"
+        response = HTTPClient.get url
+
+        properties = Parsers::Artist.parse_html response.body
+
+        ## Biography
+        url = "http://www.metal-archives.com/artist/read-more/id/#{id}/field/biography"
+        response = HTTPClient.get url
+
+        properties[:biography] = response.body
+
+        ## Trivia
+        url = "http://www.metal-archives.com/artist/read-more/id/#{id}/field/trivia"
+        response = HTTPClient.get url
+
+        properties[:trivia] = response.body
+
+        ## Related links
+        url = "http://www.metal-archives.com/link/ajax-list/type/person/id/#{id}"
+        response = HTTPClient.get url
+
+        properties[:links] = Parsers::Artist.parse_links_html response.body
+
+        ## Use constructor to fill properties
+        initialize properties
+      end
+
+    class << self
+      ##
+      # Find by ID
+      #
+      # Returns rdoc-ref:Artist, even when ID is invalid (because the data is lazily fetched)
+      #
+      # [+id+]
+      #     +Integer+
+      #
+      def find(id)
+        Artist.new :id => id
+      end
+
+      ##
+      # Find by attributes
+      #
+      # Returns rdoc-ref:Artist or nil when ID is invalid
+      #
+      # [+query+]
+      #     Hash containing one or more of the following keys:
+      #     - +:name+: +String+
+      #
+      def find_by(query)
+        url = 'http://www.metal-archives.com/search/ajax-artist-search/'
+        params = Parsers::Artist.map_params query
+
+        response = HTTPClient.get url, params
+        json = JSON.parse response.body
+
+        return nil if json['aaData'].empty?
+
+        data = json['aaData'].first
+        id = Nokogiri::HTML(data.first).xpath('//a/@href').first.value.gsub('\\', '').split('/').last.gsub(/\D/, '').to_i
+
+        Artist.new :id => id
+      rescue Errors::APIError
+        nil
+      end
+
+      ##
+      # Search by name
+      #
+      # Returns (possibly empty) +Array+ of rdoc-ref:Artist
+      #
+      # [+name+]
+      #     +String+
+      #
+      def search(name)
+        objects = []
+
+        url = 'http://www.metal-archives.com/search/ajax-artist-search/'
+        query = {
+          :name => name,
+          :iDisplayStart => 0
+        }
+
+        loop do
+          params = Parsers::Artist.map_params query
+
+          response = HTTPClient.get url, params
+          json = JSON.parse response.body
+
+          json['aaData'].each do |data|
+            # Create Artist object for every ID in the results list
+            id = Nokogiri::HTML(data.first).xpath('//a/@href').first.value.gsub('\\', '').split('/').last.gsub(/\D/, '').to_i
+            objects << Artist.new(:id => id)
+          end
+
+          break if objects.length == json['iTotalRecords']
+
+          query[:iDisplayStart] += 200
+        end
+
+        objects
+      end
+    end
+  end
+end