wikidatum 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2ee435a3831b816e6e64465040a5197de654450551812b835b28329be9c287d
-  data.tar.gz: d23fb1902df5465b123fc0bcea0c7594fb64a6e918604a9f1bb1f4e4eadf6eff
+  metadata.gz: 524da97907bba148830e9191d3c0ba5c614ddbee6c50fd74c6e91595082e73bd
+  data.tar.gz: 2321efe8c69e953521dbe5f4da51725fd6183ac871e7c00a17c552c12dc15dc2
 SHA512:
-  metadata.gz: ccd8210a5120fbbfb35ed03899938bf4ca4e5302bc93e3e53652180b86b221a3ec23afe57db78777ffcda5971150f7c0ed6af89cde7b294fe21d716491653c49
-  data.tar.gz: cb4e092b80c6ab871c1dd7f5bd46f700029eab7438c7a4063a2aee42b389c0e86ec0e387fc15fa996037d2478f494ac46572879078930c41c18ae6b7e4073e00
+  metadata.gz: 634701e7e5204ea770eb114f62982140e3441358e71f1ca32bf38718f9e72f29fe582340546c28e0dad4e575903c6822057bb12f21572333c68cd6c28b2f1e46
+  data.tar.gz: 26cf62b267be9bb4a6cc752d1968740b3d153f972204f0b1d7900fa7e087cea6eef0e543972b3aafb22f98ffbea8cdc6e30f22cc30f34aa77d2f4d1605655d02

data/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 
+## 0.3.3 - 2023-01-24
+### Added
+
+- Add a `labels` method on Wikidatum::Client for getting item label data from the new `items/{id}/labels` endpoint. (This isn't supported in the initial release of the REST API on Wikidata, so it will not work yet)
+
+### Changed
+
+- Move error classes into their own `Wikidatum::Errors` namespace.
+
+## 0.3.2 - 2022-12-29
+### Added
+
+- Add support for the `commonsMedia`, `url`, and `external-id` data types.
+- Add `humanized_content` method to `Wikidatum::DataType::Base` class, for easier access to a Struct, string, or nil which represents the contents of the given data type.
+
 ## 0.3.1 - 2022-12-28
 ### Added
 

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2022 Connor Shea
+Copyright (c) 2022-2023 Connor Shea
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -2,9 +2,11 @@
 
 This gem supports making requests to the [new Wikidata/Wikibase REST API](https://doc.wikimedia.org/Wikibase/master/js/rest-api/).
 
-The [Wikimedia Docs on Wikibase's JSON format](https://doc.wikimedia.org/Wikibase/master/php/docs_topics_json.html) are also very useful for interacting with/contributing to this gem.
+The [Wikimedia Docs on the Wikibase REST API data format differences](https://doc.wikimedia.org/Wikibase/master/php/rest_data_format_differences.html) are also very useful for interacting with/contributing to this gem.
 
-**The gem is currently in early development and is not ready for production usage**.
+**The gem is currently in development. It's ready to be used, but you should be careful when making edits with it to ensure it's working correctly.** It's missing some key features, namely authentication support, but the core of the library works.
+
+I reserve the right to make breaking changes while the library is still in the 0.x release series, although I'll avoid them unless I believe them to be significantly better for the library's usability/maintainability (or are necessary due to breaking changes in the REST API itself). If they do happen, I'll make them clear in the Changelog.
 
 ## Installation
 
@@ -24,7 +26,7 @@ Or install it yourself as:
 
 ## Usage
 
-You can view the YARD docs on GitHub Pages [here](https://connorshea.github.io/wikidatum/index.html).
+You can view the YARD docs on GitHub Pages [here](https://connorshea.github.io/wikidatum/index.html). Generally, you'll want to look at the docs for {Wikidatum::Client} to get started.
 
 Currently, the gem is able to hit a few of the basic endpoints, and currently has no way to provide authentication. The additional features will be added later.
 
@@ -33,9 +35,10 @@ require 'wikidatum'
 
 wikidatum_client = Wikidatum::Client.new(
   user_agent: 'REPLACE ME WITH THE NAME OF YOUR BOT!',
-  # Currently only the beta site has the API available, you'll
-  # likely want to use wikidata.org once it's stable.
-  wikibase_url: 'https://wikidata.beta.wmflabs.org',
+  wikibase_url: 'https://wikidata.org',
+  # NOTE: To edit as a bot, you need to authenticate as a user with the Bot
+  # flag. If you don't have that flag on your Wikibase User, you'll get a
+  # 403 error.
   bot: true
 )
 
@@ -60,6 +63,10 @@ item.label(lang: :en).value #=> "Earth"
 # Get the values for all English aliases on this item.
 item.aliases(langs: [:en]).map(&:value) #=> ["Planet Earth", "Pale Blue Dot"]
 
+# Get all labels for a given item.
+wikidatum_client.labels(id: 'Q2') #=> Array<Wikidatum::Term>
+
+# Get a specific statement from its ID.
 statement_id = 'Q123$4543523c-1d1d-1111-1e1e-11b11111b1f1'
 statement = wikidatum_client.statement(id: statement_id) #=> Wikidatum::Statement
 

data/lib/wikidatum/client.rb

@@ -10,6 +10,8 @@ module Wikidatum
     STATEMENT_REGEX = /^Q?\d+\$[\w-]+$/.freeze
     VALID_RANKS = ['preferred', 'normal', 'deprecated'].freeze
     VALID_DATA_TYPES = [
+      'Wikidatum::DataType::CommonsMedia',
+      'Wikidatum::DataType::ExternalId',
       'Wikidatum::DataType::GlobeCoordinate',
       'Wikidatum::DataType::MonolingualText',
       'Wikidatum::DataType::NoValue',
@@ -17,7 +19,21 @@ module Wikidatum
       'Wikidatum::DataType::SomeValue',
       'Wikidatum::DataType::Time',
       'Wikidatum::DataType::WikibaseItem',
-      'Wikidatum::DataType::WikibaseString'
+      'Wikidatum::DataType::WikibaseString',
+      'Wikidatum::DataType::WikibaseUrl'
+    ].freeze
+
+    # @!private
+    CONTENT_DATA_TYPES = [
+      'Wikidatum::DataType::CommonsMedia',
+      'Wikidatum::DataType::ExternalId',
+      'Wikidatum::DataType::GlobeCoordinate',
+      'Wikidatum::DataType::MonolingualText',
+      'Wikidatum::DataType::Quantity',
+      'Wikidatum::DataType::Time',
+      'Wikidatum::DataType::WikibaseItem',
+      'Wikidatum::DataType::WikibaseString',
+      'Wikidatum::DataType::WikibaseUrl'
     ].freeze
 
     # @return [String] the root URL of the Wikibase instance we want to interact
@@ -52,7 +68,10 @@ module Wikidatum
     #   to interact with. If not provided, will default to
     #   `https://www.wikidata.org`. Do not include a `/` at the end of the URL.
     # @param bot [Boolean] Whether requests sent by this client instance should
-    #   be registered as bot requests. Defaults to `true`.
+    #   be registered as bot requests. Defaults to `true`. If the user is not
+    #   authenticated, or if the user is not marked with the Bot flag in the
+    #   Wikibase instance, you'll be unable to make edits with this set to
+    #   `true`.
     # @param allow_ip_edits [Boolean] whether this client should allow non-GET
     #   requests if authentication hasn't been provided. Defaults to false. If
     #   this is set to true, the IP address of the device from which the
@@ -93,6 +112,28 @@ module Wikidatum
       Wikidatum::Item.marshal_load(response)
     end
 
+    # Get labels for an item from the Wikibase API based on the item's QID.
+    #
+    # @example
+    #   wikidatum_client.labels(id: 'Q123') #=> [<Wikidatum::Term lang="en" value="Foo">, <Wikidatum::Term lang="es" value="Bar">]
+    #   wikidatum_client.labels(id: 123)
+    #   wikidatum_client.labels(id: '123')
+    #
+    # @param id [String, Integer] Either a string or integer representation of
+    #   the relevant item's QID, e.g. `"Q123"`, `"123"`, or `123`.
+    # @return [Array<Wikidatum::Term>] This can, theoretically, be empty if the item has no labels.
+    def labels(id:)
+      raise ArgumentError, "#{id.inspect} is an invalid Wikibase QID. Must be an integer, a string representation of an integer, or in the format 'Q123'." unless id.is_a?(Integer) || id.match?(ITEM_REGEX)
+
+      id = coerce_item_id(id)
+
+      response = get_request("/entities/items/#{id}/labels")
+
+      puts JSON.pretty_generate(response) if ENV['DEBUG']
+
+      response.to_a.map { |lang, val| Wikidatum::Term.new(lang: lang, value: val) }
+    end
+
     # Get a statement from the Wikibase API based on its ID.
     #
     # @example
@@ -195,9 +236,36 @@ module Wikidatum
     #     )
     #   )
     #
+    # @example Add a URL statement.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::WikibaseUrl.new(
+    #       string: 'https://example.com'
+    #     )
+    #   )
+    #
+    # @example Add an External ID statement.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::ExternalId.new(
+    #       string: '123'
+    #     )
+    #   )
+    #
+    # @example Add a statement for an image, video, or audio file from Wikimedia Commons.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::CommonsMedia.new(
+    #       string: 'FooBar.jpg'
+    #     )
+    #   )
+    #
     # @param id [String, Integer] the ID of the item on which the statement will be added.
     # @param property [String, Integer] property ID in the format 'P123', or an integer.
-    # @param value [Wikidatum::DataType::GlobeCoordinate, Wikidatum::DataType::MonolingualText, Wikidatum::DataType::Quantity, Wikidatum::DataType::WikibaseString, Wikidatum::DataType::Time, Wikidatum::DataType::WikibaseItem, Wikidatum::DataType::NoValue, Wikidatum::DataType::SomeValue] the value of the statement being created.
+    # @param value [Wikidatum::DataType::CommonsMedia, Wikidatum::DataType::ExternalId, Wikidatum::DataType::GlobeCoordinate, Wikidatum::DataType::MonolingualText, Wikidatum::DataType::Quantity, Wikidatum::DataType::WikibaseString, Wikidatum::DataType::Time, Wikidatum::DataType::WikibaseItem, Wikidatum::DataType::WikibaseUrl, Wikidatum::DataType::NoValue, Wikidatum::DataType::SomeValue] the value of the statement being created.
     # @param qualifiers [Array<Wikidatum::Qualifier>]
     # @param references [Array<Wikidatum::Reference>]
     # @param rank [String, Symbol] Valid ranks are 'preferred', 'normal', or
@@ -233,7 +301,7 @@ module Wikidatum
             type: 'somevalue'
           }
         }
-      when 'Wikidatum::DataType::GlobeCoordinate', 'Wikidatum::DataType::MonolingualText', 'Wikidatum::DataType::Quantity', 'Wikidatum::DataType::WikibaseString', 'Wikidatum::DataType::Time', 'Wikidatum::DataType::WikibaseItem'
+      when *CONTENT_DATA_TYPES
         statement_hash = {
           property: {
             id: property
@@ -446,10 +514,10 @@ module Wikidatum
     # error message if so.
     #
     # @return [void]
-    # @raise [DisallowedIpEditError, DisallowedBotEditError]
+    # @raise [Errors::DisallowedIpEditError, Errors::DisallowedBotEditError]
     def ensure_edit_permitted!
-      raise DisallowedIpEditError if !authenticated? && !allow_ip_edits?
-      raise DisallowedBotEditError if !authenticated? && bot?
+      raise Errors::DisallowedIpEditError if !authenticated? && !allow_ip_edits?
+      raise Errors::DisallowedBotEditError if !authenticated? && bot?
     end
   end
 end

data/lib/wikidatum/data_type/base.rb

@@ -2,7 +2,7 @@
 
 # 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
+# https://doc.wikimedia.org/Wikibase/master/php/docs_topics_json.html#json_datavalues
 module Wikidatum::DataType
   class Base
     # Represents the type for this instance.
@@ -11,11 +11,14 @@ module Wikidatum::DataType
     #
     # - `:no_value`: No value
     # - `:some_value`: Unknown value
+    # - `:commons_media`: {DataType::CommonsMedia}
+    # - `:external_id`: {DataType::ExternalId}
     # - `:globe_coordinate`: {DataType::GlobeCoordinate}
     # - `:monolingual_text`: {DataType::MonolingualText}
     # - `:quantity`: {DataType::Quantity}
     # - `:string`: {DataType::WikibaseString}
     # - `:time`: {DataType::Time}
+    # - `:url`: {DataType::WikibaseUrl}
     # - `:wikibase_item`: {DataType::WikibaseItem}
     #
     # @return [Symbol]
@@ -23,13 +26,13 @@ module Wikidatum::DataType
 
     # The value of the "content" attribute in the response.
     #
-    # If the `type` is `novalue` or `somevalue`, this returns `nil`.
+    # If the `type` is `:no_value` or `:some_value`, this returns `nil`.
     #
-    # @return [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
+    # @return [DataType::CommonsMedia, DataType::ExternalId, DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::Time, DataType::WikibaseItem, DataType::WikibaseString, DataType::WikibaseUrl, nil]
     attr_reader :content
 
     # @param type [Symbol]
-    # @param content [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil] nil if type is no_value or some_value
+    # @param content [DataType::CommonsMedia, DataType::ExternalId, DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::Time, DataType::WikibaseItem, DataType::WikibaseString, DataType::WikibaseUrl, nil] nil if type is no_value or some_value
     # @return [void]
     def initialize(type:, content:)
       @type = type
@@ -44,6 +47,14 @@ module Wikidatum::DataType
       }
     end
 
+    # Get the humanized version of the content. Depending on the given data
+    # type, it will return values in different formats.
+    #
+    # @return [String, DataType::GlobeCoordinate::HumanizedStruct, DataType::MonolingualText::HumanizedStruct, DataType::Quantity::HumanizedStruct, DataType::Time::HumanizedStruct, nil]
+    def humanized_content
+      @content.humanized
+    end
+
     # @!visibility private
     #
     # @param data_type [String] The value of `data-type` for the given Statement or Qualifier's property.

data/lib/wikidatum/data_type/commons_media.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::CommonsMedia < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'commonsMedia'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :commons_media
+  end
+end

data/lib/wikidatum/data_type/external_id.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::ExternalId < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'external-id'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :external_id
+  end
+end

data/lib/wikidatum/data_type/globe_coordinate.rb

@@ -63,9 +63,19 @@ class Wikidatum::DataType::GlobeCoordinate
     'globe-coordinate'
   end
 
+  HumanizedStruct = Struct.new(:latitude, :longitude, :precision, :globe, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<latitude, longitude, precision, globe>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
-    :monolingual_text
+    :globe_coordinate
   end
 
   # @!visibility private

data/lib/wikidatum/data_type/monolingual_text.rb

@@ -49,6 +49,16 @@ class Wikidatum::DataType::MonolingualText
     'monolingualtext'
   end
 
+  HumanizedStruct = Struct.new(:language, :text, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<language, text>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :monolingual_text

data/lib/wikidatum/data_type/no_value.rb

@@ -9,11 +9,21 @@ require 'wikidatum/data_type/base'
 class Wikidatum::DataType::NoValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
+  # In this case, the type is a lie.
+  #
   # @return [String]
   def wikibase_type
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [nil]
+  def humanized
+    nil
+  end
+
   # @!visibility private
   def self.marshal_load(_data_value_json)
     new(type: :no_value, content: nil)

data/lib/wikidatum/data_type/quantity.rb

@@ -49,6 +49,16 @@ class Wikidatum::DataType::Quantity
     'quantity'
   end
 
+  HumanizedStruct = Struct.new(:amount, :unit, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<amount, unit>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :quantity

data/lib/wikidatum/data_type/some_value.rb

@@ -9,11 +9,21 @@ require 'wikidatum/data_type/base'
 class Wikidatum::DataType::SomeValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
+  # In this case, the type is a lie.
+  #
   # @return [String]
   def wikibase_type
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [nil]
+  def humanized
+    nil
+  end
+
   # @!visibility private
   def self.marshal_load(_data_value_json)
     new(type: :some_value, content: nil)

data/lib/wikidatum/data_type/time.rb

@@ -109,6 +109,16 @@ class Wikidatum::DataType::Time
     'time'
   end
 
+  HumanizedStruct = Struct.new(:time, :precision, :calendar_model, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<time, precision, pretty_precision, calendar_model>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :time

data/lib/wikidatum/data_type/wikibase_item.rb

@@ -40,6 +40,14 @@ class Wikidatum::DataType::WikibaseItem
     'wikibase-item'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [String]
+  def humanized
+    @id
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :wikibase_item

data/lib/wikidatum/data_type/wikibase_string.rb

@@ -40,6 +40,14 @@ class Wikidatum::DataType::WikibaseString
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [String]
+  def humanized
+    @string
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :string

data/lib/wikidatum/data_type/wikibase_url.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::WikibaseUrl < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'url'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :url
+  end
+end

data/lib/wikidatum/data_type.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/commons_media'
+require 'wikidatum/data_type/external_id'
 require 'wikidatum/data_type/globe_coordinate'
 require 'wikidatum/data_type/monolingual_text'
 require 'wikidatum/data_type/no_value'
@@ -9,3 +11,4 @@ require 'wikidatum/data_type/some_value'
 require 'wikidatum/data_type/time'
 require 'wikidatum/data_type/wikibase_item'
 require 'wikidatum/data_type/wikibase_string'
+require 'wikidatum/data_type/wikibase_url'

data/lib/wikidatum/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wikidatum
+  class Error < StandardError; end
+end

data/lib/wikidatum/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'wikidatum/error'
+
+module Wikidatum::Errors
+  # If the Wikidatum::Client is set to disallow IP Edits (the default) and no
+  # authentication has been provided, this error will be raised when performing
+  # any non-GET requests.
+  class DisallowedIpEditError < Wikidatum::Error
+    def message
+      'No authentication provided. If you want to perform unauthenticated edits and are comfortable exposing your IP address publicly, set `allow_ip_edits: true` when instantiating your client with `Wikidatum::Client.new`.'
+    end
+  end
+
+  # If the Wikidatum::Client is set to mark their edits as belonging to a bot,
+  # they must be authenticated as a bot user. We will disallow these edits
+  # as long as they're not authenticated as a specific user.
+  class DisallowedBotEditError < Wikidatum::Error
+    def message
+      'No authentication provided, but attempted to edit as a bot. You cannot make edits as a bot unless you have authenticated as a user with the Bot flag.'
+    end
+  end
+end

data/lib/wikidatum/qualifier.rb

@@ -9,7 +9,7 @@ class Wikidatum::Qualifier
 
   # 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
+  # https://doc.wikimedia.org/Wikibase/master/php/docs_topics_json.html#json_datavalues
   #
   # @return [Wikidatum::DataType::Base] the value of the statement, can take various forms
   attr_reader :value

data/lib/wikidatum/reference_part.rb

@@ -9,7 +9,7 @@ class Wikidatum::ReferencePart
 
   # 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
+  # https://doc.wikimedia.org/Wikibase/master/php/docs_topics_json.html#json_datavalues
   #
   # @return [Wikidatum::DataType::Base] the value of the statement, can take various forms
   attr_reader :value
@@ -17,7 +17,7 @@ class Wikidatum::ReferencePart
   # @!visibility private
   # @param property_id [String] ID of the property used, in the format "P123".
   # @param data_type [String]
-  # @param value [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, DataType::NoValue, DataType::SomeValue]
+  # @param value [DataType::CommonsMedia, DataType::ExternalId, DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::Time, DataType::WikibaseItem, DataType::WikibaseString, DataType::WikibaseUrl, DataType::NoValue, DataType::SomeValue]
   def initialize(property_id:, data_type:, value:)
     @property_id = property_id
     @data_type = data_type

data/lib/wikidatum/sitelink.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
-# Wikidatum::Sitelinks represent associated sitelinks on a Wikidata item.
+# Wikidatum::Sitelinks represent associated sitelinks on a Wikidata item, for
+# example the associated English Wikipedia article.
 class Wikidatum::Sitelink
-  # @return [String]
+  # @return [String] The shortcode for the given site (e.g. 'enwiki', 'commons', etc.).
   attr_reader :site
 
-  # @return [String]
+  # @return [String] The title of the page in the associated Wikimedia site.
   attr_reader :title
 
-  # @return [Array<String>]
+  # @return [Array<String>] An array of badges, given as item IDs (e.g. `['Q123', 'Q124']`).
   attr_reader :badges
 
   # @!visibility private
   #
   # @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 badges, given as item IDs (e.g. `['Q123', 'Q124']`) optional.
+  # @param badges [Array<String>] An array of badges, given as item IDs (e.g. `['Q123', 'Q124']`). This parameter is optional.
   # @return [Wikidatum::Sitelink]
   def initialize(site:, title:, badges: [])
     @site = site.to_s

data/lib/wikidatum/statement.rb

@@ -10,7 +10,7 @@ class Wikidatum::Statement
   # @return [String]
   attr_accessor :data_type
 
-  # @return [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
+  # @return [DataType::CommonsMedia, DataType::ExternalId, DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::Time, DataType::WikibaseItem, DataType::WikibaseString, DataType::WikibaseUrl, nil]
   attr_accessor :data_value
 
   # @return [Array<Wikidatum::Qualifier>]
@@ -26,7 +26,7 @@ class Wikidatum::Statement
   # @param id [String]
   # @param property_id [String] The 'P123' ID of the property that this statement represents.
   # @param data_type [String]
-  # @param data_value [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
+  # @param data_value [DataType::CommonsMedia, DataType::ExternalId, DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::Time, DataType::WikibaseItem, DataType::WikibaseString, DataType::WikibaseUrl, nil]
   # @param qualifiers [Array<Wikidatum::Qualifier>]
   # @param references [Array<Wikidatum::Reference>]
   # @param rank [String] The rank of the given statement.

data/lib/wikidatum/term.rb

@@ -3,16 +3,16 @@
 # Wikidatum::Term represents "Terms", which are pairs of language codes and
 # values. They're used for things like item labels, descriptions, and aliases.
 class Wikidatum::Term
-  # @return [String]
+  # @return [String] A language code ('en', 'zh-mo', etc).
   attr_reader :lang
 
-  # @return [String]
+  # @return [String] The value of the Term.
   attr_reader :value
 
   # @!visibility private
   #
   # @param lang [String, Symbol] A language code ('en', 'zh-mo', etc), can be a symbol or a string.
-  # @param value [String] The value of the term.
+  # @param value [String] The value of the Term.
   # @return [Wikidatum::Term]
   def initialize(lang:, value:)
     @lang = lang.to_s

data/lib/wikidatum/version.rb

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

data/lib/wikidatum.rb

@@ -2,6 +2,8 @@
 
 require 'wikidatum/client'
 require 'wikidatum/data_type'
+require 'wikidatum/error'
+require 'wikidatum/errors'
 require 'wikidatum/item'
 require 'wikidatum/qualifier'
 require 'wikidatum/reference'
@@ -13,26 +15,6 @@ require 'wikidatum/utils'
 require 'wikidatum/version'
 
 module Wikidatum
-  class Error < StandardError; end
-
-  # If the Wikidatum::Client is set to disallow IP Edits (the default) and no
-  # authentication has been provided, this error will be raised when performing
-  # any non-GET requests.
-  class DisallowedIpEditError < Error
-    def message
-      'No authentication provided. If you want to perform unauthenticated edits and are comfortable exposing your IP address publicly, set `allow_ip_edits: true` when instantiating your client with `Wikidatum::Client.new`.'
-    end
-  end
-
-  # If the Wikidatum::Client is set to mark their edits as belonging to a bot,
-  # they must be authenticated as a bot user. We will disallow these edits
-  # as long as they're not authenticated as a specific user.
-  class DisallowedBotEditError < Error
-    def message
-      'No authentication provided, but attempted to edit as a bot. You cannot make edits as a bot unless you have authenticated as a user with the Bot flag.'
-    end
-  end
-
   # rubocop:disable Naming/ConstantName
 
   # These language codes are not enforced, you can pass whatever language code
@@ -65,9 +47,10 @@ module Wikidatum
   end
 
   module DataType
-    # TODO: Add commonsMedia and url to the possible types.
     # rubocop:disable Lint/SymbolConversion
     DATA_TYPES = {
+      'commonsMedia': 'Wikidatum::DataType::CommonsMedia',
+      'external-id': 'Wikidatum::DataType::ExternalId',
       'globe-coordinate': 'Wikidatum::DataType::GlobeCoordinate',
       'monolingualtext': 'Wikidatum::DataType::MonolingualText',
       'novalue': 'Wikidatum::DataType::NoValue',
@@ -75,6 +58,7 @@ module Wikidatum
       'somevalue': 'Wikidatum::DataType::SomeValue',
       'string': 'Wikidatum::DataType::WikibaseString',
       'time': 'Wikidatum::DataType::Time',
+      'url': 'Wikidatum::DataType::WikibaseUrl',
       'wikibase-item': 'Wikidatum::DataType::WikibaseItem'
     }.freeze
     # rubocop:enable Lint/SymbolConversion

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wikidatum
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Connor Shea
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-28 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -40,6 +40,8 @@ files:
 - lib/wikidatum/client.rb
 - lib/wikidatum/data_type.rb
 - lib/wikidatum/data_type/base.rb
+- lib/wikidatum/data_type/commons_media.rb
+- lib/wikidatum/data_type/external_id.rb
 - lib/wikidatum/data_type/globe_coordinate.rb
 - lib/wikidatum/data_type/monolingual_text.rb
 - lib/wikidatum/data_type/no_value.rb
@@ -48,6 +50,9 @@ files:
 - lib/wikidatum/data_type/time.rb
 - lib/wikidatum/data_type/wikibase_item.rb
 - lib/wikidatum/data_type/wikibase_string.rb
+- lib/wikidatum/data_type/wikibase_url.rb
+- lib/wikidatum/error.rb
+- lib/wikidatum/errors.rb
 - lib/wikidatum/item.rb
 - lib/wikidatum/qualifier.rb
 - lib/wikidatum/reference.rb