mediawiki-gateway 0.6.2 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2024bd23d67918a2bf7d38216a70da0bf8f60cb4
-  data.tar.gz: a0a8252820764951697436d9b957126b4f9f3c83
+  metadata.gz: 5150a41bc6e40dcb57657afdc997e131fa2d870a
+  data.tar.gz: 2de54f26896f811c5deb030ebbbb763d63b567b1
 SHA512:
-  metadata.gz: c84e686ef4362878482dddb8decd812a3886442388fc243c6fe2a35719a1326691ab1d0cd6b0c94c78a07a5004e013761a083877363c34e45035b093f41612f2
-  data.tar.gz: e3e8f94661cae3ba07edba0eb5b2a6a67d41e4359fc620cecb6b4688f8f6db8014eea597aeae2bb493e6ca445d8f1536a362386a126b88a79c83b752a41ccbda
+  metadata.gz: 4dda2f19dc6b2431f052d59b57d1c36990757f1cb1daf4bf3f9a751c78705c13c4e7c778bdd8106c24ea3a9f45f192f336a360f7a260b43b8099969545c1c2a1
+  data.tar.gz: bf221978ac17b5fd4712f5738196f438453bbe5854a26c0e0caa1ec863d9396623aed815677e685ed2e56b29b45a7d778869303b3a1b59928e308e540bb05952

data/COPYING

@@ -0,0 +1,22 @@
+= License for mediawiki-gateway
+
+  Copyright (c) Jani Patokallio and Lonely Planet 2010-2013
+  
+  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/ChangeLog

@@ -0,0 +1,16 @@
+# markup: rd
+
+= Revision history for mediawiki-gateway
+
+== 1.0.0 [unreleased]
+
+* <b>Required Ruby version is now 1.9.3 or higher.</b>
+* For better Unicode support, install the +unicode+ or +activesupport+ gem.
+* API methods are grouped into submodules of MediaWiki::Gateway.
+* MediaWiki::Gateway#send_request allows generic API requests.
+* MediaWiki::Gateway::new learned +user_agent+ option.
+* MediaWiki::Gateway::Query#custom_query is now public.
+* MediaWiki::Gateway#wiki_url attribute is now exposed.
+* Added +mediawiki-gateway+ command-line client.
+* Changed or removed some of the dependencies.
+* Housekeeping and internal refactoring.

data/README.md

@@ -1,58 +1,117 @@
 # MediaWiki::Gateway
 
-A Ruby framework for MediaWiki API manipulation.  Features out of the box:
+A Ruby framework for [MediaWiki API](http://www.mediawiki.org/wiki/API:Main_page) manipulation.
+
+## Features
 
 * Simple, elegant syntax for common operations
-* Handles login, edit, move etc tokens for you
+* Handles login, edit, move etc. tokens for you
 * List, search operations work around API limits to fetch all results
 * Support for maxlag detection and automated retries on 503
 * Integrated logging
 * Tested up to MediaWiki 1.22
-* Should work with both Ruby 1.8 and 1.9
+* Should work with Ruby 1.9.3 and higher
+
+## Links
+
+RubyGem
+: http://rubygems.org/gems/mediawiki-gateway
+
+Documentation
+: http://rubydoc.info/gems/mediawiki-gateway
+
+Source
+: https://github.com/jpatokal/mediawiki-gateway
+
+CI
+: https://travis-ci.org/jpatokal/mediawiki-gateway
 
-Gem:  http://rubygems.org/gems/mediawiki-gateway
+## Installation
 
-RDoc: http://rubydoc.info/gems/mediawiki-gateway
+To install MediaWiki::Gateway, execute the command:
 
-Git:  https://github.com/jpatokal/mediawiki-gateway
+```shell
+$ gem install mediawiki-gateway
+```
 
-## Example
+Or add it to your application's `Gemfile`:
+
+```ruby
+gem 'mediawiki-gateway'
+```
+
+and then execute the command:
+
+```shell
+$ bundle
+```
+
+## Usage
 
 Simple page creation script:
 
-    require 'media_wiki'
-    mw = MediaWiki::Gateway.new('http://my-wiki.example/w/api.php')
-    mw.login('RubyBot', 'pa$$w0rd')
-    mw.create('PageTitle', 'Hello world!', :summary => 'My first page')
+```ruby
+require 'media_wiki'
+mw = MediaWiki::Gateway.new('http://my-wiki.example/w/api.php')
+mw.login('RubyBot', 'pa$$w0rd')
+mw.create('PageTitle', 'Hello world!', summary: 'My first page')
+```
+
+## Changing the default User-Agent
+
+In order to comply with Wikimedia's [User-Agent policy](https://meta.wikimedia.org/wiki/User-Agent_policy), you are strongly advised to provide your own User-Agent header when accessing Wikimedia websites. The User-Agent information should include the name and version of your bot as well as a URL (homepage, repository) and contact e-mail.
+
+You can set the default User-Agent globally:
+
+```ruby
+MediaWiki::Gateway.default_user_agent = 'MyCoolTool/1.1 (http://example.com/MyCoolTool/; MyCoolTool@example.com)'
+```
+
+You can also set it on an instance by instance basis, overriding the global default:
+
+```ruby
+mw = MediaWiki::Gateway.new('http://my-wiki.example/w/api.php', user_agent: 'MyCoolTool/1.1 (http://example.com/MyCoolTool/; MyCoolTool@example.com)')
+```
+
+You only need to provide the part that identifies your own bot, an additional part denoting that your bot is based on MediaWiki::Gateway is appended automatically.
 
 ## Development environment
 
-To compile and test MediaWiki::Gateway locally, Bundler and Ruby 1.9+ are expected.
+To compile and test MediaWiki::Gateway locally, install its development dependencies:
 
-    rvm install 1.9.3-p194
-    bundle install
+```shell
+gem install --development mediawiki-gateway
+```
 
-This will list the available options:
+Then this will list the available options:
 
-    bundle exec rake -T
+```shell
+rake -T
+```
 
 To build and install the gem use:
 
-    bundle exec rake install
+```shell
+rake gem:install
+```
 
 ### Testing against a live MediaWiki instance
 
 You need to have [Docker](https://docker.com) and [mediawiki-testwiki](https://rubygems.org/gems/mediawiki-testwiki) installed.
 
+## Versioning
+
+This project adheres to the [Semantic Versioning Specification](http://semver.org/).
+
 ## Status
 
-This gem is no longer in active development.  Pull requests that fix bugs or add new features are more than welcome, but asking for new features is unlikely to make them materialize out of thin air.
+This gem is no longer in active development. Pull requests that fix bugs or add new features are more than welcome, but asking for new features is unlikely to make them materialize out of thin air.
 
 ## Credits
 
-Loosely maintained by Jani Patokallio and [Jens Wille](https://github.com/blackwinter).  If you'd be seriously interested in joining as an active maintainer, drop us a line!
+Loosely maintained by Jani Patokallio and [Jens Wille](https://github.com/blackwinter). If you'd be seriously interested in joining as an active maintainer, drop us a line!
 
 Thanks to:
-* John Carney, Mike Williams, Daniel Heath and the rest of the Lonely Planet Atlas team.
-* Github users for code contributions, see https://github.com/jpatokal/mediawiki-gateway/pulls
 
+* John Carney, Mike Williams, Daniel Heath and the rest of the Lonely Planet Atlas team.
+* GitHub users for code contributions, see https://github.com/jpatokal/mediawiki-gateway/pulls

data/Rakefile

@@ -1,40 +1,34 @@
-require 'thread'
-require 'rake'
-require "rubygems/package_task"
-require 'rdoc/task'
-require 'rspec/core/rake_task'
-require_relative 'lib/media_wiki'
+require_relative 'lib/media_wiki/version'
 
-task :default => ['spec']
+begin
+  require 'hen'
 
-desc 'generate API documentation to doc/index.html'
+  Hen.lay! {{
+    gem: {
+      name:         %q{mediawiki-gateway},
+      version:      MediaWiki::VERSION,
+      summary:      %q{Connect to the MediaWiki API.},
+      description:  %q{A Ruby framework for MediaWiki API manipulation.},
+      authors:      ['Jani Patokallio', 'Jens Wille'],
+      email:        ['jpatokal@iki.fi', 'jens.wille@gmail.com'],
+      license:      %q{MIT},
+      homepage:     :jpatokal,
+      dependencies: { 'rest-client' => '~> 1.7' },
 
-RDoc::Task.new do |rd|
-  rd.rdoc_dir = 'doc'
-  rd.main = 'README'
-  rd.rdoc_files.include "README", "lib/media_wiki/**/*\.rb", "script/**/*\.rb"
-  rd.options << '--inline-source'
-  rd.options << '--line-numbers'
-  rd.options << '--all'
-end
+      development_dependencies: %w[
+        equivalent-xml
+        nokogiri
+        sham_rack
+        sinatra
+      ],
 
-desc "Run all specs"
-RSpec::Core::RakeTask.new('spec') do |t|
-  t.pattern = FileList['spec/**/*.rb']
-end
+      required_ruby_version: '>= 1.9.3'
+    },
 
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "mediawiki-gateway"
-    gemspec.summary = "Connect to the mediawiki API"
-    gemspec.description = ""
-    gemspec.email = "jpatokal@iki.fi"
-    gemspec.homepage = "http://github.com/jpatokal/mediawiki-gateway"
-    gemspec.authors = ["Jani Patokallio"]
-    gemspec.version = MediaWiki::VERSION
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: gem install jeweler"
+    rdoc: {
+      extra_files: %w[README.md]
+    }
+  }}
+rescue LoadError => err
+  warn "Please install the `hen' gem. (#{err})"
 end

data/bin/mediawiki-gateway

@@ -0,0 +1,203 @@
+#! /usr/bin/env ruby
+
+require 'media_wiki'
+
+require 'optparse'
+require 'yaml'
+
+def mw(options)
+  MediaWiki::Gateway.new(options[:url], loglevel: options[:loglevel]).tap { |mw|
+    mw.login(options[:user], options[:pw]) if options[:user]
+  }
+end
+
+commands = {
+  create_page:     ['Update a MediaWiki article\'s content', lambda { |options|
+    abort 'Article name is mandatory.' unless article = ARGV.shift
+
+    puts mw(options).create(article, ARGF.read, overwrite: true, summary: options[:summary] || 'Automated edit via MediaWiki::Gateway')
+  }],
+  delete_batch:    ['Delete articles in batch', lambda { |options|
+    abort 'Article prefix is mandatory.' unless key = ARGV.shift
+
+    mw = mw(options)
+
+    mw.list(key).each { |title|
+      puts "Deleting #{title}..."
+      mw.delete(title)
+    }
+  }],
+  download_batch:  ['Download images in batch', lambda { |options|
+    mw = mw(options)
+
+    ARGF.each { |image|
+      image.strip!
+      File.write(image, mw.download(image)) unless File.exist?(image)
+    }
+  }],
+  email_user:      ['Send e-mail to a registered user', lambda { |options|
+    user, subject = ARGV.shift, ARGV.shift
+    abort 'User and subject are mandatory.' unless user && subject
+
+    mw(options).email_user(user, subject, ARGF.read)
+  }],
+  export_xml:      ['Export MediaWiki pages as XML', lambda { |options|
+    abort 'User is mandatory.' unless options[:user]
+
+    puts mw(options).export(ARGV)
+  }],
+  get_page:        ['Fetch a page\'s current contents in Wiki markup', lambda { |options|
+    abort 'Article name is mandatory.' unless article = ARGV.shift
+
+    puts mw(options).get(article)
+  }],
+  import_xml:      ['Import a MediaWiki XML dump', lambda { |options|
+    abort 'File name is mandatory.' unless file = ARGV.shift
+
+    mw(options).import(file)
+  }],
+  fake_media_wiki: ['Run a live FakeWiki instance instead of just shamracking it', lambda {
+    require 'media_wiki/fake_wiki'
+
+    MediaWiki::FakeWiki::App.run!(host: 'localhost', port: 9090)
+  }],
+  search_content:  ['Search page contents in a Wiki', lambda { |options|
+    abort 'Search key is mandatory.' unless key = ARGV.shift
+
+    puts mw(options).search(key, nil, 50)
+  }],
+  semantic_query:  ['Query Semantic MediaWiki data', lambda { |options|
+    puts mw(options).semantic_query(ARGV.shift, ARGV)
+  }],
+  upload_commons:  ['Upload files to Mediawiki Commons (interactive)', lambda { |options|
+    abort 'File name is mandatory.' unless file = ARGV.shift
+
+    mw = mw(options)
+
+    puts 'Description of file:'
+    desc = STDIN.gets.chomp
+
+    puts 'Date of file:'
+    date = STDIN.gets.chomp
+
+    puts 'Target filename (leave blank to use existing name):'
+    target = STDIN.gets.chomp
+    target = options[:target] if target.empty?
+
+    puts 'Categories, separated by commas:'
+    cats = STDIN.gets.chomp.split(',')
+
+    puts "Uploading #{file} to #{target || file}..."
+    mw.upload(file, target: target, description: <<-EOT, summary: options[:summary] || 'Uploaded by MediaWiki::Gateway')
+== Summary ==
+{{Information
+|Description={{en|1=#{desc}}}
+|Source={{own}}
+|Author=[[User:#{options[:user]}|#{options[:user]}]]
+|Date=#{date}
+|Permission=
+|other_versions=
+}}
+
+== Licensing ==
+{{self|cc-by-sa-3.0|GFDL}}
+
+#{cats.map { |cat| "[[Category:#{cat}]]" }.join("\n")}
+    EOT
+  }],
+  upload_file:     ['Upload a file to a Wiki', lambda { |options|
+    abort 'File name is mandatory.' unless file = ARGV.shift
+
+    mw(options).upload(file, target: options[:target], description: options[:description], summary: options[:summary] || 'Uploaded by MediaWiki::Gateway')
+  }]
+}
+
+def commands.list
+  l = keys.map(&:length).max
+  map { |c, (d, _)| "  #{c.to_s.ljust(l)} - #{d}" }.unshift('Available commands:')
+end
+
+usage = <<-EOT
+Usage: #{$0} <command> [options]
+       #{$0} [-h|--help] [--version]
+EOT
+
+options = { loglevel: Logger::WARN }
+
+OptionParser.new { |opts|
+  opts.banner = usage
+
+  opts.separator ''
+
+  opts.on('-w', '--url URL', 'MediaWiki API URL') { |url|
+    options[:url] = url
+  }
+
+  opts.on('-u', '--username USERNAME', 'Username for login') { |user|
+    options[:user] = user
+  }
+
+  opts.on('-p', '--password PASSWORD', 'Password for login') { |pw|
+    options[:pw] = pw
+  }
+
+  opts.separator ''
+
+  opts.on('-H', '--host HOST', 'Use preconfigured HOST in hosts.yml') { |host_id|
+    host = YAML.load_file('hosts.yml').fetch(host_id) {
+      abort "Host #{host_id} not found in hosts.yml"
+    }
+
+    options[:url]  = host['url']
+    options[:pw]   = host['pw']
+    options[:user] = host['user']
+  }
+
+  opts.separator ''
+  opts.separator 'Edit options:'
+
+  opts.on('-s', '--summary SUMMARY', 'Edit summary for this change') { |summary|
+    options[:summary] = summary
+  }
+
+  opts.separator ''
+  opts.separator 'Upload options:'
+
+  opts.on('-d', '--description DESCRIPTION', 'Description of file to upload') { |description|
+    options[:description] = description
+  }
+
+  opts.on('-t', '--target-file TARGET-FILE', 'Target file name to upload to') { |target|
+    options[:target] = target
+  }
+
+  opts.separator ''
+  opts.separator 'Generic options:'
+
+  opts.on('-D', '--debug', 'Set log level to debug') {
+    options[:loglevel] = Logger::DEBUG
+  }
+
+  opts.on('-h', '--help', 'Print this help message and exit') {
+    puts opts
+    exit
+  }
+
+  opts.on('--version', 'Print program version and exit') {
+    puts "#{File.basename($0)} v#{MediaWiki::VERSION}"
+    exit
+  }
+
+  opts.separator ''
+  opts.separator commands.list
+}.parse!
+
+abort usage if ARGV.empty?
+
+command = commands.fetch(key = ARGV.shift.tr('-', '_').to_sym) {
+  abort "Invalid command: #{key}\n\n#{commands.list.join("\n")}"
+}.last
+
+command.arity.zero? ? command.call :
+  options[:url] ? command[options] :
+  abort('URL (-u) or valid host (-H) is mandatory.')