mediawiki-butt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e92d6477086ed671ae506b7dab213c47777e004c
+  data.tar.gz: 3bcb59b71c5d084cb8f27f365934710e2e60015f
+SHA512:
+  metadata.gz: 4048a9e68a138b23e8412e4c991504fb894a20632f0fe673b4c9b62ee169d03e8a965991e912a61d23c4466a6fe60de97a21b0db2c10f2becad7a727468e5bc9
+  data.tar.gz: 2cc73a41fae56f3e0c535f589e3ee9fecde5f6b74892e7bd968035739126d818e17f935b8aaf6c2a1494aca5b65aa89369c2dc9d693f086fe1110084eb267d44

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+## Version 0
+### Version 0.1.0
+* Initial version.

data/lib/mediawiki-butt.rb

@@ -0,0 +1 @@
+require_relative 'mediawiki/butt'

data/lib/mediawiki/auth.rb

@@ -0,0 +1,185 @@
+require_relative 'exceptions'
+
+module MediaWiki
+  module Auth
+
+    # Checks the login result for errors. Return true if success, else false, and will raise an error if it is not successful.
+    #
+    # ==== Attributes
+    #
+    # * +result+ - The parsed version of the result parameter of the login action.
+    # * +secondtry+ - Whether this login is the first or second try, false for first, true for second.
+    #
+    # ==== Examples
+    #
+    # This method should not be used by normal users.
+    def check_login(result, secondtry)
+      if result == "Success"
+        @logged_in = true
+        return true
+      elsif result == "NeedToken" && secondtry == true
+        raise MediaWiki::Butt::NeedTokenMoreThanOnceError
+        return false
+      elsif result == "NoName"
+        raise MediaWiki::Butt::NoNameError
+        return false
+      elsif result == "Illegal"
+        raise MediaWiki::Butt::IllegalUsernameError
+        return false
+      elsif result == "NotExists"
+        raise MediaWiki::Butt::UsernameNotExistsError
+        return false
+      elsif result == "EmptyPass"
+        raise MediaWiki::Butt::EmptyPassError
+        return false
+      elsif result == "WrongPass"
+        raise MediaWiki::Butt::WrongPassError
+        return false
+      elsif result == "WrongPluginPass"
+        raise MediaWiki::Butt::WrongPluginPassError
+        return false
+      elsif result == "CreateBlocked"
+        raise MediaWiki::Butt::CreateBlockedError
+        return false
+      elsif result == "Throttled"
+        raise MediaWiki::Butt::ThrottledError
+        return false
+      elsif result == "Blocked"
+        raise MediaWiki::Butt::BlockedError
+        return false
+      end
+    end
+    # Logs the user in to the wiki. This is generally required for editing, or getting restricted data.
+    # Will return the result of check_login.
+    #
+    # ==== Attributes
+    #
+    # * +username+ - The desired login handle
+    # * +password+ - The password of that user
+    #
+    # ==== Examples
+    #
+    # => butt.login("MyUsername", "My5up3r53cur3P@55w0rd")
+    def login(username, password)
+      params = {
+        action: 'login',
+        lgname: username,
+        lgpassword: password,
+        format: 'json'
+      }
+
+      result = post(params, true, false)
+      if check_login(result["login"]["result"], false) == true
+        @logged_in = true
+        @tokens.clear
+      elsif result["login"]["result"] == "NeedToken" && result["login"]["token"] != nil
+        token = result["login"]["token"]
+        token_params = {
+          action: 'login',
+          lgname: username,
+          lgpassword: password,
+          format: 'json',
+          lgtoken: token
+        }
+
+        #Consider refactor the @cookie initialization.
+        @cookie = "#{result["login"]["cookieprefix"]}Session=#{result["login"]["sessionid"]}"
+        result = post(token_params, true, true)
+        return check_login(result["login"]["result"], true)
+      end
+    end
+
+    # Logs the current user out
+    #
+    # ==== Examples
+    #
+    # => butt.login("MyUsername", "My5up3r53cur3P@55w0rd")
+    # => # do stuff
+    # => butt.logout
+    def logout
+      if @logged_in == true
+        params = {
+          action: 'logout'
+        }
+
+        post(params)
+        @logged_in = false
+        @tokens.clear
+      end
+    end
+
+    # Creates an account using the standard procedure.
+    #
+    # ==== Attributes
+    #
+    # *+username+ - The desired username
+    # *+password+ - The desired password.
+    # *+language+ - The language code to set as default for the account being created. Defaults to 'en' or English. Use the language code, not the name.
+    # *+reason+ - The reason for creating the account, shown in the account creation log. Optional.
+    #
+    # ==== Examples
+    #
+    # => butt.create_account("MyUser", "password", "es", "MyEmailAddress@MailMain.com", "Quiero un nuevo acuenta sin embargo correocontraseña")
+    def create_account(username, password, language = 'en', *reason)
+      params = {
+        name: username,
+        password: password,
+        reason: reason,
+        language: language,
+        token: ''
+      }
+
+      result = post(params)
+
+      if result["createaccount"]["result"] == "Success"
+        @tokens.clear
+      elsif result["createaccount"]["result"] == "NeedToken"
+        params = {
+          name: username,
+          password: password,
+          reason: reason,
+          language: language,
+          token: result["createaccount"]["token"]
+        }
+      end
+    end
+
+    # Creates an account using the random-password-sent-by-email procedure.
+    #
+    # ==== Attributes
+    #
+    # *+username+ - The desired username
+    # *+email+ - The desired email address.
+    # *+reason+ - The reason for creating the account, shown in the account creation log. Optional.
+    # *+language+ - The language code to set as default for the account being created. Defaults to 'en' or English. Use the language code, not the name.
+    #
+    # ==== Examples
+    #
+    # => butt.create_account_email("MyUser", "MyEmailAddress@Whatever.com", "es", "Quiero una nueva acuenta porque quiero a comer caca")
+    def create_account_email(username, email, language = 'en', *reason)
+      params = {
+        name: username,
+        email: email,
+        mailpassword: 'value',
+        reason: reason,
+        language: language,
+        token: ''
+      }
+
+      result = post(params)
+
+      if result["createaccount"]["result"] == "Success"
+        @tokens.clear
+      elsif result["createaccount"]["result"] == "NeedToken"
+        params = {
+          name: username,
+          email: email,
+          mailpassword: 'value',
+          reason: reason,
+          language: language,
+          token: result["createaccount"]["token"]
+        }
+      end
+    end
+  end
+end

data/lib/mediawiki/butt.rb

@@ -0,0 +1,92 @@
+require_relative 'auth'
+require_relative 'query'
+require 'httpclient'
+require 'json'
+
+module MediaWiki
+  class Butt
+    include MediaWiki::Auth
+    include MediaWiki::Query::Meta
+    include MediaWiki::Query::Properties
+    include MediaWiki::Query::Lists
+    # Creates a new instance of MediaWiki::Butt
+    #
+    # ==== Attributes
+    #
+    # * +url+ - The FULL wiki URL. api.php can be omitted, but it will make harsh assumptions about your wiki configuration.
+    # * +use_ssl+ - Whether or not to use SSL. Will default to true.
+    #
+    # ==== Examples
+    #
+    # The example below shows an ideal usage of the method.
+    # => butt = MediaWiki::Butt.new("http://ftb.gamepedia.com/api.php")
+    #
+    # The example below shows a less than idea, but still functional, usage of the method. It is less than ideal because it has to assume that your API page is at /api.php, but it could easily be at /w/api.php, or even /wiki/api.php. It also does not use a secure connection.
+    # => butt = MediaWiki::Butt.new("http://ftb.gamepedia.com", false)
+    def initialize(url, use_ssl = true)
+      if url =~ /api.php$/
+        @url = url
+      else
+        @url = "#{url}/api.php"
+      end
+
+      @client = HTTPClient.new
+      @uri = URI.parse(@url)
+      @ssl = use_ssl
+      @logged_in = false
+      @tokens = {}
+    end
+
+    # Performs a generic HTTP POST action and provides the response. This method generally should not be used by the user, unless there is not a method provided by the Butt developers for a particular action.
+    #
+    # ==== Attributes
+    #
+    # * +params+ - A basic hash containing MediaWiki API parameters. Please see mediawiki.org/wiki/API for more information.
+    # * +autoparse+ - Whether or not to provide a parsed version of the response's JSON. Will default to true.
+    # * +setcookie+ - Whether you want to set the auth cookie. Only used in authentication. Defaults to false.
+    #
+    # ==== Examples
+    #
+    # => login = butt.post({action: 'login', lgname: username, lgpassword: password, format: 'json'})
+    def post(params, autoparse = true, setcookie = false)
+      if setcookie == true
+        header = { 'Set-Cookie' => @cookie }
+        response = @client.post(@uri, params, header)
+      else
+        response = @client.post(@uri, params)
+      end
+
+      if autoparse == true
+        return JSON.parse(response.body)
+      else
+        return response
+      end
+    end
+
+    # Returns true if the currently logged in user is in the "bot" group.
+    # Will return false if the user is either not a bot or if they are not logged in.
+    def is_current_user_bot()
+      if @logged_in == true
+        params = {
+          action: 'query',
+          meta: 'userinfo',
+          uiprop: 'groups',
+          format: 'json'
+        }
+
+        ret = Array.new
+        response = post(params)
+        response["query"]["userinfo"]["groups"].each do |g|
+          if g == "bot"
+            return true
+          else
+            next
+          end
+        end
+        return false
+      else
+        return false
+      end
+    end
+  end
+end

data/lib/mediawiki/exceptions.rb

@@ -0,0 +1,65 @@
+module MediaWiki
+  class Butt
+    class AuthenticationError < StandardError; end
+
+    class NeedTokenMoreThanOnceError < AuthenticationError
+      def message
+        "You tried to get the token more than once. You likely have some problem with your login call."
+      end
+    end
+
+    class NoNameError < AuthenticationError
+      def message
+        "You did not set the lgname parameter."
+      end
+    end
+
+    class IllegalUsernameError < AuthenticationError
+      def message
+        "You provided an illegal username."
+      end
+    end
+
+    class UsernameNotExistsError < AuthenticationError
+      def message
+        "You provided a username that does not exist."
+      end
+    end
+
+    class EmptyPassError < AuthenticationError
+      def message
+        "You did not set the lgpassword paremeter."
+      end
+    end
+
+    class WrongPassError < AuthenticationError
+      def message
+        "The password you provided is not correct."
+      end
+    end
+
+    class WrongPluginPassError < AuthenticationError
+      def message
+        "A plugin (not MediaWiki) claims your password is not correct."
+      end
+    end
+
+    class CreateBlockedError < AuthenticationError
+      def message
+        "MediaWiki tried to automatically create an account for you, but your IP is blocked from account creation."
+      end
+    end
+
+    class ThrottledError < AuthenticationError
+      def message
+        "You've logged in too many times."
+      end
+    end
+
+    class BlockedError < AuthenticationError
+      def message
+        "User is blocked."
+      end
+    end
+  end
+end

data/lib/mediawiki/query.rb

@@ -0,0 +1,154 @@
+module MediaWiki
+  module Query
+    #TODO: Actually decide on a good way to deal with meta information queries.
+    # The metainformation could probably be handled in a much less verbose way.
+    module Meta
+
+      # Gets all raw names for the wiki's image repositories into an array.
+      #
+      # ==== Examples
+      #
+      # => names = butt.get_filerepo_names()
+      def get_filerepo_names()
+        params = {
+          action: 'query',
+          meta: 'filerepoinfo',
+          friprop: 'name',
+          format: 'json'
+        }
+
+        result = post(params)
+        array = Array.new
+        result["query"]["repos"].each do |repo|
+          array.push(repo["name"])
+        end
+        return array
+      end
+    end
+
+    module Properties
+
+      # Gets the text for the given page. Returns nil if the page does not exist.
+      #
+      # ==== Attributes
+      #
+      # * +title+ - The page.
+      #
+      # ==== Examples
+      #
+      # => text = butt.get_text("User:Pendejo")
+      def get_text(title)
+        params = {
+          action: 'query',
+          prop: 'revisions',
+          rvprop: 'content',
+          format: 'json',
+          titles: title
+        }
+
+        response = post(params)
+        response["query"]["pages"].each do |revid, data|
+          $revid = revid
+        end
+
+        if response["query"]["pages"][$revid]["missing"] == ""
+          return nil
+        else
+          return response["query"]["pages"][$revid]["revisions"][0]["*"]
+        end
+      end
+    end
+
+    module Lists
+      # Gets the list of backlinks of the title.
+      #
+      # ==== Attributes
+      #
+      # * +title+ - List pages linking to this title.
+      # * +limit+ - The maximum number of pages to get. Defaults to 500, and cannot be greater than 5000.
+      #
+      # ==== Examples
+      #
+      # => backlinks = butt.what_links_here("Title", 5)
+      # => backlinks.each do |butt|
+      # =>   puts butt
+      # => end
+      def what_links_here(title, limit = 500)
+        params = {
+          action: 'query',
+          bltitle: title,
+          format: 'json'
+        }
+
+        if limit > 500
+          if is_current_user_bot() == true
+            if limit > 5000
+              params[:bllimit] = 5000
+            else
+              params[:bllimit] = limit
+            end
+          else
+            params[:bllimit] = 500
+          end
+        else
+          params[:bllimit] = limit
+        end
+
+        ret = Array.new
+        response = post(params)
+        response["query"]["backlinks"].each do |bl|
+          ret.push(bl["title"])
+        end
+        return ret
+      end
+      # Returns an array of all pages (titles specifically, because IDs and namespace ints aren't very important) that belong to a given category. See API:Categorymembers
+      #
+      # ==== Attributes
+      #
+      # * +category+ - The category title.
+      # * +limit+ - The maximum number of members to get. Defaults to 500, and cannot be greater than 5000.
+      #
+      # ==== Examples
+      #
+      # => members = butt.get_category_members("Category:Butts", 5000)
+      # => members.each do |butts|
+      # =>   puts butts
+      # => end
+      def get_category_members(category, limit = 500)
+        params = {
+          action: 'query',
+          list: 'categorymembers',
+          #cmprop: 'title',
+          format: 'json'
+        }
+
+        if category =~ /Category\:/
+          params[:cmtitle] = category
+        else
+          params[:cmtitle] = "Category:#{category}"
+        end
+
+        if limit > 500
+          if is_current_user_bot() == true
+            if limit > 5000
+              params[:cmlimit] = 5000
+            else
+              params[:cmlimit] = limit
+            end
+          else
+            params[:cmlimit] = 500
+          end
+        else
+          params[:cmlimit] = limit
+        end
+
+        ret = Array.new
+        response = post(params)
+        response["query"]["categorymembers"].each do |cm|
+          ret.push(cm["title"])
+        end
+        return ret
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: mediawiki-butt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eli Foster
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-09-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httpclient
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      MediaWiki::Butt is a Ruby Gem that provides a fully-featured MediaWiki API interface.
+email: elifosterwy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- lib/mediawiki-butt.rb
+- lib/mediawiki/auth.rb
+- lib/mediawiki/butt.rb
+- lib/mediawiki/exceptions.rb
+- lib/mediawiki/query.rb
+homepage: https://github.com/ftb-gamepedia/mediawiki-butt-ruby
+licenses:
+- CC-BY-NC-ND-4.0
+metadata:
+  issue_tracker: https://github.com/ftb-gamepedia/mediawiki-butt-ruby/issues
+post_install_message: ONE OF US! ONE OF US!
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Interacting with the MediaWiki API
+test_files: []