wikidata_adaptor 1.0.0

data/Gemfile.lock

@@ -0,0 +1,124 @@
+PATH
+  remote: .
+  specs:
+    wikidata_adaptor (1.0.0)
+      api_adaptor (>= 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    api_adaptor (1.0.0)
+      addressable (~> 2.8)
+      base64 (~> 0.3)
+      bigdecimal (>= 3.3, < 5.0)
+      link_header (~> 0.0.8)
+      logger (>= 1.6, < 2.0)
+      rest-client (~> 2.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    domain_name (0.6.20240107)
+    dotenv (3.2.0)
+    hashdiff (1.2.1)
+    http-accept (1.7.0)
+    http-cookie (1.1.0)
+      domain_name (~> 0.5)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
+    link_header (0.0.8)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.0127)
+    netrc (0.11.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    redcarpet (3.6.1)
+    regexp_parser (2.11.3)
+    rest-client (2.1.0)
+      http-accept (>= 1.7.0, < 2.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 4.0)
+      netrc (~> 0.8)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    rubocop-yard (1.1.0)
+      lint_roller
+      rubocop (~> 1.72)
+      yard
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  dotenv (= 3.2.0)
+  rake (~> 13.0)
+  redcarpet (~> 3.6)
+  rspec (~> 3.0)
+  rubocop (~> 1.84)
+  rubocop-rake
+  rubocop-rspec
+  rubocop-yard
+  webmock (~> 3.17)
+  wikidata_adaptor!
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.5.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Huw Diprose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,269 @@
+# WikidataAdaptor
+
+[![Quality Checks](https://github.com/huwd/wikidata_adaptor/actions/workflows/quality-checks.yml/badge.svg)](https://github.com/huwd/wikidata_adaptor/actions/workflows/quality-checks.yml)
+[![Documentation](https://github.com/huwd/wikidata_adaptor/actions/workflows/docs.yml/badge.svg)](https://github.com/huwd/wikidata_adaptor/actions/workflows/docs.yml)
+
+A Ruby gem providing a clean, well-documented interface to the [Wikibase REST API](https://doc.wikimedia.org/Wikibase/master/js/rest-api/). Interact with Wikidata and other Wikibase instances to read and write structured data.
+
+## Features
+
+- **100% API coverage** - All 65 endpoints from Wikibase REST API v1.4
+- **Fully documented** - 100% YARD documentation coverage
+- **Well-tested** - Comprehensive unit and integration test suites
+- **Structured JSON responses** - Consistent response shapes from the API
+- **Test helpers included** - WebMock stubs for easy testing in your applications
+
+Supported operations:
+- **Items & Properties** - Create, read, update (GET, POST, PATCH)
+- **Labels** - Multi-language labels with fallback support (GET, PUT, PATCH, DELETE)
+- **Descriptions** - Multi-language descriptions (GET, PUT, PATCH, DELETE)
+- **Aliases** - Alternative names in multiple languages (GET, POST, PATCH)
+- **Statements** - Claims and references (GET, POST, PUT, PATCH, DELETE)
+- **Sitelinks** - Links to related wiki pages (GET, PUT, PATCH, DELETE)
+- **Search** - Full-text search and autocomplete suggestions
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "wikidata_adaptor"
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install wikidata_adaptor
+```
+
+## Quick Start
+
+```ruby
+require "wikidata_adaptor"
+
+# Create a client
+client = WikidataAdaptor.rest_api
+
+# Get an item (Douglas Adams - Q42)
+item = client.get_item("Q42")
+puts item["labels"]["en"]  # => "Douglas Adams"
+
+# Get labels in a specific language
+labels = client.get_item_labels("Q42")
+puts labels["en"]  # => "Douglas Adams"
+puts labels["fr"]  # => "Douglas Adams"
+
+# Search for items
+results = client.search_items("Douglas Adams")
+results.each do |result|
+  puts "#{result['id']}: #{result['label']}"
+end
+```
+
+## Documentation
+
+- **[API Documentation](https://huwd.github.io/wikidata_adaptor/)** - Full YARD documentation
+- **[Wikibase REST API Reference](https://doc.wikimedia.org/Wikibase/master/js/rest-api/)** - Official API docs
+- **[CHANGELOG](CHANGELOG.md)** - Version history and changes
+
+## Usage
+
+### Reading Data
+
+```ruby
+# Get an item with all its data
+item = client.get_item("Q42")
+
+# Get specific language label
+label = client.get_item_label("Q42", "en")
+
+# Get label with language fallback
+label = client.get_item_label_with_language_fallback("Q42", "en-gb")
+
+# Get descriptions
+desc = client.get_item_description("Q42", "en")
+
+# Get aliases
+aliases = client.get_item_aliases("Q42")
+
+# Get statements (claims)
+statements = client.get_item_statements("Q42")
+
+# Filter statements by property
+statements = client.get_item_statements("Q42", property: "P31")  # instance of
+```
+
+### Search
+
+```ruby
+# Full-text search
+results = client.search_items("Albert Einstein")
+
+# Autocomplete suggestions
+suggestions = client.suggest_items("Einst")
+
+# Search properties
+properties = client.search_properties("instance of")
+```
+
+### Writing Data (requires authentication)
+
+```ruby
+# Configure an authenticated REST API client with a bearer token
+rest_api = WikidataAdaptor::RestApi.new(
+  "https://www.wikidata.org/w/rest.php/wikibase",
+  bearer_token: "your_oauth_token"
+)
+
+# Build a WikidataAdaptor client using the authenticated REST API instance
+client = WikidataAdaptor::Client.new(rest_api: rest_api)
+# Create a new item
+new_item = client.post_item({
+  item: {
+    labels: { en: "My New Item" },
+    descriptions: { en: "A test item" }
+  },
+  comment: "Creating test item"
+})
+
+# Update a label
+client.put_item_label("Q42", "en", {
+  label: "Douglas Noël Adams",
+  comment: "Adding middle name"
+})
+
+# Add a statement
+client.post_item_statement("Q42", {
+  statement: {
+    property: { id: "P31" },
+    value: { content: "Q5", type: "item" }
+  },
+  comment: "Adding instance of human"
+})
+
+# Delete a label
+client.delete_item_label("Q42", "en", {
+  comment: "Removing English label"
+})
+```
+
+### Using Different Wikibase Instances
+
+By default, the gem connects to Wikidata. To use a different Wikibase instance:
+
+```ruby
+ENV["WIKIBASE_REST_ENDPOINT"] = "https://your-wikibase.org/w/rest.php/wikibase"
+client = WikidataAdaptor.rest_api
+```
+
+### Test Helpers
+
+The gem includes WebMock test helpers for easy testing:
+
+```ruby
+require "wikidata_adaptor/test_helpers/rest_api"
+
+RSpec.describe MyClass do
+  include WikidataAdaptor::TestHelpers::RestApi
+
+  it "fetches an item" do
+    stub_get_item("Q42")  # Stubs the API call
+
+    result = MyClass.fetch_item("Q42")
+    expect(result["labels"]["en"]).to eq("Douglas Adams")
+  end
+end
+```
+
+See the [test helpers documentation](https://huwd.github.io/wikidata_adaptor/WikidataAdaptor/TestHelpers/RestApi.html) for all available stubs.
+
+## Development
+
+After checking out the repository:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake           # Run all tests + RuboCop
+bundle exec rspec          # Run unit tests only
+bundle exec rubocop        # Run linter only
+
+# Generate documentation
+bundle exec rake yard
+
+# Run integration tests (requires Docker)
+./script/integration-up    # Start Wikibase instance
+./script/integration-test  # Run integration tests
+./script/integration-down  # Stop Wikibase instance
+```
+
+### Project Structure
+
+```
+lib/
+├── wikidata_adaptor/
+│   ├── rest_api.rb              # Main client class
+│   ├── rest_api/                # API endpoint modules
+│   │   ├── items.rb
+│   │   ├── labels.rb
+│   │   ├── statements.rb
+│   │   └── ...
+│   └── test_helpers/            # WebMock test stubs
+│       └── rest_api/
+│           ├── items.rb
+│           ├── labels.rb
+│           └── ...
+spec/
+├── wikidata_adaptor/rest_api/  # Unit tests
+└── integration/                 # Integration tests
+```
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Bundler
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/huwd/wikidata_adaptor).
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Make your changes with tests
+4. Ensure all tests pass (`bundle exec rake`)
+5. Commit following [commit conventions](CLAUDE.md#commit-standards)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a Pull Request
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+
+See [CLAUDE.md](CLAUDE.md) for detailed development guidelines including:
+- Commit standards (Conventional Commits)
+- Git workflow (branch/PR process)
+- TDD workflow
+- Testing conventions
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Code of Conduct
+
+Everyone interacting in the WikidataAdaptor project is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Links
+
+- [Documentation](https://huwd.github.io/wikidata_adaptor/)
+- [Source Code](https://github.com/huwd/wikidata_adaptor)
+- [Issue Tracker](https://github.com/huwd/wikidata_adaptor/issues)
+- [Changelog](CHANGELOG.md)
+- [Wikibase REST API](https://doc.wikimedia.org/Wikibase/master/js/rest-api/)
+- [Wikidata](https://www.wikidata.org/)

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "yard"
+
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.stats_options = ["--list-undoc"]
+end
+
+task default: %i[spec rubocop]

data/integration/.env.example

@@ -0,0 +1,20 @@
+# Copy to integration/.env (optional) and adjust as needed.
+#
+# This stack is intended for local integration testing.
+
+WIKIBASE_PORT=8080
+MW_WG_SITENAME=Wikibase
+MW_ADMIN_NAME=admin
+MW_ADMIN_PASS=integration-admin-12345
+MW_ADMIN_EMAIL=admin@example.org
+MW_WG_SERVER=http://localhost:8080
+
+# Required by wikibase/wikibase image on first boot
+METADATA_CALLBACK=false
+
+DB_NAME=my_wiki
+DB_USER=wikiuser
+DB_PASS=wikpass
+
+# Lowering memory can speed up startup on small machines, but too low will crash ES.
+ES_JAVA_OPTS=-Xms512m -Xmx512m -Dlog4j2.formatMsgNoLookups=true

data/integration/README.md

@@ -0,0 +1,58 @@
+# Integration tests
+
+This repo’s default RSpec suite uses WebMock and stubs requests.
+
+For end-to-end verification against a real Wikibase instance, run the integration suite.
+
+## Prereqs
+
+- Docker + Docker Compose (v2)
+- A running Wikibase instance exposing the REST API at `.../w/rest.php/wikibase`
+  - You can use the provided `integration/docker-compose.yml` (core-only; no WDQS/SPARQL)
+- `WIKIBASE_REST_ENDPOINT` set to that base URL (defaults to `http://localhost:8080/w/rest.php/wikibase`)
+- If your Wikibase requires authentication for writes, set `WIKIBASE_BEARER_TOKEN`
+
+## Running
+
+### Bring up local Wikibase (recommended)
+
+```bash
+cp integration/.env.example integration/.env
+./script/integration-up
+```
+
+If `wikibase` fails to start with `METADATA_CALLBACK not configured`, make sure
+`METADATA_CALLBACK=false` is present in `integration/.env`.
+
+If the MediaWiki installer rejects `MW_ADMIN_PASS`, pick a less common password
+of at least 10 characters in `integration/.env`.
+
+### Run integration specs
+
+```bash
+INTEGRATION=1 \
+WIKIBASE_REST_ENDPOINT=http://localhost:8080/w/rest.php/wikibase \
+WIKIBASE_BEARER_TOKEN=... \
+bundle exec rspec --tag integration
+```
+
+Or:
+
+```bash
+./script/integration-test
+```
+
+### Tear down
+
+```bash
+./script/integration-down
+```
+
+## Notes
+
+- The integration tests currently seed data via `POST /v1/entities/items` and then validate read-only endpoints.
+- If you prefer seeding without write access, we can switch to a container-side import step instead.
+
+## Performance
+
+This stack omits WDQS/SPARQL and traefik to start faster.

data/integration/config/99_IntegrationTesting.php

@@ -0,0 +1,3 @@
+<?php
+# Disable rate limits for integration testing
+$wgRateLimits = [];

data/integration/config/wikibase-php.ini

@@ -0,0 +1,15 @@
+; ##############################################################################
+; Wikibase Suite PHP settings
+; ##############################################################################
+; Feel free to adjust those settings according your needs.
+; Changes will be picked up automatically by the wikibase container on restart.
+
+; Set the PHP upload limits be the same as the MediaWiki default of 100M.
+; Should match the wgMaxUploadSize setting in LocalSettings.php
+file_uploads = On
+upload_max_filesize = 100M
+post_max_size = 100M
+
+; Set the PHP memory and execution limits
+memory_limit = 100M
+max_execution_time = 600

data/integration/docker-compose.yml

@@ -0,0 +1,98 @@
+name: wikidata-adaptor-integration
+
+# Core-only Wikibase stack based on:
+# https://github.com/wmde/wikibase-release-pipeline/blob/main/deploy/docker-compose.yml
+#
+# Intentionally omitted for speed:
+# - WDQS / SPARQL (wdqs, wdqs-updater, wdqs-frontend)
+# - traefik
+# - quickstatements
+
+services:
+  mysql:
+    image: mariadb:10.11
+    restart: unless-stopped
+    environment:
+      MYSQL_DATABASE: ${DB_NAME:-my_wiki}
+      MYSQL_USER: ${DB_USER:-wikiuser}
+      MYSQL_PASSWORD: ${DB_PASS:-wikpass}
+      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
+    volumes:
+      - mysql-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      start_period: 60s
+      interval: 10s
+      timeout: 5s
+      retries: 20
+
+  elasticsearch:
+    image: wikibase/elasticsearch:1
+    restart: unless-stopped
+    environment:
+      discovery.type: single-node
+      ES_JAVA_OPTS: ${ES_JAVA_OPTS:--Xms512m -Xmx512m -Dlog4j2.formatMsgNoLookups=true}
+    volumes:
+      - elasticsearch-data:/usr/share/elasticsearch/data
+    healthcheck:
+      test: ["CMD", "curl", "--silent", "--fail", "http://localhost:9200"]
+      start_period: 120s
+      interval: 10s
+      timeout: 5s
+      retries: 20
+
+  wikibase:
+    image: wikibase/wikibase:5
+    depends_on:
+      mysql:
+        condition: service_healthy
+      elasticsearch:
+        condition: service_healthy
+    restart: unless-stopped
+    ports:
+      - "${WIKIBASE_PORT:-8080}:80"
+    volumes:
+      # Optional: mount custom config if you need to tweak LocalSettings.
+      - ./config:/config:rw
+      - ./config/99_IntegrationTesting.php:/var/www/html/LocalSettings.d/99_IntegrationTesting.php:ro
+      - wikibase-image-data:/var/www/html/images
+    environment:
+      # Required by the wikibase/wikibase image on first boot
+      METADATA_CALLBACK: ${METADATA_CALLBACK:-false}
+
+      MW_WG_SITENAME: ${MW_WG_SITENAME:-Wikibase}
+      MW_ADMIN_NAME: ${MW_ADMIN_NAME:-admin}
+      # MediaWiki enforces password strength requirements on first install.
+      MW_ADMIN_PASS: ${MW_ADMIN_PASS:-integration-admin-12345}
+      MW_ADMIN_EMAIL: ${MW_ADMIN_EMAIL:-admin@example.org}
+      # When running locally without a reverse proxy, keep this http.
+      MW_WG_SERVER: ${MW_WG_SERVER:-http://localhost:${WIKIBASE_PORT:-8080}}
+
+      DB_SERVER: mysql:3306
+      DB_USER: ${DB_USER:-wikiuser}
+      DB_PASS: ${DB_PASS:-wikpass}
+      DB_NAME: ${DB_NAME:-my_wiki}
+
+      ELASTICSEARCH_HOST: elasticsearch
+    healthcheck:
+      test:
+        ["CMD", "curl", "--silent", "--fail", "http://localhost/wiki/Main_Page"]
+      interval: 10s
+      start_period: 300s
+      timeout: 5s
+      retries: 30
+
+  wikibase-jobrunner:
+    image: wikibase/wikibase:5
+    command: /jobrunner-entrypoint.sh
+    depends_on:
+      wikibase:
+        condition: service_healthy
+    restart: unless-stopped
+    volumes_from:
+      - wikibase
+
+volumes:
+  mysql-data:
+  elasticsearch-data:
+  wikibase-image-data: