wikipedia_wrapper 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c55aa7e042f26d61832be539119c30a64667b8af
+  data.tar.gz: f1b62295f0e88b7ff14f329a3928da3b454e2142
+SHA512:
+  metadata.gz: 24d61ddd0a2191c023e773b81711ab6b189ca75a76a458f690383b39bd78fc4c0c72210a0a820ac04b03a8f2e58c0b63841dcdb78282c482e11829f776126a79
+  data.tar.gz: 5fe8f6a7995043e90d7e20a70d0a9b35cac96cb03ddf45202d87f0b8b210a32426093dd4a4b5c2a4b6f29b83a594d82b16fcb54030c065e7584c25819d9d5001

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Sybil Ehrensberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,101 @@
+# WikipediaWrapper
+WikipediaWrapper is a ruby gem that extracts information from Wikipedia and makes the information available in an easy-to-use API.
+
+All information is extracted using the [Wikipedia/MediaWiki API](https://en.wikipedia.org/w/api.php).
+
+This gem is inspired by the [Python wrapper for the Wikipedia API](https://github.com/goldsmith/Wikipedia) by [Jonathan Goldsmith](https://github.com/goldsmith).
+
+## Installation
+Install WikipediaWrapper like any other Ruby gem:
+
+```
+gem install wikipedia_wrapper
+```
+
+Or, if you're using Rails/Bundler, add this to your Gemfile:
+
+```
+gem 'wikipedia_wrapper'
+```
+
+and run at the command prompt:
+
+```
+bundle install
+```
+
+## Usage
+Before you can use the gem, you need to require it in your file:
+
+```ruby
+require 'wikipedia_wrapper'
+```
+
+The following are just some example usages. For detailed information, check the documentation.
+
+### Configuration
+To use this gem you do not need to specify configuration options, but you can. The values specified in the example below are the default values. It is however highly recommended that you choose a caching client and set that before making a lot of requests. The caching functionality is provided by the [cache gem](https://github.com/seamusabshere/cache). See it's documentation for more information on possible caching clients.
+
+```ruby
+WikipediaWrapper.configure do |config|
+  config.lang = 'en'
+  config.user_agent = 'WikipediaWrapper/0.0.1 (http://sykaeh.github.com/wikipedia_wrapper/) Ruby/2.2.1'
+  config.default_ttl = 604800
+  # additional config options are: image_restrictions, img_height, img_width
+end
+
+WikipediaWrapper.cache(Memcached.new('127.0.0.1:11211', :binary_protocol => true)) # or
+WikipediaWrapper.cache(Dalli::Client.new) # or
+WikipediaWrapper.cache(Redis.new) # or
+WikipediaWrapper.cache(Rails.cache)
+```
+
+### Autocomplete suggestions
+Autocomplete suggestions are the suggestions you get when you start typing a word in the search box on the page. You get the complete title for each page and a short summary. You can specify a limit with the keyword argument `limit` (default is 10).
+
+```ruby
+WikipediaWrapper.autocomplete('api', limit: 3)
+# returns => { "Application programming interface"=>"In computer programming, an application programming interface (API) is a set of routines, protocols, and tools for building software applications.",
+# "Apia"=>"Apia is the capital and the largest city of Samoa. From 1900 to 1919, it was the capital of the German Samoa.",
+# "Apink"=>"Apink (Korean: 에이핑크, Japanese: エーピンク; also written A Pink) is a South Korean girl group formed by A Cube Entertainment in 2011. The group consists of Park Cho-rong, Yoon Bo-mi, Jung Eun-ji, Son Na-eun, Kim Nam-joo and Oh Ha-young."}
+```
+
+### Search
+Search does a full-text search of the term you provided, and returns the list of page titles that match and short snippets containing the search term.
+
+```ruby
+WikipediaWrapper.search('api', limit: 3)
+# returns: => {"Application programming interface"=>""API In computer programming",
+# "Web API"=>"For the Microsoft ASP.NET Web API) for both the web server and web",
+# "Google Gadgets API"=>"Google Gadgets API which allows developers to create Google Gadgets easily.  Gadgets are mini-applications built in HTML, JavaScript,"}
+```
+
+### Summary
+Summary is a convenience function to get the first couple of character, sentences of all of the text before the first section (introductory text) either in plain text or as basic HTML markup.
+
+```ruby
+WikipediaWrapper.summary('Ruby') # returns the intro text in plaintext
+WikipediaWrapper.summary('Ruby', chars: 100) # returns the first 100 characters in plaintext
+WikipediaWrapper.summary('Ruby', sentences: 10) # returns the first 10 sentences in plaintext
+WikipediaWrapper.summary('Ruby', html: true) # returns the intro text in HTML
+```
+
+### Complete page
+To get all of the information on a particular page, use the `page` convenience wrapper or use the `Page` class directly.
+
+```ruby
+
+page = WikipediaWrapper.page('Ruby')
+# or directly:
+page = WikipediaWrapper::Page.new('Ruby')
+
+page.title # => "Ruby"
+page.url # => "http://en.wikipedia.org/wiki/Ruby"
+page.extract # => "<p>A <b>ruby</b> is a pink to blood-red colored gemstone, a variety of the mineral corundum (aluminium oxide). The red color is caused mainly by the presence of the element chromium. Its name comes from <i>ruber</i>, Latin for red. Other varieties of gem-quality corundum are called sapphires. Ruby is considered one of the four precious stones, together with sapphire, emerald and diamond.</p>\n<p>Prices of rubies are primarily determined by color. The brightest and most valuable \"red\" called blood-red, commands a large premium over other rubies of similar quality. After color follows clarity: similar to diamonds, a clear stone will command a premium, but a ruby without any needle-like rutile inclusions may indicate that the stone has been treated. Cut and carat (weight) are also an important factor in determining the price. Ruby is the traditional birthstone for July and is always lighter red or pink than garnet.</p>\n<p></p>"
+```
+
+## Tests
+WikipediaWrapper comes with a test suite (just run rake test).
+
+## License
+Copyright (c) 2015 Sybil Ehrensberger, released under the MIT license

data/lib/wikipedia_wrapper.rb

@@ -0,0 +1,216 @@
+require 'cache'
+require 'wikipedia_wrapper/util'
+require 'wikipedia_wrapper/exception'
+require 'wikipedia_wrapper/configuration'
+require 'wikipedia_wrapper/page'
+
+# @author Sybil Ehrensberger <contact@sybil-ehrensberger.com>
+module WikipediaWrapper
+
+  extend self
+
+  # @!attribute [r]
+  #   @return [WikipediaWrapper::Configuration] the configuration for this module
+  def config
+    @config ||= Configuration.new
+  end
+
+  # Set up configuration options
+  #
+  # @yieldparam config [WikipediaWrapper::Configuration] the configuration instance
+  # @example
+  #   WikipediaWrapper.configure do |config|
+  #     config.api_key = 'http://en.wikipedia.org/w/api.php'
+  #     config.user_agent = 'WikipediaWrapper/0.0.1 (http://sykaeh.github.com/wikipedia_wrapper/) Ruby/2.2.1'
+  #     config.default_ttl = 604800
+  #   end
+  def configure
+    @config ||= Configuration.new
+    yield(config)
+  end
+
+  # Retrieve the cache for this module if it is already defined, otherwise
+  # create a new Cache, defaulting to an in-memory cache
+  # @return [Cache] the cache
+  def cache
+    if @cache.nil?
+      @cache = Cache.new
+      @cache.config.default_ttl = config.default_ttl
+    end
+    @cache
+  end
+
+
+  # Define the caching client
+  # @example
+  #   WikipediaWrapper.cache(Memcached.new('127.0.0.1:11211', :binary_protocol => true))
+  #   WikipediaWrapper.cache(Dalli::Client.new)
+  #   WikipediaWrapper.cache(Redis.new)
+  #   WikipediaWrapper.cache(Rails.new)
+  # @see https://github.com/seamusabshere/cache Cache Gem Configuration
+  # @param raw_client [Memcached, Dalli::Client, Redis, memcache-client] a caching client (Memcached, Dalli, memcache-client, redis)
+  # @param timeout [Integer] default timeout for the cache entries [in seconds]
+  def cache=(raw_client, timeout: config.default_ttl)
+    @cache = Cache.wrap(raw_client)
+    @cache.config.default_ttl = timeout
+  end
+
+
+  # Convenience function to retrieve a Wikipedia page
+  #
+  # @param term [String] the title of the page
+  # @param auto_suggest [Boolean] whether the search and autocorrect suggestion should be used to find a valid term (default: true)
+  # @param redirect [Boolean] whether redirects should be followed automatically (default: true)
+  # @return [WikipediaWrapper::Page] the wiki page
+  def page(term, auto_suggest: true, redirect: true)
+
+    if auto_suggest
+      term = check_page(term)
+    end
+
+    return WikipediaWrapper::Page.new(term, redirect: redirect)
+
+  end
+
+  # Plain text or basic HTML summary of the page. Redirects are always followed
+  # automatically.
+  #
+  # @note This is a convenience wrapper - auto_suggest and redirect are enabled by default
+  #
+  # @raise [WikipediaWrapper::PageError] if no page with that term was found
+  # @raise [WikipediaWrapper::MultiplePagesError] if more than one page with that term was found
+  # @param term [String] the title of the page
+  # @param html [Boolean] if true, return basic HTML instead of plain text
+  # @param sentences [Integer] if set, return the first `sentences` sentences (can be no greater than 10).
+  # @param chars [Integer] if set, return only the first `chars` characters (actual text returned may be slightly longer).
+  # @return [String] the plain text or basic HTML summary of that page
+  def summary(term, html: false, sentences: 0, chars: 0)
+
+    # get auto_suggest
+    term = check_page(term)
+
+    query_params = {
+      'redirects': '',
+      'prop': 'extracts|pageprops',
+      'titles': term,
+      'ppprop': 'disambiguation',
+    }
+
+    if !html
+      query_params['explaintext'] = ''
+    end
+
+    if sentences
+      query_params[:exsentences] = (sentences > 10 ? 10 : sentences).to_s
+    elsif chars
+      query_params[:exchars] = chars.to_s
+    else
+      query_params[:exintro] = ''
+    end
+
+    raw_results = fetch(query_params)
+    check_results(term, raw_results)
+
+    id, info = raw_results['query']['pages'].first
+    summary = info['extract']
+
+    return summary
+  end
+
+
+  # Do a Wikipedia search for the given term
+  #
+  # @param limit [Integer] the maximimum number of results returned
+  # @param suggestion [Boolean] set to true if you want an autocorrect suggestion
+  # @return [{String => String}] if suggestion is false, return a Hash of the suggestions
+  #   (as keys) and a snippet of the search result as values
+  # @return [Array<{String => String}, <String, nil>>] if suggestion is true,
+  #   return return a Hash of the suggestions
+  #   (as keys) and a snippet of the search result as values in the first position of
+  #   the array and in the second position a proposed suggestion or nil if there
+  #   was no suggestion
+  def search(term, limit: 10, suggestion: false)
+
+    search_params = {
+      'list': 'search',
+      'srprop': 'snippet',
+      'srlimit': limit.to_s,
+      'srsearch': term
+    }
+
+    raw_results = fetch(search_params)
+
+    results = {}
+
+    raw_results['query']['search'].each do |sr|
+      results[sr['title']] = sr['snippet'].gsub(/<span .*>(?<term>[^<]*)<\/span>/, '\k<term>')
+    end
+
+    if suggestion
+      s = raw_results['query']['searchinfo'].key?('suggestion') ? raw_results['query']['searchinfo']['suggestion'] : nil
+      return [results, s]
+    else
+      return results
+    end
+
+  end
+
+  # Get an autocomplete suggestions for the given term. The term will be used
+  # as a prefix.
+
+  # @see https://www.mediawiki.org/wiki/API:Opensearch MediaWiki API
+  # @raise [WikipediaWrapper::FormatError] if an unknown format is encountered in the response
+  # @param term [String] the term to get the autocompletions for (used as a prefix)
+  # @param limit [Integer]  the maximum number of results to return (may not exceed 100)
+  # @param redirect [Boolean] whether redirects should be followed for suggestions
+  # @return [Hash{String=>String}] a hash where the keys are the titles of the articles and
+  #   the values are a short description of the page
+  def autocomplete(term, limit: 10, redirect: true)
+
+    query_params = {
+      'action': 'opensearch',
+      'search': term,
+      'redirects': redirect ? 'resolve' : 'return',
+      'limit': (limit > 100 ? 100 : limit).to_s
+    }
+
+    raw_results = fetch(query_params)
+
+    if raw_results.length != 4
+      raise WikipediaWrapper::FormatError.new("autocomplete", "array had length of #{raw_results.length} instead of 4")
+    end
+
+    num_suggestions = raw_results[1].length - 1
+
+    results = {}
+    for i in 0..num_suggestions
+      results[raw_results[1][i]] = raw_results[2][i]
+    end
+
+    return results
+
+  end
+
+
+  # Function to determine whether there is a page with that term. It uses
+  # the search and suggestion functionality to find a possible match
+  # and raises a PageError if no page could be found.
+  #
+  # @raise [WikipediaWrapper::PageError] if no page with that term could be found
+  # @param term [String] the term for which we want a page
+  # @return [String] the actual title of the page
+  def check_page(term)
+
+    results, suggestion = search(term, limit: 1, suggestion: true)
+    if !suggestion.nil?
+      return suggestion
+    elsif results.length == 1
+      title, snippet = results.first
+      return title
+    else
+      raise WikipediaWrapper::PageError.new(term)
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/configuration.rb

@@ -0,0 +1,104 @@
+require 'yaml'
+
+module WikipediaWrapper
+
+  class Configuration
+    attr_accessor :lang, :user_agent, :default_ttl, :img_width, :img_height
+    attr_reader :api_url
+
+    # Initialize the configuration with some sensible defaults
+    def initialize
+      set_defaults
+    end
+
+    # Reset the configuration to the initial state with the default parameters
+    def reset
+      set_defaults
+      @image_restrictions = nil
+    end
+
+    def lang=(lang_code)
+      @lang = lang_code
+      @api_url = "https://#{@lang}.wikipedia.org/w/api.php"
+    end
+
+    def image_restrictions
+      if @image_restrictions.nil?
+        self.image_restrictions = File.expand_path(File.dirname(__FILE__)) + '/default_image_restrictions.yaml'
+      end
+      @image_restrictions
+    end
+
+    def image_restrictions=(path)
+      begin
+        @image_restrictions = YAML.load_file(path)
+      rescue Errno::ENOENT # No such file
+        raise WikipediaWrapper::ConfigurationError.new("The file #{path} does not exist")
+      rescue Psych::SyntaxError => e
+        raise WikipediaWrapper::ConfigurationError.new("SyntaxError in the file #{path}: #{e}")
+      end
+    end
+
+    def image_allowed?(filename)
+      allowed_ending?(filename) && !blocked_filename?(filename) && !blocked_partial?(filename)
+    end
+
+    private
+
+    def set_defaults
+      self.lang = 'en'
+      @user_agent = 'WikipediaWrapper/0.1 (http://sykaeh.github.com/wikipedia_wrapper/; wikipedia_wrapper@sybil-ehrensberger.com) Ruby/2.2.1'
+      @default_ttl = 7*24*60*60
+      @img_height = nil
+      @img_width = nil
+    end
+
+    def allowed_ending?(filename)
+      if self.image_restrictions['allowed_endings'].nil? # if there are no allowed_endings
+        if self.image_restrictions['exclude_endings'].nil?
+          return true
+        end
+
+        self.image_restrictions['exclude_endings'].each do |e|
+          if filename.downcase.end_with?(e.downcase)
+            return false
+          end
+        end
+        return true
+      else # if allowed_endings is specified
+        self.image_restrictions['allowed_endings'].each do |e|
+          if filename.downcase.end_with?(e.downcase)
+            return true
+          end
+        end
+        return false
+      end
+    end
+
+    def blocked_partial?(filename)
+
+      if self.image_restrictions['exclude_partials'].nil?
+        return false
+      end
+
+      self.image_restrictions['exclude_partials'].each do |p|
+        if filename.downcase.include? p.downcase
+          return true
+        end
+      end
+
+      return false
+    end
+
+    def blocked_filename?(filename)
+
+      if self.image_restrictions['exclude_files'].nil?
+        false
+      else
+        self.image_restrictions['exclude_files'].include? filename
+      end
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/default_image_restrictions.yaml

@@ -0,0 +1,27 @@
+---
+  allowed_endings: # leave blank to allow all endings
+    - .png
+    - .jpeg
+    - .jpg
+
+  exclude_endings: # is only considered if allowed_endings is blank
+    - .ogg
+
+  exclude_files:
+    - File:Commons-logo.svg
+    - File:Wiktionary-logo-en.svg
+    - File:Edit-clear.svg
+    - File:Disambig gray.svg
+
+  exclude_partials:
+    - arms
+    - blason
+    - icon
+    - wappen
+    - projection
+    - bandera
+    - flag
+    - map
+    - arms
+    - karte
+    - coa

data/lib/wikipedia_wrapper/exception.rb

@@ -0,0 +1,142 @@
+
+module WikipediaWrapper
+
+  # Base Wikipedia error class
+  class WikipediaError < StandardError
+
+    def initialize(error)
+      @error = error
+    end
+
+    def message
+      "An unexpected error occured: \"#{@error}\". Please report it on GitHub (github.com/sykaeh/wikipedia_wrapper)!"
+    end
+
+  end
+
+  # Exception raised when there is a problem with the configuration
+  class ConfigurationError < WikipediaError
+
+    def initialize(msg)
+      @msg = msg
+    end
+
+    def message
+      "#{@msg}"
+    end
+
+  end
+
+  # Exception raised when the expected return format does not match what was received
+  class FormatError < WikipediaError
+
+    def initialize(function, msg)
+      @func = function
+      @msg = msg
+    end
+
+    def message
+      "Format Error calling \"#{@func}\": #{@msg}"
+    end
+
+  end
+
+  # Exception raised when no Wikipedia matched a query.
+  class PageError < WikipediaError
+
+    def initialize(term, pageid: false)
+      @pageid = pageid
+      @term = term
+    end
+
+    def message
+      if @pageid
+        "Page id \"#{@term}\" does not match any pages. Try another id!"
+      else
+        "\"#{@term}\" does not match any pages. Try another query!"
+      end
+    end
+
+  end
+
+  # Exception raised when more than one Wikipedia article matched a query.
+  class MultiplePagesError < WikipediaError
+
+    def initialize(page_titles, term, pageid: false)
+      @pages = page_titles
+      @pageid = pageid
+      @term = term
+    end
+
+    def message
+      if @pageid
+        "Page id \"#{@term}\" matches #{@pages.length} pages: \n#{@pages.join(', ')}"
+      else
+        "\"#{@term}\" matches #{@pages.length} pages: \n#{@pages.join(', ')}"
+      end
+    end
+
+  end
+
+  # Exception raised when the request is invalid and the server replies with an error
+  class InvalidRequestError < WikipediaError
+
+    def initialize(url, msg)
+      @url = url
+      @msg = msg
+    end
+
+    def message
+      "Invalid Request for URL #{@url}: #{@msg}"
+    end
+
+  end
+
+
+
+  # Exception raised when a page resolves to a Disambiguation page.
+  #
+  # The `options` property contains a list of titles
+  # of Wikipedia pages that the query may refer to.
+  #
+  # @note `options` does not include titles that do not link to a valid Wikipedia page.
+  class DisambiguationError < WikipediaError
+
+    def initialize(title)
+      @title = title
+    end
+
+    def message
+      "\"#{@title}\" may refer to several different things."
+    end
+
+  end
+
+
+  # Exception raised when a page title unexpectedly resolves to a redirect.
+  class RedirectError < WikipediaError
+
+    def initialize(title)
+      @title = title
+    end
+
+    def message
+      "\"#{@title}\" resulted in a redirect. Set the redirect property to True to allow automatic redirects."
+    end
+
+  end
+
+  # Exception raised when a request to the Mediawiki servers times out.
+  class HTTPTimeoutError < WikipediaError
+
+    def initialize(query)
+      @query = query
+    end
+
+    def message
+      "Searching for \"#{@query}\" resulted in a timeout. Try again in a few seconds, and make sure you have rate limiting set to True."
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/image.rb

@@ -0,0 +1,69 @@
+require 'wikipedia_wrapper/exception'
+
+module WikipediaWrapper
+
+  class WikiImage
+
+    attr_accessor :small, :normal, :description_url
+
+    def initialize(raw_info)
+
+      @small = nil
+      @normal = nil
+
+      if !raw_info.key?('imageinfo') || raw_info['imageinfo'].length != 1
+        raise WikipediaWrapper::FormatError.new('WikiImage initialize', "Unknown format for imageinfo: #{raw_info}")
+      end
+
+      @filename = (raw_info.key? 'title') ? raw_info['title'].sub('File:', '') : 'No name'
+
+      data = {
+        'name': @filename,
+        'mime': raw_info['imageinfo'][0]['mime'],
+      }
+
+      @description_url = raw_info['imageinfo'][0]['descriptionurl']
+
+      @normal = Image.new(raw_info['imageinfo'][0]['url'],
+                         raw_info['imageinfo'][0]['width'].to_i,
+                         raw_info['imageinfo'][0]['height'].to_i, data)
+
+
+      if raw_info['imageinfo'][0].key? ('thumburl')
+        @small = Image.new(raw_info['imageinfo'][0]['thumburl'],
+                                 raw_info['imageinfo'][0]['thumbwidth'].to_i,
+                                 raw_info['imageinfo'][0]['thumbheight'].to_i,
+                                 data)
+      else
+        @small = @normal
+      end
+
+    end
+
+    def to_s
+      "WikiImage #{@filename}"
+    end
+
+  end
+
+  class Image
+
+    attr_reader :name, :url, :width, :height, :mime # makes attributes readable
+
+    def initialize(url, width, height, data)
+
+      @url = url
+      @name = data[:name] || ''
+      @mime = data[:mime] || ''
+      @height = data[:height] || 0
+      @width = data[:width] || 0
+
+    end
+
+    def to_s
+      "Image: #{@name} (#{@url})"
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/page.rb

@@ -0,0 +1,135 @@
+require 'wikipedia_wrapper/exception'
+require 'wikipedia_wrapper/image'
+require 'wikipedia_wrapper/util'
+
+module WikipediaWrapper
+
+  class Page
+
+    attr_reader :title, :revision_time, :url, :extract
+
+    def initialize(term, redirect: true)
+
+      @term = term
+      @redirect = redirect
+      @images = nil
+      @img_width = WikipediaWrapper.config.img_width
+      @img_height = WikipediaWrapper.config.img_height
+
+      # FIXME: Deal with continuation
+
+      # FIXME: deal with redirect false!
+      load_page
+
+    end
+
+    def to_s
+      "Wikipedia Page: #{@title} (#{@url}), revid: #{@revision_id}, revtime: #{@revision_time}"
+    end
+
+    def categories
+      # FIXME: Implement!
+    end
+
+    # Retrieve image info for all given image filenames, except for the images in the whitelist
+    # See {http://www.mediawiki.org/wiki/API:Imageinfo}
+    #
+    # @param width [Integer] optional width of the smaller image (in px)
+    # @param height [Integer] optional height of the smaller image (in px)
+    # @note Only one of width and height can be used at the same time. If both are defined, only width is used.
+    # @return [Array<WikipediaWrapper::WikiImage>] list of images
+    def images(width: nil, height: nil)
+
+      # if we haven't retrieved any images or the width or height have changed, re-fetch
+      if @images.nil? || (!width.nil? && @img_width != width) || (!width.nil? && @img_width != width)
+
+        unless width.nil?
+          @img_width = width
+        end
+
+        unless height.nil?
+          @img_height = height
+        end
+
+        @images = []
+
+        # deal with the case that a page has no images
+        if @raw['images'].nil?
+          return @images
+        end
+
+        filenames = @raw['images'].map {|img_info| img_info['title']}.compact
+
+        if filenames.empty? # there are no filenames, return an empty array
+          return @images
+        end
+
+        # exclude whitelisted filenames
+        filenames = filenames.map { |f| WikipediaWrapper.config.image_allowed?(f) ? f : nil }.compact
+
+        query_parameters = {
+          'titles': filenames.join('|'),
+          'redirects': '',
+          'prop': 'imageinfo',
+          'iiprop': 'url|size|mime',
+        }
+
+        if (!@img_width.nil?)
+          query_parameters[:iiurlwidth] = @img_width.to_s
+        elsif (!@img_height.nil?)
+          query_parameters[:iiurlheight] = @img_height.to_s
+        end
+
+        raw_results = WikipediaWrapper.fetch(query_parameters)
+
+        # check if the proper format is there
+        if raw_results.key?('query') && raw_results['query'].key?('pages')
+          raw_results['query']['pages'].each do |k, main_info|
+            begin
+              wi = WikiImage.new(main_info)
+              @images.push(wi)
+            rescue WikipediaWrapper::FormatError => e
+              puts e.message
+            end
+          end
+        end
+
+      end
+
+      return @images
+
+    end
+
+
+    private
+
+    def load_page
+
+      query_parameters = {
+        'prop': 'revisions|info|extracts|images|pageprops',
+        'titles': @term,
+        'redirects': '',
+        'rvprop': 'content',
+        'inprop': 'url',
+        'exintro': '',
+        'ppprop': 'disambiguation',
+      }
+
+      raw_results = WikipediaWrapper.fetch(query_parameters)
+      WikipediaWrapper.check_results(@term, raw_results)
+
+      key, page_info = raw_results['query']['pages'].first
+      @raw = page_info
+
+      @page_id = page_info['pageid']
+      @title = page_info['title']
+      @revision_time = page_info['touched'] #FIXME: parse in to date & time, format: 2015-04-23T07:20:47Z
+      @revision_id = page_info['lastrevid']
+      @url = page_info['fullurl']
+      @extract = (page_info.key? 'extract') ? page_info['extract'] : ''
+
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/util.rb

@@ -0,0 +1,66 @@
+require 'uri'
+require 'open-uri'
+require 'json'
+require 'wikipedia_wrapper/exception'
+
+
+module WikipediaWrapper
+
+
+  # Given the request parameters, params, fetch the response from the API URL
+  # and parse it as JSON. Raise an InvalidRequestError if an error occurrs.
+  #
+  # @raise [WikipediaWrapper::InvalidRequestError] if the request was invalid
+  #   or another error occurrs
+  # @param params [Hash{Symbol => String}] hash of the properties that should
+  #   be added to the request URL
+  # @return [Hash] the JSON response of the server converted in to a hash
+  def self.fetch(params)
+
+    # if no action is defined, set it to 'query'
+    if !params.key?(:action)
+      params[:action] = 'query'
+    end
+
+    params[:format] = 'json' # always return json format
+
+    # FIXME: deal with continuation
+    #params[:continue] = '' # does not work for autocomplete
+
+    query_part = params.map { |k, v| v.empty? ? "#{k}" : "#{k}=#{v}" }.join("&")
+    endpoint_url = URI.encode("#{WikipediaWrapper.config.api_url}?#{query_part}")
+
+    raw_results = cache.fetch(endpoint_url) {
+      f = open(endpoint_url, "User-Agent" => config.user_agent)
+      JSON.parse(f.read)
+    }
+
+    if params[:action] != 'opensearch' && raw_results.key?('error')
+      raise WikipediaWrapper::InvalidRequestError.new(endpoint_url, raw_results['error']['info'])
+    end
+
+    return raw_results
+
+  end
+
+  def self.check_results(term, raw_results)
+
+    if raw_results['query']['pages'].length > 1
+      raise WikipediaWrapper::MultiplePagesError.new(raw_results['query']['pages'].map { |p| p['title'] }, term)
+    elsif raw_results['query']['pages'].length < 1
+      raise WikipediaWrapper::PageError.new(term)
+    end
+
+    key, page_info = raw_results['query']['pages'].first
+    if key == '-1'
+      raise WikipediaWrapper::PageError.new(term)
+    end
+
+    # Check for disambiguation pages
+    if page_info['pageprops'] && page_info['pageprops']['disambiguation']
+      raise WikipediaWrapper::DisambiguationError.new(term)
+    end
+
+  end
+
+end

data/lib/wikipedia_wrapper/version.rb

@@ -0,0 +1,3 @@
+module WikipediaWrapper
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: wikipedia_wrapper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sybil Ehrensberger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-07-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: WikipediaWrapper is a ruby gem that extracts information from Wikipedia
+  and makes the information available in an easy-to-use API. All information is extracted
+  using the Wikipedia/MediaWiki API.
+email: contact@sybil-ehrensberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/wikipedia_wrapper.rb
+- lib/wikipedia_wrapper/configuration.rb
+- lib/wikipedia_wrapper/default_image_restrictions.yaml
+- lib/wikipedia_wrapper/exception.rb
+- lib/wikipedia_wrapper/image.rb
+- lib/wikipedia_wrapper/page.rb
+- lib/wikipedia_wrapper/util.rb
+- lib/wikipedia_wrapper/version.rb
+homepage: http://sybil-ehrensberger.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: WikipediaWrapper retrieves information about a place from Wikipedia
+test_files: []