mediawiktory 0.0.3 → 0.1.0

data/lib/mediawiktory/wikipedia/api.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative './client'
+require_relative './actions'
+
+# Wrapper for [Wikipedia](https://en.wikipedia.org/wiki/Main_Page) API.
+#
+# _Generated from https://en.wikipedia.org/w/api.php at May 09, 2017 by MediaWiktory 0.1.0._
+#
+# It also can be used for access to any other MediaWiki site, but some of actions could be
+# non-existent/outdated.
+#
+# See {MediaWiktory::Wikipedia::Api} for usage.
+#
+module MediaWiktory::Wikipedia
+  # Base API class for [Wikipedia](https://en.wikipedia.org/wiki/Main_Page).
+  #
+  # Example of usage:
+  #
+  # ```ruby
+  # # For Wikipedia
+  # api = MediaWiktory::Wikipedia::Api.new
+  # api.some_action.some_param(value).other_param(*more_values).perform
+  # # => returns raw response of MediaWiki API
+  # api.some_action.some_param(value).other_param(*more_values).response
+  # # => returns an instance of Response, parsed from JSON
+  #
+  # # For any other site:
+  # api = MediaWiktory::Wikipedia::Api.new('https://some.site/w/api.php')
+  # # ...the same as above
+  # ```
+  #
+  # {Actions} module lists all available API actions and refers to corresponding classes and
+  # their options.
+  #
+  # See also {Response} for working with return values and {Actions::Base} for working with actions.
+  #
+  class Api
+    # @private
+    attr_reader :client, :defaults
+
+    # @private
+    CLIENT_OPTIONS = %i[user_agent ua].freeze
+
+    # @param url [String] Source URL for this API, by default "".
+    #   Note that most of MediaWiki installations have source URL at `/w/api.php`, but some are
+    #   just `/api.php`, others use `/wiki/api.php` and so on.
+    #
+    # @param defaults [Hash] Default options for all API queries. Default param values also can be
+    #   set by subsequent {Actions::Base} methods, like `api.some_action.json(callback: 'mycallbackname')...`
+    # @option defaults [Symbol] user_agent User-Agent header for underlying client.
+    # @option defaults [Symbol] format The format of the output. Selecting an option includes tweaking methods from corresponding module: See {Actions::Base#format}
+    # @option defaults [Integer] maxlag Maximum lag can be used when MediaWiki is installed on a database replicated cluster. To save actions causing any more site replication lag, this parameter can make the client wait until the replication lag is less than the specified value. In case of excessive lag, error code maxlag is returned with a message like Waiting for $host: $lag seconds lagged.See Manual: Maxlag parameter for more information. See {Actions::Base#maxlag}
+    # @option defaults [Integer] smaxage Set the s-maxage HTTP cache control header to this many seconds. Errors are never cached. See {Actions::Base#smaxage}
+    # @option defaults [Integer] maxage Set the max-age HTTP cache control header to this many seconds. Errors are never cached. See {Actions::Base#maxage}
+    # @option defaults [String] assert Verify the user is logged in if set to user, or has the bot user right if bot. One of "user", "bot". See {Actions::Base#assert}
+    # @option defaults [String] assertuser Verify the current user is the named user. See {Actions::Base#assertuser}
+    # @option defaults [String] requestid Any value given here will be included in the response. May be used to distinguish requests. See {Actions::Base#requestid}
+    # @option defaults [true, false] servedby Include the hostname that served the request in the results. See {Actions::Base#servedby}
+    # @option defaults [true, false] curtimestamp Include the current timestamp in the result. See {Actions::Base#curtimestamp}
+    # @option defaults [true, false] responselanginfo Include the languages used for uselang and errorlang in the result. See {Actions::Base#responselanginfo}
+    # @option defaults [String] origin When accessing the API using a cross-domain AJAX request (CORS), set this to the originating domain. This must be included in any pre-flight request, and therefore must be part of the request URI (not the POST body). See {Actions::Base#origin}
+    # @option defaults [String] uselang Language to use for message translations. action=query&meta=siteinfo with siprop=languages returns a list of language codes, or specify user to use the current user's language preference, or specify content to use this wiki's content language. See {Actions::Base#uselang}
+    # @option defaults [String] errorformat Format to use for warning and error text output. One of " plaintext" ( Wikitext with HTML tags removed and entities replaced), " wikitext" ( Unparsed wikitext), " html" ( HTML), " raw" ( Message key and parameters), " none" ( No text output, only the error codes), " bc" ( Format used prior to MediaWiki 1.29. errorlang and errorsuselocal are ignored). See {Actions::Base#errorformat}
+    # @option defaults [String] errorlang Language to use for warnings and errors. action=query&meta=siteinfo with siprop=languages returns a list of language codes, or specify content to use this wiki's content language, or specify uselang to use the same value as the uselang parameter. See {Actions::Base#errorlang}
+    # @option defaults [true, false] errorsuselocal If given, error texts will use locally-customized messages from the MediaWiki namespace. See {Actions::Base#errorsuselocal}
+    # @option defaults [String] centralauthtoken When accessing the API using a cross-domain AJAX request (CORS), use this to authenticate as the current SUL user. Use action=centralauthtoken on this wiki to retrieve the token, before making the CORS request. Each token may only be used once, and expires after 10 seconds. This should be included in any pre-flight request, and therefore should be included in the request URI (not the POST body). See {Actions::Base#centralauthtoken}
+    #
+    def initialize(url = 'https://en.wikipedia.org/w/api.php', **defaults)
+      client_options, @defaults = defaults.partition { |k, _| CLIENT_OPTIONS.include?(k) }.map(&:to_h)
+      @client = Client.new(url, **client_options)
+    end
+
+    def inspect
+      "#<#{self.class.name}(#{@client.url})>"
+    end
+
+    include MediaWiktory::Wikipedia::Actions
+  end
+end

data/lib/mediawiktory/wikipedia/client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'addressable'
+require 'faraday'
+require 'faraday_middleware'
+
+module MediaWiktory::Wikipedia
+  # Internal low-level client class, used by {Api}.
+  #
+  # Uses [Faraday](https://github.com/lostisland/faraday) library inside (and will expose it's settings
+  # in future).
+  #
+  # You should not use it directly, all you need is in {Api}.
+  class Client
+    # Default MediaWiktory User-Agent header.
+    #
+    # You can set yours as an option to {#initialize}
+    UA = 'MediaWiktory/0.1.0 '\
+         '(https://github.com/molybdenum-99/mediawiktory; zverok.offline@gmail.com)'
+
+    class << self
+      # User agent getter/setter.
+      #
+      # Default value is {UA}.
+      #
+      # You can also use per-instance option, see {#initialize}
+      attr_accessor :user_agent
+    end
+
+    attr_reader :url
+
+    def initialize(url, **options)
+      @url = Addressable::URI.parse(url)
+      @options = options
+      @faraday = Faraday.new(url) do |f|
+        f.request :url_encoded
+        f.use FaradayMiddleware::FollowRedirects, limit: 5
+        f.adapter Faraday.default_adapter
+      end
+      @faraday.headers.merge!(headers)
+    end
+
+    def user_agent
+      @options[:user_agent] || @options[:ua] || self.class.user_agent || UA
+    end
+
+    def get(params)
+      @faraday.get('', params).body
+    end
+
+    def post(params)
+      @faraday.post('', params).body
+    end
+
+    private
+
+    def headers
+      {'User-Agent' => user_agent}
+    end
+  end
+end

data/lib/mediawiktory/wikipedia/modules/abusefilters.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module MediaWiktory::Wikipedia
+  module Modules
+    # Show details of the abuse filters.
+    #
+    # The "submodule" (MediaWiki API term) is included in action after setting some param, providing
+    # additional tweaking for this param. Example (for {MediaWiktory::Wikipedia::Actions::Query} and
+    # its submodules):
+    #
+    # ```ruby
+    # api.query             # returns Actions::Query
+    #    .prop(:revisions)  # adds prop=revisions to action URL, and includes Modules::Revisions into action
+    #    .limit(10)         # method of Modules::Revisions, adds rvlimit=10 to URL
+    # ```
+    #
+    # All submodule's parameters are documented as its public methods, see below.
+    #
+    module Abusefilters
+
+      # The filter ID to start enumerating from.
+      #
+      # @param value [Integer]
+      # @return [self]
+      def startid(value)
+        merge(abfstartid: value.to_s)
+      end
+
+      # The filter ID to stop enumerating at.
+      #
+      # @param value [Integer]
+      # @return [self]
+      def endid(value)
+        merge(abfendid: value.to_s)
+      end
+
+      # In which direction to enumerate:
+      #
+      # @param value [String] One of "newer" (List oldest first. Note: abfstart has to be before abfend), "older" (List newest first (default). Note: abfstart has to be later than abfend).
+      # @return [self]
+      def dir(value)
+        _dir(value) or fail ArgumentError, "Unknown value for dir: #{value}"
+      end
+
+      # @private
+      def _dir(value)
+        defined?(super) && super || ["newer", "older"].include?(value.to_s) && merge(abfdir: value.to_s)
+      end
+
+      # Show only filters which meet these criteria.
+      #
+      # @param values [Array<String>] Allowed values: "enabled", "!enabled", "deleted", "!deleted", "private", "!private".
+      # @return [self]
+      def show(*values)
+        values.inject(self) { |res, val| res._show(val) or fail ArgumentError, "Unknown value for show: #{val}" }
+      end
+
+      # @private
+      def _show(value)
+        defined?(super) && super || ["enabled", "!enabled", "deleted", "!deleted", "private", "!private"].include?(value.to_s) && merge(abfshow: value.to_s, replace: false)
+      end
+
+      # The maximum number of filters to list.
+      #
+      # @param value [Integer, "max"]
+      # @return [self]
+      def limit(value)
+        merge(abflimit: value.to_s)
+      end
+
+      # Which properties to get.
+      #
+      # @param values [Array<String>] Allowed values: "id", "description", "pattern", "actions", "hits", "comments", "lasteditor", "lastedittime", "status", "private".
+      # @return [self]
+      def prop(*values)
+        values.inject(self) { |res, val| res._prop(val) or fail ArgumentError, "Unknown value for prop: #{val}" }
+      end
+
+      # @private
+      def _prop(value)
+        defined?(super) && super || ["id", "description", "pattern", "actions", "hits", "comments", "lasteditor", "lastedittime", "status", "private"].include?(value.to_s) && merge(abfprop: value.to_s, replace: false)
+      end
+    end
+  end
+end

data/lib/mediawiktory/wikipedia/modules/abuselog.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module MediaWiktory::Wikipedia
+  module Modules
+    # Show events that were caught by one of the abuse filters.
+    #
+    # The "submodule" (MediaWiki API term) is included in action after setting some param, providing
+    # additional tweaking for this param. Example (for {MediaWiktory::Wikipedia::Actions::Query} and
+    # its submodules):
+    #
+    # ```ruby
+    # api.query             # returns Actions::Query
+    #    .prop(:revisions)  # adds prop=revisions to action URL, and includes Modules::Revisions into action
+    #    .limit(10)         # method of Modules::Revisions, adds rvlimit=10 to URL
+    # ```
+    #
+    # All submodule's parameters are documented as its public methods, see below.
+    #
+    module Abuselog
+
+      # The timestamp to start enumerating from.
+      #
+      # @param value [Time]
+      # @return [self]
+      def start(value)
+        merge(aflstart: value.iso8601)
+      end
+
+      # The timestamp to stop enumerating at.
+      #
+      # @param value [Time]
+      # @return [self]
+      def end(value)
+        merge(aflend: value.iso8601)
+      end
+
+      # In which direction to enumerate:
+      #
+      # @param value [String] One of "newer" (List oldest first. Note: aflstart has to be before aflend), "older" (List newest first (default). Note: aflstart has to be later than aflend).
+      # @return [self]
+      def dir(value)
+        _dir(value) or fail ArgumentError, "Unknown value for dir: #{value}"
+      end
+
+      # @private
+      def _dir(value)
+        defined?(super) && super || ["newer", "older"].include?(value.to_s) && merge(afldir: value.to_s)
+      end
+
+      # Show only entries done by a given user or IP address.
+      #
+      # @param value [String]
+      # @return [self]
+      def user(value)
+        merge(afluser: value.to_s)
+      end
+
+      # Show only entries occurring on a given page.
+      #
+      # @param value [String]
+      # @return [self]
+      def title(value)
+        merge(afltitle: value.to_s)
+      end
+
+      # Show only entries that were caught by a given filter ID.
+      #
+      # @param values [Array<String>]
+      # @return [self]
+      def filter(*values)
+        values.inject(self) { |res, val| res._filter(val) }
+      end
+
+      # @private
+      def _filter(value)
+        merge(aflfilter: value.to_s, replace: false)
+      end
+
+      # The maximum amount of entries to list.
+      #
+      # @param value [Integer, "max"]
+      # @return [self]
+      def limit(value)
+        merge(afllimit: value.to_s)
+      end
+
+      # Which properties to get.
+      #
+      # @param values [Array<String>] Allowed values: "ids", "filter", "user", "ip", "title", "action", "details", "result", "timestamp", "hidden", "revid".
+      # @return [self]
+      def prop(*values)
+        values.inject(self) { |res, val| res._prop(val) or fail ArgumentError, "Unknown value for prop: #{val}" }
+      end
+
+      # @private
+      def _prop(value)
+        defined?(super) && super || ["ids", "filter", "user", "ip", "title", "action", "details", "result", "timestamp", "hidden", "revid"].include?(value.to_s) && merge(aflprop: value.to_s, replace: false)
+      end
+    end
+  end
+end

data/lib/mediawiktory/wikipedia/modules/allcategories.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module MediaWiktory::Wikipedia
+  module Modules
+    # Enumerate all categories.
+    #
+    # The "submodule" (MediaWiki API term) is included in action after setting some param, providing
+    # additional tweaking for this param. Example (for {MediaWiktory::Wikipedia::Actions::Query} and
+    # its submodules):
+    #
+    # ```ruby
+    # api.query             # returns Actions::Query
+    #    .prop(:revisions)  # adds prop=revisions to action URL, and includes Modules::Revisions into action
+    #    .limit(10)         # method of Modules::Revisions, adds rvlimit=10 to URL
+    # ```
+    #
+    # All submodule's parameters are documented as its public methods, see below.
+    #
+    module Allcategories
+
+      # The category to start enumerating from.
+      #
+      # @param value [String]
+      # @return [self]
+      def from(value)
+        merge(acfrom: value.to_s)
+      end
+
+      # When more results are available, use this to continue.
+      #
+      # @param value [String]
+      # @return [self]
+      def continue(value)
+        merge(accontinue: value.to_s)
+      end
+
+      # The category to stop enumerating at.
+      #
+      # @param value [String]
+      # @return [self]
+      def to(value)
+        merge(acto: value.to_s)
+      end
+
+      # Search for all category titles that begin with this value.
+      #
+      # @param value [String]
+      # @return [self]
+      def prefix(value)
+        merge(acprefix: value.to_s)
+      end
+
+      # Direction to sort in.
+      #
+      # @param value [String] One of "ascending", "descending".
+      # @return [self]
+      def dir(value)
+        _dir(value) or fail ArgumentError, "Unknown value for dir: #{value}"
+      end
+
+      # @private
+      def _dir(value)
+        defined?(super) && super || ["ascending", "descending"].include?(value.to_s) && merge(acdir: value.to_s)
+      end
+
+      # Only return categories with at least this many members.
+      #
+      # @param value [Integer]
+      # @return [self]
+      def min(value)
+        merge(acmin: value.to_s)
+      end
+
+      # Only return categories with at most this many members.
+      #
+      # @param value [Integer]
+      # @return [self]
+      def max(value)
+        merge(acmax: value.to_s)
+      end
+
+      # How many categories to return.
+      #
+      # @param value [Integer, "max"]
+      # @return [self]
+      def limit(value)
+        merge(aclimit: value.to_s)
+      end
+
+      # Which properties to get:
+      #
+      # @param values [Array<String>] Allowed values: "size" (Adds number of pages in the category), "hidden" (Tags categories that are hidden with __HIDDENCAT__).
+      # @return [self]
+      def prop(*values)
+        values.inject(self) { |res, val| res._prop(val) or fail ArgumentError, "Unknown value for prop: #{val}" }
+      end
+
+      # @private
+      def _prop(value)
+        defined?(super) && super || ["size", "hidden"].include?(value.to_s) && merge(acprop: value.to_s, replace: false)
+      end
+    end
+  end
+end

data/lib/mediawiktory/wikipedia/modules/alldeletedrevisions.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module MediaWiktory::Wikipedia
+  module Modules
+    # List all deleted revisions by a user or in a namespace.
+    #
+    # The "submodule" (MediaWiki API term) is included in action after setting some param, providing
+    # additional tweaking for this param. Example (for {MediaWiktory::Wikipedia::Actions::Query} and
+    # its submodules):
+    #
+    # ```ruby
+    # api.query             # returns Actions::Query
+    #    .prop(:revisions)  # adds prop=revisions to action URL, and includes Modules::Revisions into action
+    #    .limit(10)         # method of Modules::Revisions, adds rvlimit=10 to URL
+    # ```
+    #
+    # All submodule's parameters are documented as its public methods, see below.
+    #
+    module Alldeletedrevisions
+
+      # Which properties to get for each revision:
+      #
+      # @param values [Array<String>] Allowed values: "ids" (The ID of the revision), "flags" (Revision flags (minor)), "timestamp" (The timestamp of the revision), "user" (User that made the revision), "userid" (User ID of the revision creator), "size" (Length (bytes) of the revision), "sha1" (SHA-1 (base 16) of the revision), "contentmodel" (Content model ID of the revision), "comment" (Comment by the user for the revision), "parsedcomment" (Parsed comment by the user for the revision), "content" (Text of the revision), "tags" (Tags for the revision), "parsetree" (The XML parse tree of revision content (requires content model wikitext)).
+      # @return [self]
+      def prop(*values)
+        values.inject(self) { |res, val| res._prop(val) or fail ArgumentError, "Unknown value for prop: #{val}" }
+      end
+
+      # @private
+      def _prop(value)
+        defined?(super) && super || ["ids", "flags", "timestamp", "user", "userid", "size", "sha1", "contentmodel", "comment", "parsedcomment", "content", "tags", "parsetree"].include?(value.to_s) && merge(adrprop: value.to_s, replace: false)
+      end
+
+      # Limit how many revisions will be returned.
+      #
+      # @param value [Integer, "max"]
+      # @return [self]
+      def limit(value)
+        merge(adrlimit: value.to_s)
+      end
+
+      # Expand templates in revision content (requires adrprop=content).
+      #
+      # @return [self]
+      def expandtemplates()
+        merge(adrexpandtemplates: 'true')
+      end
+
+      # Generate XML parse tree for revision content (requires adrprop=content; replaced by adrprop=parsetree).
+      #
+      # @return [self]
+      def generatexml()
+        merge(adrgeneratexml: 'true')
+      end
+
+      # Parse revision content (requires adrprop=content). For performance reasons, if this option is used, adrlimit is enforced to 1.
+      #
+      # @return [self]
+      def parse()
+        merge(adrparse: 'true')
+      end
+
+      # Only retrieve the content of this section number.
+      #
+      # @param value [String]
+      # @return [self]
+      def section(value)
+        merge(adrsection: value.to_s)
+      end
+
+      # Revision ID to diff each revision to. Use prev, next and cur for the previous, next and current revision respectively.
+      #
+      # @param value [String]
+      # @return [self]
+      def diffto(value)
+        merge(adrdiffto: value.to_s)
+      end
+
+      # Text to diff each revision to. Only diffs a limited number of revisions. Overrides adrdiffto. If adrsection is set, only that section will be diffed against this text.
+      #
+      # @param value [String]
+      # @return [self]
+      def difftotext(value)
+        merge(adrdifftotext: value.to_s)
+      end
+
+      # Perform a pre-save transform on the text before diffing it. Only valid when used with adrdifftotext.
+      #
+      # @return [self]
+      def difftotextpst()
+        merge(adrdifftotextpst: 'true')
+      end
+
+      # Serialization format used for adrdifftotext and expected for output of content.
+      #
+      # @param value [String] One of "application/json", "text/x-wiki", "text/javascript", "text/css", "text/plain".
+      # @return [self]
+      def contentformat(value)
+        _contentformat(value) or fail ArgumentError, "Unknown value for contentformat: #{value}"
+      end
+
+      # @private
+      def _contentformat(value)
+        defined?(super) && super || ["application/json", "text/x-wiki", "text/javascript", "text/css", "text/plain"].include?(value.to_s) && merge(adrcontentformat: value.to_s)
+      end
+
+      # Only list revisions by this user.
+      #
+      # @param value [String]
+      # @return [self]
+      def user(value)
+        merge(adruser: value.to_s)
+      end
+
+      # Only list pages in this namespace.
+      #
+      # @param values [Array<String>] Allowed values: "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "100", "101", "108", "109", "118", "119", "446", "447", "710", "711", "828", "829", "2300", "2301", "2302", "2303".
+      # @return [self]
+      def namespace(*values)
+        values.inject(self) { |res, val| res._namespace(val) or fail ArgumentError, "Unknown value for namespace: #{val}" }
+      end
+
+      # @private
+      def _namespace(value)
+        defined?(super) && super || ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "100", "101", "108", "109", "118", "119", "446", "447", "710", "711", "828", "829", "2300", "2301", "2302", "2303"].include?(value.to_s) && merge(adrnamespace: value.to_s, replace: false)
+      end
+
+      # The timestamp to start enumerating from.
+      #
+      # @param value [Time]
+      # @return [self]
+      def start(value)
+        merge(adrstart: value.iso8601)
+      end
+
+      # The timestamp to stop enumerating at.
+      #
+      # @param value [Time]
+      # @return [self]
+      def end(value)
+        merge(adrend: value.iso8601)
+      end
+
+      # In which direction to enumerate:
+      #
+      # @param value [String] One of "newer" (List oldest first. Note: adrstart has to be before adrend), "older" (List newest first (default). Note: adrstart has to be later than adrend).
+      # @return [self]
+      def dir(value)
+        _dir(value) or fail ArgumentError, "Unknown value for dir: #{value}"
+      end
+
+      # @private
+      def _dir(value)
+        defined?(super) && super || ["newer", "older"].include?(value.to_s) && merge(adrdir: value.to_s)
+      end
+
+      # Start listing at this title.
+      #
+      # @param value [String]
+      # @return [self]
+      def from(value)
+        merge(adrfrom: value.to_s)
+      end
+
+      # Stop listing at this title.
+      #
+      # @param value [String]
+      # @return [self]
+      def to(value)
+        merge(adrto: value.to_s)
+      end
+
+      # Search for all page titles that begin with this value.
+      #
+      # @param value [String]
+      # @return [self]
+      def prefix(value)
+        merge(adrprefix: value.to_s)
+      end
+
+      # Don't list revisions by this user.
+      #
+      # @param value [String]
+      # @return [self]
+      def excludeuser(value)
+        merge(adrexcludeuser: value.to_s)
+      end
+
+      # Only list revisions tagged with this tag.
+      #
+      # @param value [String]
+      # @return [self]
+      def tag(value)
+        merge(adrtag: value.to_s)
+      end
+
+      # When more results are available, use this to continue.
+      #
+      # @param value [String]
+      # @return [self]
+      def continue(value)
+        merge(adrcontinue: value.to_s)
+      end
+
+      # When being used as a generator, generate titles rather than revision IDs.
+      #
+      # @return [self]
+      def generatetitles()
+        merge(adrgeneratetitles: 'true')
+      end
+    end
+  end
+end