wikidatum 0.1.0 → 0.2.0

data/lib/wikidatum/item.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
 class Wikidatum::Item
+  # @return [String] the ID of the Wikibase item, in the format "Q123".
+  attr_reader :id
+
   # @!visibility private
   #
+  # @param id [String] The ID of the Wikibase item, in the format "Q123".
   # @param labels [Array<Wikidatum::Term>] An array of {Wikidatum::Term}s representing labels for this item.
   # @param descriptions [Array<Wikidatum::Term>] An array of {Wikidatum::Term}s representing descriptions for this item.
   # @param aliases [Array<Wikidatum::Term>] An array of {Wikidatum::Term}s representing aliases for this item.
   # @param statements [Array<Wikidatum::Statement>] Statements for this item.
   # @param sitelinks [Array<Wikidatum::Sitelink>] Sitelinks for this item.
   # @return [Wikidatum::Item]
-  def initialize(labels:, descriptions:, aliases:, statements:, sitelinks:)
+  def initialize(id:, labels:, descriptions:, aliases:, statements:, sitelinks:)
+    @id = id
     @labels = labels
     @descriptions = descriptions
     @aliases = aliases
@@ -17,21 +22,28 @@ class Wikidatum::Item
     @sitelinks = sitelinks
   end
 
-  # @param property [String] Wikidata property, in the format of 'P123'. If unspecified, will return all statements for the item.
-  # @return [Array<Wikidatum::Statement>]
-  def statements(property: nil)
-    return @statements if property.nil?
-
-    # TODO
-    @statements
-  end
-
+  # Get the label for an item in a given language.
+  #
+  # @example Get the label of the item for a given language.
+  #   item.label(lang: 'es')
+  # @example Also accepts symbols.
+  #   item.label(lang: :en)
+  # @example You can also use the {Wikidatum::LanguageCodes} constants to write code that's easier to read.
+  #   item.label(lang: Wikidatum::LanguageCodes::English)
+  #
   # @param lang [String, Symbol]
   # @return [Wikidatum::Term, nil]
   def label(lang:)
     @labels.find { |label| label.lang == lang.to_s }
   end
 
+  # Get labels for an item.
+  #
+  # @example Get all labels on the item.
+  #   item.labels
+  # @example Get the labels for a few specific languages.
+  #   item.labels(langs: ['en', 'es', 'fr'])
+  #
   # @param langs [Array<String, Symbol>]
   # @return [Array<Wikidatum::Term>]
   def labels(langs: [])
@@ -41,12 +53,28 @@ class Wikidatum::Item
     @labels.filter { |label| langs.include?(label.lang) }
   end
 
+  # Get the description for an item in a given language.
+  #
+  # @example Get the description in a given language.
+  #   item.description(lang: 'fr')
+  # @example Also accepts symbols.
+  #   item.description(lang: :en)
+  # @example You can also use the {Wikidatum::LanguageCodes} constants to write code that's easier to read.
+  #   item.description(lang: Wikidatum::LanguageCodes::English)
+  #
   # @param lang [String, Symbol]
   # @return [Wikidatum::Term, nil]
   def description(lang:)
     @descriptions.find { |desc| desc.lang == lang.to_s }
   end
 
+  # Get descriptions for an item.
+  #
+  # @example Get all descriptions on the item.
+  #   item.descriptions
+  # @example Get the descriptions for a few specific languages.
+  #   item.descriptions(langs: ['en', 'es', 'fr'])
+  #
   # @param langs [Array<String, Symbol>]
   # @return [Array<Wikidatum::Term>]
   def descriptions(langs: [])
@@ -56,6 +84,15 @@ class Wikidatum::Item
     @descriptions.filter { |desc| langs.include?(desc.lang) }
   end
 
+  # Get aliases for the item.
+  #
+  # @example Get aliases for all languages.
+  #   item.aliases
+  # @example Get the aliases for one or more specific languages.
+  #   item.aliases(langs: ['en', 'es'])
+  # @example Also accepts symbols.
+  #   item.aliases(langs: [:en, :es])
+  #
   # @param langs [Array<Symbol, String>] If unspecified, will return all aliases for all languages.
   # @return [Array<Wikidatum::Term>]
   def aliases(langs: [])
@@ -65,6 +102,21 @@ class Wikidatum::Item
     @aliases.filter { |al| langs.include?(al.lang) }
   end
 
+  # Get statements on the item.
+  #
+  # @example Get all statements.
+  #   item.statements
+  # @example Get statements for one or more specific properties.
+  #   item.statements(properties: ['P123', 'P124'])
+  #
+  # @param properties [Array<String>] One or more Wikidata properties, in the format of `['P123']`. If unspecified, will return all statements for the item.
+  # @return [Array<Wikidatum::Statement>]
+  def statements(properties: [])
+    return @statements if properties.empty?
+
+    @statements.filter { |statement| properties.include?(statement.property_id) }
+  end
+
   # Get a specific sitelink based on its shortcode.
   #
   # @example
@@ -83,9 +135,11 @@ class Wikidatum::Item
   # @example Getting all sitelinks for the item.
   #   item.sitelinks
   # @example Getting only a few specific sitelinks.
-  #   item.sitelink(sites: ['enwiki', 'eswiki', 'commons'])
+  #   item.sitelinks(sites: ['enwiki', 'eswiki', 'commons'])
+  # @example Also accepts symbols.
+  #   item.sitelinks(sites: [:enwiki, :eswiki])
   #
-  # @param sites [Array<String, Symbol>] An array of sitelink shortcodes to return (e.g. ['enwiki', 'eswiki']), if not provided then all sitelinks will be returned.
+  # @param sites [Array<String, Symbol>] An array of sitelink shortcodes to return (e.g. `['enwiki', 'eswiki']`), if not provided then all sitelinks will be returned.
   # @return [Array<Wikidatum::Sitelink>]
   def sitelinks(sites: [])
     return @sitelinks if sites.empty?
@@ -93,4 +147,56 @@ class Wikidatum::Item
     sites.map!(&:to_s)
     @sitelinks.filter { |sitelink| sites.include?(sitelink.site) }
   end
+
+  # Convert the item, including all of its labels, descriptions, aliases,
+  # statements, and sitelinks, to a Ruby hash.
+  #
+  # This can be useful for debugging purposes.
+  #
+  # @example View the contents of an item according to the Wikidatum gem by outputting prettified JSON.
+  #   require 'json'
+  #
+  #   puts JSON.pretty_generate(item.to_h)
+  #
+  # @return [Hash]
+  def to_h
+    {
+      id: @id,
+      labels: @labels.map(&:to_h),
+      descriptions: @descriptions.map(&:to_h),
+      aliases: @aliases.map(&:to_h),
+      statements: @statements.map(&:to_h),
+      sitelinks: @sitelinks.map(&:to_h)
+    }
+  end
+
+  # @!visibility private
+  #
+  # This takes in the JSON blob (as a hash) that is output for an item record
+  # in the API and turns it into an actual instance of an Item.
+  #
+  # @param item_json [Hash]
+  # @return [Wikidatum::Item]
+  def self.marshal_load(item_json)
+    labels = item_json['labels'].to_a.map { |lang, label| Wikidatum::Term.new(lang: lang, value: label) }
+    descriptions = item_json['descriptions'].to_a.map { |lang, desc| Wikidatum::Term.new(lang: lang, value: desc) }
+    aliases = item_json['aliases'].to_a.flat_map do |lang, als|
+      als.map { |al| Wikidatum::Term.new(lang: lang, value: al) }
+    end
+    statements = item_json['statements'].to_a.flat_map do |_property_id, st_arr|
+      st_arr.map { |statement| Wikidatum::Statement.marshal_load(statement) }
+    end
+    sitelinks = item_json['sitelinks'].to_a.map do |_name, sitelink|
+      Wikidatum::Sitelink.new(site: sitelink['site'], title: sitelink['title'], badges: sitelink['badges'])
+    end
+
+    Wikidatum::Item.new(
+      id: item_json['id'],
+      labels: labels,
+      descriptions: descriptions,
+      aliases: aliases,
+      statements: statements,
+      sitelinks: sitelinks
+    )
+  end
 end

data/lib/wikidatum/qualifier.rb

@@ -1,4 +1,7 @@
 # frozen_string_literal: true
 
-class Wikidatum::Qualifier
-end
+require 'wikidatum/snak'
+
+# Wikidatum::Qualifier is actually just an alias for snak, because qualifiers
+# are effectively just snaks.
+Wikidatum::Qualifier = Wikidatum::Snak

data/lib/wikidatum/reference.rb

@@ -1,4 +1,47 @@
 # frozen_string_literal: true
 
 class Wikidatum::Reference
+  # @return [String] Hash of the reference (a cryptographic hash, not a Ruby hash).
+  attr_reader :hash
+
+  # @return [Array<Wikidatum::Snak>]
+  attr_reader :snaks
+
+  # @!visibility private
+  # @param hash [String] Hash of the reference (a cryptographic hash, not a Ruby hash).
+  # @param snaks [Array<Wikidatum::Snak>]
+  def initialize(hash:, snaks:)
+    @hash = hash
+    @snaks = snaks
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      hash: @hash,
+      snaks: @snaks.map(&:to_h)
+    }
+  end
+
+  # @return [String]
+  def inspect
+    "<Wikidatum::Reference hash=#{@hash.inspect} snaks=#{@snaks.inspect}>"
+  end
+
+  # @!visibility private
+  #
+  # This takes in the JSON blob (as a hash) that is output for a given
+  # reference in the API and turns it into an actual instance of a
+  # Reference.
+  #
+  # @param ref_json [Hash]
+  # @return [Wikidatum::Reference]
+  def self.marshal_load(ref_json)
+    snaks = ref_json['snaks'].values.flatten.map { |snak| Wikidatum::Snak.marshal_load(snak) }
+
+    Wikidatum::Reference.new(
+      hash: ref_json['hash'],
+      snaks: snaks
+    )
+  end
 end

data/lib/wikidatum/sitelink.rb

@@ -15,11 +15,25 @@ class Wikidatum::Sitelink
   #
   # @param site [String, Symbol] The shortcode for the given site (e.g. 'enwiki', 'commons', etc.), can be either a string or a symbol.
   # @param title [String] The title of the page in the associated Wikimedia site.
-  # @param badges [Array<String>] An array of badge names, optional.
+  # @param badges [Array<String>] An array of badges, given as item IDs (e.g. `['Q123', 'Q124']`) optional.
   # @return [Wikidatum::Sitelink]
   def initialize(site:, title:, badges: [])
     @site = site.to_s
     @title = title
     @badges = badges
   end
+
+  # @return [Hash]
+  def to_h
+    {
+      site: @site,
+      title: @title,
+      badges: @badges
+    }
+  end
+
+  # @return [String]
+  def inspect
+    "<Wikidatum::Sitelink site=#{@site.inspect} title=#{@title.inspect} badges=#{@badges.inspect}>"
+  end
 end

data/lib/wikidatum/snak.rb

@@ -1,4 +1,79 @@
 # frozen_string_literal: true
 
 class Wikidatum::Snak
+  # @return [String] Hash of a snak (a cryptographic hash, not a Ruby hash).
+  attr_reader :hash
+
+  # @return [String]
+  attr_reader :snaktype
+
+  # @return [String] ID of the property for this Snak, in the format 'P123'.
+  attr_reader :property
+
+  # @return [String]
+  attr_reader :datatype
+
+  # For more information on the possible types that can be returned by
+  # datavalues, see the official documentation:
+  # https://doc.wikimedia.org/Wikibase/master/php/md_docs_topics_json.html#json_datavalues
+  #
+  # @return [Wikidatum::DataValueType::Base] the value of the statement, can take various forms
+  attr_reader :datavalue
+
+  # @!visibility private
+  # @param hash [String] Hash of a snak (a cryptographic hash, not a Ruby hash).
+  # @param snaktype [String]
+  # @param property [String] ID of the property for this Snak, in the format 'P123'.
+  # @param datatype [String]
+  # @param datavalue [DataValueType::GlobeCoordinate, DataValueType::MonolingualText, DataValueType::Quantity, DataValueType::WikibaseString, DataValueType::Time, DataValueType::WikibaseEntityId]
+  def initialize(hash:, snaktype:, property:, datatype:, datavalue:)
+    @hash = hash
+    @snaktype = snaktype
+    @property = property
+    @datatype = datatype
+    @datavalue = datavalue
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      hash: @hash,
+      snaktype: @snaktype,
+      property: @property,
+      datatype: @datatype,
+      datavalue: @datavalue.to_h
+    }
+  end
+
+  # @return [String]
+  def inspect
+    "<Wikidatum::Snak hash=#{@hash.inspect} snaktype=#{@snaktype.inspect} property=#{@property.inspect} datatype=#{@datatype.inspect} datavalue=#{@datavalue.inspect}>"
+  end
+
+  # @!visibility private
+  #
+  # This takes in the JSON blob (as a hash) that is output for a given
+  # snak in the API and turns it into an actual instance of a Snak.
+  #
+  # @param snak_json [Hash]
+  # @return [Wikidatum::Snak]
+  def self.marshal_load(snak_json)
+    # snaktype can be 'novalue' (no value) or 'somevalue' (unknown), so we handle those as somewhat special cases
+    case snak_json['snaktype']
+    when 'novalue'
+      datavalue = Wikidatum::DataValueType::Base.marshal_load('novalue', nil)
+    when 'somevalue'
+      datavalue = Wikidatum::DataValueType::Base.marshal_load('somevalue', nil)
+    when 'value'
+      datavalue = Wikidatum::DataValueType::Base.marshal_load(snak_json['datavalue']['type'], snak_json['datavalue']['value'])
+    end
+
+    Wikidatum::Snak.new(
+      hash: snak_json['hash'],
+      snaktype: snak_json['snaktype'],
+      property: snak_json['property'],
+      datatype: snak_json['datatype'],
+      datavalue: datavalue
+    )
+  end
 end

data/lib/wikidatum/statement.rb

@@ -1,4 +1,77 @@
 # frozen_string_literal: true
 
 class Wikidatum::Statement
+  # @return [String]
+  attr_reader :id
+
+  # @return [String] property ID, in the format of 'P123'.
+  attr_accessor :property_id
+
+  # @return [Wikidatum::Snak]
+  attr_accessor :mainsnak
+
+  # @return [Array<Wikidatum::Qualifier>]
+  attr_accessor :qualifiers
+
+  # @return [Array<Wikidatum::Reference>]
+  attr_accessor :references
+
+  # @return [String] the rank of the given statement.
+  #   Can have the values "preferred", "normal", or "deprecated". Defaults to "normal".
+  attr_accessor :rank
+
+  # @param id [String]
+  # @param property_id [String] The 'P123' ID of the property that this statement represents.
+  # @param mainsnak [Wikidatum::Snak]
+  # @param qualifiers [Array<Wikidatum::Qualifier>]
+  # @param references [Array<Wikidatum::Reference>]
+  # @param rank [String] The rank of the given statement.
+  #   Can have the values "preferred", "normal", or "deprecated". Defaults to "normal".
+  def initialize(id:, property_id:, mainsnak:, qualifiers:, references:, rank: 'normal')
+    @id = id
+    @property_id = property_id
+    @mainsnak = mainsnak
+    @qualifiers = qualifiers
+    @references = references
+    @rank = rank
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      id: @id,
+      property_id: @property_id,
+      mainsnak: @mainsnak.to_h,
+      qualifiers: @qualifiers.map(&:to_h),
+      references: @references.map(&:to_h),
+      rank: @rank
+    }
+  end
+
+  # @!visibility private
+  #
+  # This takes in the JSON blob (as a hash) that is output for a given
+  # statement in the API and turns it into an actual instance of a Statement.
+  #
+  # @param statement_json [Hash]
+  # @return [Wikidatum::Statement]
+  def self.marshal_load(statement_json)
+    mainsnak = Wikidatum::Snak.marshal_load(statement_json['mainsnak'])
+
+    qualifiers = statement_json['qualifiers'].to_a.flat_map do |_qualifier_prop_id, qualifier|
+      qualifier.map { |q| Wikidatum::Qualifier.marshal_load(q) }
+    end
+    references = statement_json['references'].flat_map do |reference|
+      Wikidatum::Reference.marshal_load(reference)
+    end
+
+    Wikidatum::Statement.new(
+      id: statement_json['id'],
+      property_id: mainsnak.property,
+      mainsnak: mainsnak,
+      qualifiers: qualifiers,
+      references: references,
+      rank: statement_json['rank']
+    )
+  end
 end

data/lib/wikidatum/term.rb

@@ -18,4 +18,17 @@ class Wikidatum::Term
     @lang = lang.to_s
     @value = value
   end
+
+  # @return [Hash]
+  def to_h
+    {
+      lang: @lang,
+      value: @value
+    }
+  end
+
+  # @return [String]
+  def inspect
+    "<Wikidatum::Term lang=#{@lang.inspect} value=#{@value.inspect}>"
+  end
 end

data/lib/wikidatum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wikidatum
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/wikidatum.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'wikidatum/client'
+require_relative 'wikidatum/data_value_type'
 require_relative 'wikidatum/item'
 require_relative 'wikidatum/qualifier'
 require_relative 'wikidatum/reference'
+require_relative 'wikidatum/sitelink'
 require_relative 'wikidatum/snak'
 require_relative 'wikidatum/statement'
 require_relative 'wikidatum/term'
@@ -11,4 +13,50 @@ require_relative 'wikidatum/version'
 
 module Wikidatum
   class Error < StandardError; end
+
+  # rubocop:disable Naming/ConstantName
+
+  # These language codes are not enforced, you can pass whatever language code
+  # you want, even if it's not represented in this list. The purpose of this
+  # is to provide helper constants to allow writing more readable code.
+  #
+  # This will only cover some of the most common language codes, not all of
+  # them.
+  module LanguageCodes
+    Arabic = 'ar'
+    BrazilianPortuguese = 'pt-br'
+    Chinese = 'zh'
+    Dutch = 'nl'
+    English = 'en'
+    EnglishUK = 'en-gb'
+    French = 'fr'
+    German = 'de'
+    Hebrew = 'he'
+    Hindi = 'hi'
+    Italian = 'it'
+    Polish = 'pl'
+    Portuguese = 'pt'
+    Russian = 'ru'
+    SimplifiedChinese = 'zh-hans'
+    Spanish = 'es'
+    TraditionalChinese = 'zh-hant'
+    Turkish = 'tr'
+    Ukrainian = 'uk'
+    # rubocop:enable Naming/ConstantName
+  end
+
+  module DataValueType
+    # rubocop:disable Lint/SymbolConversion
+    DATA_VALUE_TYPES = {
+      'globecoordinate': 'Wikidatum::DataValueType::GlobeCoordinate',
+      'monolingualtext': 'Wikidatum::DataValueType::MonolingualText',
+      'novalue': 'Wikidatum::DataValueType::NoValue',
+      'quantity': 'Wikidatum::DataValueType::Quantity',
+      'somevalue': 'Wikidatum::DataValueType::SomeValue',
+      'string': 'Wikidatum::DataValueType::WikibaseString',
+      'time': 'Wikidatum::DataValueType::Time',
+      'wikibase-entityid': 'Wikidatum::DataValueType::WikibaseEntityId'
+    }.freeze
+    # rubocop:enable Lint/SymbolConversion
+  end
 end

data/wikidatum.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = "https://github.com/connorshea/wikidatum"
   spec.metadata["source_code_uri"] = "https://github.com/connorshea/wikidatum"
   spec.metadata["changelog_uri"] = "https://github.com/connorshea/wikidatum/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -30,8 +31,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency "faraday", "~> 2.4"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: wikidatum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Connor Shea
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-20 00:00:00.000000000 Z
-dependencies: []
+date: 2022-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 description: Interact with the Wikidata/Wikibase REST API from Ruby.
 email:
 - connor.james.shea+rubygems@gmail.com
@@ -27,6 +41,16 @@ files:
 - bin/setup
 - lib/wikidatum.rb
 - lib/wikidatum/client.rb
+- lib/wikidatum/data_value_type.rb
+- lib/wikidatum/data_value_type/base.rb
+- lib/wikidatum/data_value_type/globe_coordinate.rb
+- lib/wikidatum/data_value_type/monolingual_text.rb
+- lib/wikidatum/data_value_type/no_value.rb
+- lib/wikidatum/data_value_type/quantity.rb
+- lib/wikidatum/data_value_type/some_value.rb
+- lib/wikidatum/data_value_type/time.rb
+- lib/wikidatum/data_value_type/wikibase_entity_id.rb
+- lib/wikidatum/data_value_type/wikibase_string.rb
 - lib/wikidatum/item.rb
 - lib/wikidatum/qualifier.rb
 - lib/wikidatum/reference.rb
@@ -44,6 +68,7 @@ metadata:
   homepage_uri: https://github.com/connorshea/wikidatum
   source_code_uri: https://github.com/connorshea/wikidatum
   changelog_uri: https://github.com/connorshea/wikidatum/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -59,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Ruby gem for the new Wikidata REST API.