wikidata_adaptor 1.0.0

data/lib/wikidata_adaptor/test_helpers/rest_api/support/support.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module WikidataAdaptor
+  module TestHelpers
+    module RestApi
+      # WebMock stubs for Wikibase REST API support utilities
+      module Support
+        # Load the OpenAPI specification from file
+        #
+        # @return [Hash] The parsed OpenAPI specification
+        def load_openapi_spec
+          JSON.parse(
+            File.read(File.join("spec", "openapi", "openapi.json"))
+          )
+        end
+
+        # Load example response from OpenAPI specification for a given path and method
+        #
+        # @param path [String] The API path
+        # @param method [String] The HTTP method
+        # @param response_code [String] The HTTP response code
+        #
+        # @return [Hash] The example response
+        def load_path_example(path, method, response_code = "200")
+          load_openapi_spec.dig(
+            "paths",
+            path,
+            method,
+            "responses",
+            response_code,
+            "content",
+            "application/json",
+            "example"
+          )
+        end
+
+        # Fixture for a posted item response
+        #
+        # @return [Hash] The posted item response fixture
+        def posted_item_response_fixture
+          {
+            "id" => "Q24",
+            "type" => "item",
+            "labels" => {
+              "en" => "Jane Doe",
+              "ru" => "Джейн Доу"
+            },
+            "descriptions" => {
+              "en" => "famous person",
+              "ru" => "известная личность"
+            },
+            "aliases" => {
+              "en" => [
+                "Jane M. Doe",
+                "JD"
+              ],
+              "ru" => [
+                "Джейн М. Доу"
+              ]
+            },
+            "statements" => {
+              "P694" => [
+                {
+                  "id" => "Q24$BB728546-A400-4116-A772-16D54B62AC2B",
+                  "rank" => "normal",
+                  "property" => {
+                    "id" => "P694",
+                    "data_type" => "wikibase-item"
+                  },
+                  "value" => {
+                    "type" => "value",
+                    "content" => "Q626683"
+                  },
+                  "qualifiers" => [],
+                  "references" => []
+                }
+              ],
+              "P476" => [
+                {
+                  "id" => "Q24$F3B2F956-B6AB-4984-8D89-BEE0FFFA3385",
+                  "rank" => "normal",
+                  "property" => {
+                    "id" => "P476",
+                    "data_type" => "time"
+                  },
+                  "value" => {
+                    "type" => "value",
+                    "content" => {
+                      "time" => "+1986-01-27T00:00:00Z",
+                      "precision" => 11,
+                      "calendarmodel" => "http://www.wikidata.org/entity/Q1985727"
+                    }
+                  },
+                  "qualifiers" => [],
+                  "references" => []
+                }
+              ],
+              "P17" => [
+                {
+                  "id" => "Q24$9966A1CA-F3F5-4B1D-A534-7CD5953169DA",
+                  "rank" => "normal",
+                  "property" => {
+                    "id" => "P17",
+                    "data_type" => "string"
+                  },
+                  "value" => {
+                    "type" => "value",
+                    "content" => "Senior Team Supervisor"
+                  },
+                  "qualifiers" => [
+                    {
+                      "property" => {
+                        "id" => "P706",
+                        "data_type" => "time"
+                      },
+                      "value" => {
+                        "type" => "value",
+                        "content" => {
+                          "time" => "+2023-06-13T00:00:00Z",
+                          "precision" => 11,
+                          "calendarmodel" => "http://www.wikidata.org/entity/Q1985727"
+                        }
+                      }
+                    }
+                  ],
+                  "references" => [
+                    {
+                      "hash" => "7ccd777f870b71a4c5056c7fd2a83a22cc39be6d",
+                      "parts" => [
+                        {
+                          "property" => {
+                            "id" => "P709",
+                            "data_type" => "url"
+                          },
+                          "value" => {
+                            "type" => "value",
+                            "content" => "https://news.example.org"
+                          }
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            "sitelinks" => {
+              "enwiki" => {
+                "title" => "Jane Doe",
+                "badges" => [],
+                "url" => "https://enwiki.example.org/wiki/Jane_Doe"
+              },
+              "ruwiki" => {
+                "title" => "Джейн Доу",
+                "badges" => [],
+                "url" => "https://ruwiki.example.org/wiki/Джейн_Доу"
+              }
+            }
+          }
+        end
+
+        # Fixture for a posted property response
+        #
+        # @return [Hash] The posted property response fixture
+        def posted_property_response_fixture
+          {
+            "id" => "P1",
+            "type" => "property",
+            "data_type" => "string",
+            "labels" => {
+              "en" => "instance of"
+            },
+            "descriptions" => {
+              "en" => "that class of which this subject is a particular example and member"
+            },
+            "aliases" => {
+              "en" => ["is a"]
+            },
+            "statements" => {}
+          }
+        end
+
+        # Fixture for a property creation payload
+        #
+        # @return [Hash] The posted property payload fixture
+        def posted_property_payload_fixture
+          {
+            "property" => {
+              "data_type" => "string",
+              "labels" => {
+                "en" => "instance of"
+              },
+              "descriptions" => {
+                "en" => "that class of which this subject is a particular example and member"
+              },
+              "aliases" => {
+                "en" => ["is a"]
+              }
+            },
+            "comment" => "Create a Property"
+          }
+        end
+
+        # Fixture for an item creation payload
+        #
+        # @return [Hash] The posted item payload fixture
+        def posted_item_payload_fixture
+          {
+            "item" => {
+              "labels" => {
+                "en" => "Jane Doe",
+                "ru" => "Джейн Доу"
+              },
+              "descriptions" => {
+                "en" => "famous person",
+                "ru" => "известная личность"
+              },
+              "aliases" => {
+                "en" => [
+                  "Jane M. Doe",
+                  "JD"
+                ],
+                "ru" => [
+                  "Джейн М. Доу"
+                ]
+              },
+              "statements" => {
+                "P694" => [
+                  {
+                    "property" => {
+                      "id" => "P694"
+                    },
+                    "value" => {
+                      "type" => "value",
+                      "content" => "Q626683"
+                    }
+                  }
+                ],
+                "P476" => [
+                  {
+                    "property" => {
+                      "id" => "P476"
+                    },
+                    "value" => {
+                      "type" => "value",
+                      "content" => {
+                        "time" => "+1986-01-27T00:00:00Z",
+                        "precision" => 11,
+                        "calendarmodel" => "http://www.wikidata.org/entity/Q1985727"
+                      }
+                    }
+                  }
+                ],
+                "P17" => [
+                  {
+                    "property" => {
+                      "id" => "P17"
+                    },
+                    "value" => {
+                      "type" => "value",
+                      "content" => "Senior Team Supervisor"
+                    },
+                    "qualifiers" => [
+                      {
+                        "property" => {
+                          "id" => "P706"
+                        },
+                        "value" => {
+                          "type" => "value",
+                          "content" => {
+                            "time" => "+2023-06-13T00:00:00Z",
+                            "precision" => 11,
+                            "calendarmodel" => "http://www.wikidata.org/entity/Q1985727"
+                          }
+                        }
+                      }
+                    ],
+                    "references" => [
+                      {
+                        "parts" => [
+                          {
+                            "property" => {
+                              "id" => "P709"
+                            },
+                            "value" => {
+                              "type" => "value",
+                              "content" => "https://news.example.org"
+                            }
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              },
+              "sitelinks" => {
+                "enwiki" => {
+                  "title" => "Jane Doe"
+                },
+                "ruwiki" => {
+                  "title" => "Джейн Доу"
+                }
+              }
+            },
+            "comment" => "Create an Item for Jane Doe"
+          }
+        end
+      end
+    end
+  end
+end

data/lib/wikidata_adaptor/test_helpers/rest_api.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "webmock"
+
+module WikidataAdaptor
+  # Test helpers for stubbing WikidataAdaptor API calls in tests
+  module TestHelpers
+    # WebMock stubs for the Wikibase REST API
+    #
+    # Include this module in your RSpec tests to access stub methods
+    # for all Wikibase REST API endpoints.
+    #
+    # @example
+    #   RSpec.describe MyClass do
+    #     include WikidataAdaptor::TestHelpers::RestApi
+    #
+    #     it "fetches an item" do
+    #       stub_get_item("Q42")
+    #       # ...
+    #     end
+    #   end
+    module RestApi
+      require_relative "rest_api/open_api_document"
+      require_relative "rest_api/aliases"
+      require_relative "rest_api/items"
+      require_relative "rest_api/sitelinks"
+      require_relative "rest_api/properties"
+      require_relative "rest_api/labels"
+      require_relative "rest_api/descriptions"
+      require_relative "rest_api/statements"
+      require_relative "rest_api/property_data_types"
+      require_relative "rest_api/search_item"
+      require_relative "rest_api/search_property"
+      include WikidataAdaptor::TestHelpers::RestApi::OpenApiDocument
+      include WikidataAdaptor::TestHelpers::RestApi::Aliases
+      include WikidataAdaptor::TestHelpers::RestApi::Items
+      include WikidataAdaptor::TestHelpers::RestApi::Sitelinks
+      include WikidataAdaptor::TestHelpers::RestApi::Properties
+      include WikidataAdaptor::TestHelpers::RestApi::Labels
+      include WikidataAdaptor::TestHelpers::RestApi::Descriptions
+      include WikidataAdaptor::TestHelpers::RestApi::Statements
+      include WikidataAdaptor::TestHelpers::RestApi::PropertyDataTypes
+      include WikidataAdaptor::TestHelpers::RestApi::SearchItem
+      include WikidataAdaptor::TestHelpers::RestApi::SearchProperty
+
+      # Default test endpoint for stubbed requests
+      WIKIBASE_REST_ENDPOINT = ENV["WIKIBASE_REST_ENDPOINT"] || "https://test.test/w/rest.php/wikibase"
+
+      # Stub a Wikibase REST API request with WebMock
+      #
+      # This is the base method used by all specific stub_* helpers.
+      # Use the specific stub methods instead of calling this directly.
+      #
+      # @param [Symbol] method HTTP method (:get, :post, :put, :patch, :delete)
+      # @param [String] path API path (e.g., "/v1/entities/items/Q42")
+      # @param [Hash] with Optional request matching criteria
+      # @param [Integer] response_status HTTP status code to return
+      # @param [Hash] response_headers HTTP headers to return
+      # @param [Hash, Array, String] response_body Response body
+      # @param [String, nil] session Optional session token
+      #
+      # @return [WebMock::RequestStub] The configured stub
+      def stub_rest_api_request(method, path, with: {}, response_status: 200, response_headers: {}, response_body: {}, session: nil)
+        with.merge!(headers: { WikidataAdaptor::RestApi::AUTH_HEADER_NAME => session }) if session
+        session = nil if response_status >= 400
+        to_return = { status: response_status, headers: response_headers, body: prepare_response(response_body, session) }
+        if with.empty?
+          stub_request(method, "#{WIKIBASE_REST_ENDPOINT}#{path}").to_return(**to_return)
+        else
+          stub_request(method, "#{WIKIBASE_REST_ENDPOINT}#{path}").with(**with).to_return(**to_return)
+        end
+      end
+
+      private
+
+      def prepare_response(response_body, session)
+        case response_body
+        when Hash
+          response_body.merge(session: session).compact.to_json
+        when Array
+          response_body.to_json
+        else # String or other
+          response_body
+        end
+      end
+    end
+  end
+end

data/lib/wikidata_adaptor/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module WikidataAdaptor
+  # Gem version
+  VERSION = "1.0.0"
+end

data/lib/wikidata_adaptor.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "api_adaptor"
+
+require_relative "wikidata_adaptor/version"
+require_relative "wikidata_adaptor/rest_api"
+
+module WikidataAdaptor
+  # Base error class for WikidataAdaptor exceptions
+  class Error < StandardError; end
+
+  # Get the Wikibase REST API endpoint URL
+  #
+  # Reads from the WIKIBASE_REST_ENDPOINT environment variable,
+  # defaulting to the production Wikidata endpoint.
+  #
+  # @return [String] The base URL for the Wikibase REST API
+  def self.rest_endpoint
+    ENV["WIKIBASE_REST_ENDPOINT"] || "https://www.wikidata.org/w/rest.php/wikibase"
+  end
+
+  # Creates a WikidataAdaptor::RestApi adapter
+  #
+  # @return [WikidataAdaptor::RestApi]
+  def self.rest_api
+    WikidataAdaptor::RestApi.new(rest_endpoint)
+  end
+end

data/sig/wikidata_adaptor.rbs

@@ -0,0 +1,4 @@
+module WikidataAdaptor
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: wikidata_adaptor
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Huw Diprose
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: api_adaptor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+description: Use the Wikibase Action and REST API to interact with wikidata
+email:
+- mail@huwdiprose.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.test"
+- ".rspec"
+- ".rubocop.yml"
+- ".yardopts"
+- CHANGELOG.md
+- CLAUDE.md
+- CODE_OF_CONDUCT.md
+- COVERAGE.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- integration/.env.example
+- integration/README.md
+- integration/config/99_IntegrationTesting.php
+- integration/config/wikibase-php.ini
+- integration/docker-compose.yml
+- lib/wikidata_adaptor.rb
+- lib/wikidata_adaptor/rest_api.rb
+- lib/wikidata_adaptor/rest_api/aliases.rb
+- lib/wikidata_adaptor/rest_api/descriptions.rb
+- lib/wikidata_adaptor/rest_api/items.rb
+- lib/wikidata_adaptor/rest_api/labels.rb
+- lib/wikidata_adaptor/rest_api/open_api_document.rb
+- lib/wikidata_adaptor/rest_api/properties.rb
+- lib/wikidata_adaptor/rest_api/property_data_types.rb
+- lib/wikidata_adaptor/rest_api/search_item.rb
+- lib/wikidata_adaptor/rest_api/search_property.rb
+- lib/wikidata_adaptor/rest_api/sitelinks.rb
+- lib/wikidata_adaptor/rest_api/statements.rb
+- lib/wikidata_adaptor/test_helpers/rest_api.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/aliases.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/descriptions.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/items.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/labels.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/open_api_document.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/properties.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/property_data_types.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/search_item.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/search_property.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/sitelinks.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/statements.rb
+- lib/wikidata_adaptor/test_helpers/rest_api/support/support.rb
+- lib/wikidata_adaptor/version.rb
+- sig/wikidata_adaptor.rbs
+homepage: https://github.com/huwd/wikidata_adaptor
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/huwd/wikidata_adaptor
+  source_code_uri: https://github.com/huwd/wikidata_adaptor
+  changelog_uri: https://github.com/huwd/wikidata_adaptor/blob/main/CHANGELOG.md
+  documentation_uri: https://huwd.github.io/wikidata_adaptor/
+  bug_tracker_uri: https://github.com/huwd/wikidata_adaptor/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: An API wrapper to interact with Wikidata and Wikibase APIs
+test_files: []