wikidatum 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78bb68e7872a77e0dc21f9904d0fd8306b4d4caa23329824d87257a91e503925
-  data.tar.gz: 84765a7d5f3cee85b0c6ad68953f1d6e9718d068037247f8e8e7e1c4b651c51b
+  metadata.gz: bcaa080ee9ab979f63dbde3fc8bca7f819ffd47b0a7d463c5f34bd57e1f2a988
+  data.tar.gz: c0226585d7af46f01c7127b7de8ec13cc22a593f414431acd3ec11f580425b88
 SHA512:
-  metadata.gz: 24dd512b025f3e618b46ba9b5cc280c2ef500909b7f68c666f29914b5a64e1da63729ded4e321e37461f68f6fdc1f429ec87a71684b773eacb5f25f56ee5c212
-  data.tar.gz: e43e1b92d171667ce5af5028c56b7d5c28971ef3c3aed93f55a919088e6a990796889eb32293563191d857cf547ca685b6d571bc629a199cbbb6ab332283a731
+  metadata.gz: '058da6289ed70d623511a2732b3c83c4d1b574aadc8570cbceee83c23df7adf71ef34e8413783cc1c0e9173c8ea7fcbb419d01b9fd58816278614bfd2f10e83f'
+  data.tar.gz: 0a0220e396643884380d858b0fe4cd4ab867f5f3a7ff92ccbbc54440ac4668f490a172f7244d567b093cd753044f845ced5daae3482514fa897cb0a42234ffe6

data/CHANGELOG.md

@@ -4,11 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## Unreleased
+
+## 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
+
+- Add an error message when attempting to make a bot edit without authentication, as this will always trigger a 403 error from the REST API.
+
+### Fixed
+
+- Fix the creation of WikibaseItem statements, the format used in the previous release was incorrect.
+
 ## 0.3.0 - 2022-12-27
 ### Added
 
 - Add `allow_ip_edits` argument on `Wikidatum::Client.new`. This protects users from making IP address-exposing edits if they haven't explicitly opted-in to doing that. The argument defaults to false.
 - Add code to raise errors when various types of invalid input are passed to `Wikidatum::Client#add_statement`.
+- Start testing the gem on Ruby 3.2.
 
 ### Fixed
 

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,8 @@ module Wikidatum
       'Wikidatum::DataType::SomeValue',
       'Wikidatum::DataType::Time',
       'Wikidatum::DataType::WikibaseItem',
-      'Wikidatum::DataType::WikibaseString'
+      'Wikidatum::DataType::WikibaseString',
+      'Wikidatum::DataType::WikibaseUrl'
     ].freeze
 
     # @return [String] the root URL of the Wikibase instance we want to interact
@@ -110,6 +113,19 @@ module Wikidatum
       Wikidatum::Statement.marshal_load(response)
     end
 
+    # @!private
+    CONTENT_DATA_TYPES = [
+      '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'
+    ].freeze
+
     # Add a statement to an item.
     #
     # NOTE: Adding references/qualifiers with `add_statement` is untested and
@@ -195,9 +211,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 +276,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
@@ -245,7 +288,15 @@ module Wikidatum
         }
       end
 
-      body = { statement: statement_hash.merge({ qualifiers: qualifiers, references: references, rank: rank.to_s, type: 'statement' }) }
+      body = {
+        statement: statement_hash.merge(
+          {
+            qualifiers: qualifiers,
+            references: references,
+            rank: rank.to_s
+          }
+        )
+      }
 
       response = post_request("/entities/items/#{id}/statements", body, tags: tags, comment: comment)
 
@@ -292,6 +343,13 @@ module Wikidatum
       @allow_ip_edits
     end
 
+    # Is the current instance of Client editing as a bot?
+    #
+    # @return [Boolean]
+    def bot?
+      @bot
+    end
+
     private
 
     # For now this just returns the `@wikibase_url`, but in the future the API
@@ -426,13 +484,15 @@ module Wikidatum
     # Check if authentication has been provided, and then check if IP edits
     # are allowed. If neither condition returns true, raise an error.
     #
+    # Also check if the user is performing IP edits as a bot, which will
+    # always return a 403 error from the REST API, and return a specific
+    # error message if so.
+    #
     # @return [void]
-    # @raise [DisallowedIpEditError]
+    # @raise [DisallowedIpEditError, DisallowedBotEditError]
     def ensure_edit_permitted!
-      return if authenticated?
-      return if allow_ip_edits?
-
-      raise DisallowedIpEditError
+      raise DisallowedIpEditError if !authenticated? && !allow_ip_edits?
+      raise 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]
@@ -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
@@ -57,8 +65,6 @@ class Wikidatum::DataType::WikibaseItem
 
   # @!visibility private
   def marshal_dump
-    {
-      id: @id
-    }
+    @id
   end
 end

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/version.rb

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

data/lib/wikidatum.rb

@@ -24,6 +24,15 @@ module Wikidatum
     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
@@ -56,9 +65,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',
@@ -66,6 +76,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.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Connor Shea
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-28 00:00:00.000000000 Z
+date: 2022-12-29 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,7 @@ 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/item.rb
 - lib/wikidatum/qualifier.rb
 - lib/wikidatum/reference.rb