gimme_wikidata 0.4.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 751f0e5c9d5d79ec200fa83d215aeaa247349c28
+  data.tar.gz: 64413f1af54686da1a196cb37b760cfb886ec7ef
+SHA512:
+  metadata.gz: e5167aa38e3ee801094c52389687ec687e4338bcbdb6d018f9a1f2d85fe417fc9b9e14d21756bfbfcb0fa2248e03bc6da2f042b7d8964726e826c4343e573aac
+  data.tar.gz: d81f1e387305fb803d35d7c9929e2ef4505bbd2ecceb5841e0bc8270a32344980ce924b5c694a1d53b0260d4ddd9b02f0fab555f1203aaf21efbe7ec696f5d56

data/.gitignore

@@ -0,0 +1,18 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/Gemfile.lock
+/pkg/
+/spec/reports/
+/tmp/
+
+# Documentation
+/doc/
+/coverage/
+/test/html_reports/
+
+# Configuration
+/.env
+
+# Generated *.gem files
+/*.gem

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in gimme_wikidata.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Bradley Marques
+
+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,138 @@
+[![Gem Version](http://img.shields.io/gem/v/gimme_wikidata.svg?style=flat-square)](https://rubygems.org/gems/gimme_wikidata)
+[![Code Climate](https://codeclimate.com/github/bradleymarques/gimme_wikidata/badges/gpa.svg)](https://codeclimate.com/github/bradleymarques/gimme_wikidata)
+[![Test Coverage](https://codeclimate.com/github/bradleymarques/gimme_wikidata/badges/coverage.svg)](https://codeclimate.com/github/bradleymarques/gimme_wikidata/coverage)
+[![Issue Count](https://codeclimate.com/github/bradleymarques/gimme_wikidata/badges/issue_count.svg)](https://codeclimate.com/github/bradleymarques/gimme_wikidata)
+[![Inline docs](http://inch-ci.org/github/bradleymarques/gimme_wikidata.svg?branch=master)](http://inch-ci.org/github/bradleymarques/gimme_wikidata)
+[![License](http://img.shields.io/:license-mit-blue.svg?style=flat-square)](http://bradleymarques.mit-license.org)
+
+![alt text](https://raw.githubusercontent.com/bradleymarques/gimme_wikidata/master/img/gimme_wikidata_logo.png "Gimme Wikidata")
+
+Search and get data from the [Wikidata](https://www.wikidata.org/wiki/Wikidata:Main_Page) open knowledge base.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gimme_wikidata'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gimme_wikidata
+
+## Usage
+
+### Search Wikidata
+
+```ruby
+search = GimmeWikidata.search('David Bowie');
+
+search.was_successful?
+  => true
+
+search.search_term
+  => "David Bowie"
+
+search.results.count
+  => 7
+
+search.top_result
+=> #<GimmeWikidata::SearchResult:0x00555df75cdaa0
+    @description="British musician, actor, record producer and arranger",
+    @id="Q5383",
+    @label="David Bowie",
+    @type=GimmeWikidata::Item>
+```
+
+### Get Data from Wikidata
+
+You could use the search results above to get more data about an `Item` (identified by an `id`):
+
+```ruby
+david_bowie = GimmeWikidata.fetch('Q5383')
+
+david_bowie.aliases
+=> ["David Robert Jones", "Ziggy Stardust", "David Jones", "Bowie"]
+
+david_bowie.print
+===================
+David Bowie (Q5383)
+===================
+Description British musician, actor, record producer and arranger
+Aliases   David Robert Jones, Ziggy Stardust, David Jones, Bowie
+Claims:
+instance of: human (Q5)
+sex or gender: male (Q6581097)
+place of birth: Brixton (Q146690)
+spouse: Iman (Q256531)
+spouse: Angela Bowie (Q2669959)
+VIAF ID: 79021253
+GND ID: 118514091
+SUDOC authorities: 026748363
+LCAuth ID: n81112099
+BnF ID: 11893660s
+discography: David Bowie discography (Q1173801)
+Commons category: David Bowie
+ISNI: 0000 0001 1444 8576
+ISNI: 0000 0003 6858 7082
+ISNI: 0000 0003 6858 7074
+occupation: painter (Q1028181)
+occupation: singer-songwriter (Q488205)
+occupation: guitarist (Q855091)
+occupation: saxophonist (Q12800682)
+occupation: composer (Q36834)
+occupation: film actor (Q10800557)
+occupation: record producer (Q183945)
+occupation: songwriter (Q753110)
+occupation: actor (Q33999)
+# ... etc
+
+```
+
+## Retrieving Multiple Entities
+
+TODO: DOCUMENT
+
+### Publish
+
+Please note that the GimmeWikidata gem does not currently support publishing data to Wikidata.
+
+### Advanced usage
+
+## The Data Model
+
+The GimmeWikidata gem mirrors the main components of the [Wikidata data model](https://www.mediawiki.org/wiki/Wikibase/DataModel/Primer).  Specifically, the following ideas are encapsulated in classes in this gem:
+
++ `Entity`
+  + `Item`
+  + `Property`
++ `Claim`
++ `Snak`
+
+## Contributing
+
+Please feel free to contribute:
+
++ Fork the repo
++ Make your own bugfix/feature branch
++ Make tests for your contribution
++ Submit a pull request
+
+Alternatively, please feel free to make suggestions.
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2016 Bradley Marques
+
+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/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+require 'dotenv'
+Dotenv.load
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+puts "CODECLIMATE_REPO_TOKEN = #{ENV['CODECLIMATE_REPO_TOKEN']}"
+
+task :default => :test

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "gimme_wikidata"
+
+include GimmeWikidata
+
+# You can add fixtures and/or initialization code here to make experimenting with your gem easier.
+
+require "#{File.join(Dir.pwd, 'test', 'test_api_results', 'response_faker')}"
+
+# You can also use a different console, if you like.
+# Let's use pry:
+require 'pry'
+Pry.start
+

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/gimme_wikidata.gemspec

@@ -0,0 +1,48 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gimme_wikidata/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gimme_wikidata"
+  spec.version       = GimmeWikidata::VERSION
+  spec.authors       = ["Bradley Marques"]
+  spec.email         = ["bradmarxmoosepi@gmail.com"]
+
+  spec.summary       = %q{Search and get data from the Wikidata open knowledge base.}
+  spec.description   = %q{GimmeWikidata is a Ruby gem that provides an interface to search, pull (and, in future, publish) data from Wikidata.  It provides a number of classes that encapsulate the data model of Wikidata.}
+  spec.homepage      = "https://github.com/bradleymarques/gimme_wikidata"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency 'bundler', '~> 1.10'
+  spec.add_development_dependency 'rake', '>= 11.1.2', '~> 11.1.2'
+  spec.add_development_dependency 'simplecov', '~> 0.11.2', '>= 0.11.2'
+  spec.add_development_dependency 'minitest-display', '>= 0.3.1', '~> 0.3.1'
+  spec.add_development_dependency 'minitest-reporters', '~> 1.1.9', '>= 1.1.9'
+  spec.add_development_dependency 'm', '>= 1.5.0', '~> 1.5.0'
+  spec.add_development_dependency 'pry', '~> 0.10.3', '>= 0.10.3'
+  spec.add_development_dependency 'rdoc', '~> 4.2.2', '>= 4.2.2'
+  spec.add_development_dependency 'mocha', '~> 1.1.0', '>= 1.1.0'
+  spec.add_development_dependency 'dotenv', '~> 2.0.2', '>= 2.0.2'
+  spec.add_development_dependency 'codeclimate-test-reporter', '~> 0.5.2', '>= 0.5.2'
+
+  spec.add_dependency 'httparty', '~> 0.13.7', '>= 0.13.7'
+  spec.add_dependency 'ruby-enum', '~> 0.5.0', '>= 0.5.0'
+  spec.add_dependency 'colorize', '~> 0.7.7', '>= 0.7.7'
+  spec.add_dependency 'json', '~> 1.8.3', '>= 1.8.3'
+  spec.add_dependency 'carbon_date', '~> 0.1.2', '>= 0.1.2'
+
+end

data/lib/gimme_wikidata.rb

@@ -0,0 +1,143 @@
+require 'gimme_wikidata/claim'
+require 'gimme_wikidata/entity'
+require 'gimme_wikidata/entity_result'
+require 'gimme_wikidata/extensions'
+require 'gimme_wikidata/enums'
+require 'gimme_wikidata/item'
+require 'gimme_wikidata/parser'
+require 'gimme_wikidata/printer'
+require 'gimme_wikidata/property'
+require 'gimme_wikidata/search'
+require 'gimme_wikidata/version'
+require 'gimme_wikidata/wikidata_api'
+
+module GimmeWikidata
+
+  include SymbolizeHelper
+
+  class << self
+
+    ##
+    # Search Wikidata for a particular search term, and get the results.
+    #
+    # Searches the Wikidata API for a particular term and returns some SearchResults (wrapped in a Search object).
+    # Constructs the required search query, makes the call to the API and parses the response.
+    #
+    # * *Parameters*    :
+    #   - +search_term+ -> the search term to look for on Wikidata
+    #   - +strict_language+ -> Should we force a restriction to the current language?  See WikidataAPI::language
+    #   - +type+ -> Either search for 'item' or 'property'.  Defaults to 'item'
+    #   - +limit+ -> The maximum number of SearchResults to return.  Defaults to 50.
+    #   - +continue+ -> Where to continue the search from.  Defaults to 0.
+    # * *Returns* :
+    #   - A Search object representing and containing the +SearchResults+ found
+    def search(search_term = 'wikidata', strict_language: false, type: 'item', limit: 50, continue: 0)
+      search_query = WikidataAPI.search_query(search_term, strict_language: strict_language, type: type, limit: limit, continue: continue)
+      response = WikidataAPI.make_call(search_query)
+      Parser.parse_search_response(response)
+    end
+
+    ##
+    # Fetch Entity (or Entities) from Wikidata by id (or ids)
+    #
+    # Calls either +fetch_entity+ or +fetch_entities+, so is just for convenience.
+    #
+    # * *Parameters*    :
+    #   - +ids+ -> Either a single Wikidata id or an array of them.  If the former, will call +fetch_entity+; if the latter, will call +fetch_entities+
+    #   - +props+ -> The properties to pull from Wikidata (see Props class).  Defaults to +aliases+, +labels+, +descriptions+ and +claims+.
+    # * *Returns* :
+    #   - An Entity in the case of a single id, and an EntityResult in the case of multiple ids
+    # * *Raises* :
+    #   - +ArgumentError+ if ids are not valid Wikidata ids
+    def fetch(ids, props: [Props::ALIASES, Props::LABELS, Props::DESCRIPTIONS, Props::CLAIMS])
+      case ids.class.to_s
+      when 'Array'
+        raise ArgumentError.new 'Invalid Wikidata ids' unless valid_ids? ids
+        return fetch_entities(ids, props: props)
+      when 'String'
+        raise ArgumentError.new 'Invalid Wikidata id' unless valid_id? ids
+        return fetch_entity(ids, props: props)
+      else
+        raise ArgumentError.new 'Invalid Wikidata ids'
+      end
+    end
+
+    ##
+    # Fetch a single Entity from Wikidata by id
+    #
+    # * *Parameters*    :
+    #   - +id+ -> The Wikidata id of the Entity to get
+    #   - +props+ -> The properties to pull from Wikidata (see Props class)
+    # * *Returns* :
+    #   - An Entity if successful, and an EntityResponse (with error message) if unsuccessful
+    # * *Raises* :
+    #   - +ArgumentError+ if ids are not valid Wikidata ids
+    def fetch_entity(id, props: [Props::ALIASES, Props::LABELS, Props::DESCRIPTIONS, Props::CLAIMS])
+      raise ArgumentError.new 'Invalid Wikidata id' unless valid_id? id
+      entity_result = fetch_entities([id], props: props)
+      return entity_result unless entity_result.was_successful?
+      entity_result.entities.first # Simply return the first element, since there was only 1 Entity to fetch
+    end
+
+    ##
+    # Fetch multiple Entities from Wikidata by id
+    #
+    # Makes a call to Wikidata and get the results wrapped in a +EntityResult+ object
+    # * *Parameters*    :
+    #   - +ids+ -> An array of Wikidata ids, such as ['Q1', 'Q2', 'P206', 'P16']
+    #   - +props+ -> The properties to pull from Wikidata (see Props class)
+    # * *Returns* :
+    #   - An EntityResult object containing Entities
+    # * *Raises* :
+    #   - +ArgumentError+ if ids are not valid Wikidata ids
+    def fetch_entities(ids, props: [Props::ALIASES, Props::LABELS, Props::DESCRIPTIONS, Props::CLAIMS])
+      raise ArgumentError.new 'Invalid Wikidata ids' unless valid_ids? ids
+      get_query = WikidataAPI.get_entities_query(ids, props: props)
+      response = WikidataAPI.make_call(get_query)
+      entity_result = Parser.parse_entity_response(response)
+      entity_result.resolve_all_properties
+      entity_result.resolve_all_claims if props.include? Props::CLAIMS
+      entity_result
+    end
+
+    ##
+    # Valdiates an array of ids against Wikidata format
+    #
+    # Wikidata has ids in the form 'QN' or 'PN' where Q means 'Item', P means 'Property', and N is any number.
+    # * *Parameters*:
+    #   - +ids+ -> An array of (possible) Wikidata ids to be validated, in string form
+    #   - +type+ -> array of symbols representing entity types to check. Defaults to +[:item, :property]+
+    # * *Returns*:
+    #   - boolean
+    def valid_ids?(ids, type = [:item, :property])
+      return false unless ids.is_a? Array
+      ids.all? { |i| valid_id?(i, type) }
+    end
+
+    ##
+    # Valdiates a single id against Wikidata format
+    #
+    # Wikidata has ids in the form 'QN' or 'PN' where Q means 'Item', P means 'Property', and N is any number.
+    # * *Parameters*    :
+    #   - +id+ -> A (possible) Wikidata id to be validated, as a String
+    #   - +type+ -> array of symbols representing entity types to check. Defaults to +[:item, :property]+
+    # * *Returns*:
+    #   - boolean
+    def valid_id?(id, type = [:item, :property])
+
+      return false unless id.is_a? String
+
+      prefix =
+      case type
+      when [:item, :property] then 'QP'
+      when [:item] then 'Q'
+      when [:property] then 'P'
+      else raise ArgumentError.new "type must be a subset of [:item, :property]"
+      end
+
+      !(/\A[#{prefix}][0-9]+\z/.match(id).nil?)
+    end
+
+  end
+
+end

data/lib/gimme_wikidata/claim.rb

@@ -0,0 +1,65 @@
+module GimmeWikidata
+
+  ##
+  # Models a Claim on Wikidata, which consists of a Property and a value
+  #
+  # Note that the value can be of any type (example: a number, a date), and is often another Item on Wikidata.
+  #
+  # For more details, please see: https://www.wikidata.org/wiki/Wikidata:Glossary#Claims_and_statements
+  class Claim
+
+    ##
+    # The Property that the Claim is about
+    attr_reader :property
+
+    ##
+    # The value that the Property is claimed to have
+    attr_reader :value
+
+    ##
+    # The type of value.  Current types:
+    # - item
+    # - property
+    # - wikidata_time
+    # - external_id
+    # - media
+    # - text
+    # - url
+    # - gps_coordinates
+    # - quantity
+    attr_reader :value_type
+
+    def initialize(property = nil, value = nil, value_type = nil)
+      @property = property
+      @value = value
+      @value_type = value_type
+    end
+
+    ##
+    # Returns a simple hash form of the claim.
+    #
+    # Example: {sex_or_gender: "Male"}
+    def simplify
+      property = @property.label
+      value = simplify_value
+      return {property: property, value: value}
+    end
+
+    ##
+    # Simplifies the value
+    #
+    # TODO: DOCUMENT THIS FUNCTION BETTER
+    def simplify_value
+      case @value_type
+      when :item, :property
+        return "#{@value.label} (#{@value.id})"
+      when :carbon_date
+        return @value.to_s
+      when :external_id, :media, :text, :url, :gps_coordinates, :quantity
+        return @value
+      else
+        return nil # TODO: Consider throwing an exception here
+      end
+    end
+  end
+end