wikidatum 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcaa080ee9ab979f63dbde3fc8bca7f819ffd47b0a7d463c5f34bd57e1f2a988
-  data.tar.gz: c0226585d7af46f01c7127b7de8ec13cc22a593f414431acd3ec11f580425b88
+  metadata.gz: 524da97907bba148830e9191d3c0ba5c614ddbee6c50fd74c6e91595082e73bd
+  data.tar.gz: 2321efe8c69e953521dbe5f4da51725fd6183ac871e7c00a17c552c12dc15dc2
 SHA512:
-  metadata.gz: '058da6289ed70d623511a2732b3c83c4d1b574aadc8570cbceee83c23df7adf71ef34e8413783cc1c0e9173c8ea7fcbb419d01b9fd58816278614bfd2f10e83f'
-  data.tar.gz: 0a0220e396643884380d858b0fe4cd4ab867f5f3a7ff92ccbbc54440ac4668f490a172f7244d567b093cd753044f845ced5daae3482514fa897cb0a42234ffe6
+  metadata.gz: 634701e7e5204ea770eb114f62982140e3441358e71f1ca32bf38718f9e72f29fe582340546c28e0dad4e575903c6822057bb12f21572333c68cd6c28b2f1e46
+  data.tar.gz: 26cf62b267be9bb4a6cc752d1968740b3d153f972204f0b1d7900fa7e087cea6eef0e543972b3aafb22f98ffbea8cdc6e30f22cc30f34aa77d2f4d1605655d02

data/CHANGELOG.md

@@ -6,6 +6,15 @@ 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
 

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

@@ -23,6 +23,19 @@ module Wikidatum
       '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
     #   with. If not provided, will default to Wikidata.
     attr_reader :wikibase_url
@@ -55,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
@@ -96,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
@@ -113,19 +151,6 @@ 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
@@ -489,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

@@ -26,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

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.2'
+  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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wikidatum
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Connor Shea
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-29 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -51,6 +51,8 @@ files:
 - 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