mediawiki-butt 0.11.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d6dbd003fbc5068efe0a5bc3492317db380f0ceb
-  data.tar.gz: 92d56a75e87f81f30e58368eb4e7406d1b9ed638
+  metadata.gz: 16daad9c28f5960f5820657cf6ec6b646976b0c0
+  data.tar.gz: f0a165472aad7b3864507a351581abeb40be25a5
 SHA512:
-  metadata.gz: b096731fa931d81c5c6eef8cfd2eab9c0ffc71a1af89277b79894a0b5cb6f88a6264bc27d3d9b5a7a33a0fd30dc23a2a4f0fbdcc0ebd511ff553f2301b096fce
-  data.tar.gz: 3cee7c55b72f0296ec90d0f3198fdc69baabf66c8b7aea6042c6f54b1dd03f38ad49c9c4d28836f2ebf4894b57324055302d65f31becbea13b19a28283fc380e
+  metadata.gz: 1d944b95cea6f5b6319db90607a117288ec244def26000ce018b2d14301cc3c11b9c1ed49d36628d39cb8e2e300cbbd47d8437770be12affb7a5526716eeebaf
+  data.tar.gz: 0a82a742586f999f7dcbf1055fbbda20ff6c3b22f183cd249c045b0f960be0d36741b273b09d35736ff60700326573ef5d7ae7f2177fc1700f76fd7d2bb1d329

data/CHANGELOG.md

@@ -1,4 +1,27 @@
 # Changelog
+## Version 1
+### Version 1.0.0
+* Important: MediaWiki::Butt now depends on Ruby 2.3. If you aren't using that yet, use it. It's worth it.
+* MediaWiki::Butt.new now takes two parameters, `url`, and an options hash. See the documentation for initialize for more details.
+* Improvements to the way we handle query limits (#28, #31, and #37):
+  * `get_recent_revisions`, `get_prefix_search`, and `get_full_watchlist` now properly set their limits.
+  * Most query lists that took a limit parameter now use the attribute `:query_limit_default` instead of each having a set default of 500.
+  * New `:query_limit_default` attribute accessor. This means you can change your default limits whenever you want!
+  * Support using 'max' as the limit.
+* Major cleanup of documentation. The YARD server at ftb-gamepedia.github.io/MediaWiki-Butt-Ruby is now the recommended place for documentation.
+* Improve testing slightly.
+* Remove the TIME_FORMAT constant and instead use DateTime's methods properly.
+* Fix FileRepoInfo methods returning hashes with nil values instead of arrays of hashes (#34).
+* Add support for the MediaWiki Watching/Unwatching APIs (#38)
+* Remove the unused `:tokens` instance variable. This should silence some errors when logging in/out.
+* Improve authentication methods by making them recursive. `login` and `create_account(_email)` now take an optional third parameter, token.
+* Fix error in `get_categories_in_page` (APerson241)
+* Error handling improvements (APerson241 and elifoster) (#32):
+  * New EditError that is thrown when there is an error when editing. It contains the error code.
+  * `edit` returns false when there is no change (error: nochange), rather than throwing an error.
+  * New BlockError that is thrown when there is an error when blocking/unblocking.
+  * Removed AuthenticationError subclasses, as well as `check_login` and `check_create`. All authentication errors now return a generic AuthenticationError with the provided error message from MediaWiki.
+
 ## Version 0
 ### Version 0.11.1
 * Relicense under the MIT license.
@@ -197,7 +220,7 @@
   * New get_general method, for getting hash of the 'general' wiki information.
   * New get_extensions method, for getting an array of all extension names installed.
   * New get_languages method, for getting a hash of all the languages, formatted as code => name.
-* User-Agent header is now set for each post. It defaults to 'NotLoggedIn/MediaWiki::Butt', or "#{name}/MediaWiki::Butt" if logged in. This might cause some slight performance issues ([#5](https://github.com/FTB-Gamepedia/MediaWiki-Butt-Ruby/issues/5))
+* User-Agent header is now set for each post. It defaults to `NotLoggedIn/MediaWiki::Butt`, or `#{name}/MediaWiki::Butt` if logged in. This might cause some slight performance issues ([#5](https://github.com/FTB-Gamepedia/MediaWiki-Butt-Ruby/issues/5))
 
 ### Version 0.5.0
 * New Administration module for administrative methods.
@@ -240,8 +263,8 @@
 * New get_contrib_count method.
 * Refactor get_usergroups and is_current_user_bot? to use new get_userinfo method.
 * Minor refactors to make optional arguments more Ruby-like with splat arguments.
-* #edit no longer prints the edit token, because that's stupid.
-* #edit no longer sets the summary if it is nil.
+* `#edit` no longer prints the edit token, because that's stupid.
+* `#edit` no longer sets the summary if it is nil.
 
 ### Version 0.2.1
 * Fix gemspec. You should actually have the new stuff now.
@@ -259,8 +282,8 @@
 * Got rid of pointless array in is_current_user_bot
 * Potentially fixed docs
 * Raise errors on unsuccessful account creation
-* #login properly returns true if the login is successful on the first try
-* #logout returns true/false if it logs the user out. Basically returns true if @logged_in is true, and false if not, because the logout action has no errors.
+* `#login` properly returns true if the login is successful on the first try
+* `#logout` returns true/false if it logs the user out. Basically returns true if @logged_in is true, and false if not, because the logout action has no errors.
 * Account creation stuff actually returns true/false on success/fail. It also handles errors now.
 * Better Category title regex in get_category_members
 

data/lib/mediawiki/administration.rb

@@ -1,14 +1,15 @@
+require_relative 'exceptions'
+
 module MediaWiki
   module Administration
     # Blocks the user.
-    # @param user [String] The user to block.
+    # @param (see #unblock)
     # @param expiry [String] The expiry timestamp using a relative expiry time.
-    # @param reason [String] The reason to show in the block log.
     # @param nocreate [Boolean] Whether to allow them to create an account.
     # @see https://www.mediawiki.org/wiki/API:Block MediaWiki Block API Docs
     # @since 0.5.0
-    # @return [String] The error code.
-    # @return [Int] The block ID.
+    # @raise [BlockError]
+    # @return (see #unblock)
     def block(user, expiry = '2 weeks', reason = nil, nocreate = true)
       params = {
         action: 'block',
@@ -17,42 +18,42 @@ module MediaWiki
       }
 
       token = get_token('block')
-      params[:reason] = reason unless reason.nil?
+      params[:reason] = reason if reason
       params[:nocreate] = '1' if nocreate
       params[:token] = token
 
       response = post(params)
 
-      if !response['error'].nil?
-        return response['error']['code']
-      else
-        return response['id'].to_i
+      if response.key?('error')
+        raise MediaWiki::Butt::BlockError.new(response.dig('error', 'code') || 'Unknown error code')
       end
+
+      response['id'].to_i
     end
 
     # Unblocks the user.
-    # @param user [String] The user to unblock.
+    # @param user [String] The user affected.
     # @param reason [String] The reason to show in the block log.
     # @see https://www.mediawiki.org/wiki/API:Block MediaWiki Block API Docs
     # @since 0.5.0
-    # @return [String] The error code.
-    # @return [Int] The block ID.
+    # @raise [BlockError]
+    # @return [Fixnum] The block ID.
     def unblock(user, reason = nil)
       params = {
         action: 'unblock',
         user: user
       }
       token = get_token('unblock')
-      params[:reason] = reason unless reason.nil?
+      params[:reason] = reason if reason
       params[:token] = token
 
       response = post(params)
 
-      if !response['error'].nil?
-        return response['error']['code']
-      else
-        return response['id'].to_i
+      if response.key?('error')
+        raise MediaWiki::Butt::BlockError.new(response.dig('error', 'code') || 'Unknown error code')
       end
+
+      response['id'].to_i
     end
   end
 end

data/lib/mediawiki/auth.rb

@@ -2,153 +2,48 @@ require_relative 'exceptions'
 
 module MediaWiki
   module Auth
-    # Checks the login result for errors. Returns true if it is successful,
-    # else false with an error raised.
-    # @param result [String] The parsed version of the result.
-    # @param secondtry [Boolean] Whether this login is the first or second try.
-    #   False for first, true for second.
-    # @raise [NeedTokenMoreThanOnceError] When secondtry is true and the wiki
-    #   still returns 'NeedToken'
-    # @raise [NoNameError] When the username is nil or undefined.
-    # @raise [IllegalUsernameError] When the username is illegal.
-    # @raise [UsernameNotExistsError] When the username does not exist.
-    # @raise [EmptyPassError] When the password is nil or undefined.
-    # @raise [WrongPassError] When the password is incorrect.
-    # @raise [WrongPluginPassError] When an authentication plugin, not
-    #   MediaWiki, claims that the password is incorrect.
-    # @raise [CreateBlockedError] When the wiki tries to automatically create
-    #   an account, but the user's IP address is already blocked.
-    # @raise [ThrottledError] When the user has logged in, or tried to, too
-    #   much in a particular amount of time.
-    # @raise [BlockedError] When the user is blocked from the wiki.
-    # @since 0.1.0
-    # @return [Boolean] true if successful. Does not return anything otherwise.
-    def check_login(result, secondtry)
-      case result
-      when 'Success'
-        @logged_in = true
-        return true
-      when 'NeedToken'
-        fail MediaWiki::Butt::NeedTokenMoreThanOnceError if secondtry
-      when 'NoName'
-        fail MediaWiki::Butt::NoNameError
-      when 'Illegal'
-        fail MediaWiki::Butt::IllegalUsernameError
-      when 'NotExists'
-        fail MediaWiki::Butt::UsernameNotExistsError
-      when 'EmptyPass'
-        fail MediaWiki::Butt::EmptyPassError
-      when 'WrongPass'
-        fail MediaWiki::Butt::WrongPassError
-      when 'WrongPluginPass'
-        fail MediaWiki::Butt::WrongPluginPassError
-      when 'CreateBlocked'
-        fail MediaWiki::Butt::CreateBlockedError
-      when 'Throttled'
-        fail MediaWiki::Butt::ThrottledError
-      when 'Blocked'
-        fail MediaWiki::Butt::BlockedError
-      end
-    end
-
-    # Checks the account creation result's error and raises the corresponding
-    # exception.
-    # @param error [String] The parsed error code string
-    # @raise [NoNameError] When the username was either not provided or is
-    #   invalid.
-    # @raise [UserExistsError] When the username is already in use.
-    # @raise [UserPassMatchError] When the username and password are identical.
-    # @raise [PasswordLoginForbiddenError] When the use of the username and
-    #   password has been forbidden.
-    # @raise [NoEmailTitleError] When there is no provided email address.
-    # @raise [InvalidEmailAddressError] When the email address has an invalid
-    #   format.
-    # @raise [PasswordTooShortError] When the password is shorter than the
-    #   $wgMinimumPasswordLength option.
-    # @raise [NoEmailError] When there is no email address set for the user.
-    # @raise [ThrottledError] When the user has created too many accounts in one
-    #   day.
-    # @raise [AbortedError] When an extension has aborted this action.
-    # @raise [BlockedError] When the IP or logged in user is blocked.
-    # @raise [PermDeniedError] When the user does not have the right to create
-    #   accounts.
-    # @raise [HookAbortedError] Same as AbortedError.
-    # @since 0.1.1
-    # @return [void]
-    def check_create(error)
-      case error
-      when 'noname'
-        fail MediaWiki::Butt::NoNameError
-      when 'userexists'
-        fail MediaWiki::Butt::UserExistsError
-      when 'password-name-match'
-        fail MediaWiki::Butt::UserPassMatchError
-      when 'password-login-forbidden'
-        fail MediaWiki::Butt::PasswordLoginForbiddenError
-      when 'noemailtitle'
-        fail MediaWiki::Butt::NoEmailTitleError
-      when 'invalidemailaddress'
-        fail MediaWiki::Butt::InvalidEmailAddressError
-      when 'passwordtooshort'
-        fail MediaWiki::Butt::PasswordTooShortError
-      when 'noemail'
-        fail MediaWiki::Butt::NoEmailError
-      when 'acct_creation_throttle_hit'
-        fail MediaWiki::Butt::ThrottledError
-      when 'aborted'
-        fail MediaWiki::Butt::AbortedError
-      when 'blocked'
-        fail MediaWiki::Butt::BlockedError
-      when 'permdenied-createaccount'
-        fail MediaWiki::Butt::PermDeniedError
-      when 'createaccount-hook-aborted'
-        fail MediaWiki::Butt::HookAbortedError
-      end
-    end
-
-    # Logs the user into the wiki. This is generally required for editing and
-    #   getting restricted data. Will return the result of #check_login
+    # Logs the user into the wiki. This is generally required for editing and getting restricted data.
     # @param username [String] The username
     # @param password [String] The password
-    # @see check_login
+    # @param token [String] The login token to use. Only set this if you know what you are doing. You probably want
+    # to just let the function get the token and set it on its own.
+    # @see #check_login
     # @see https://www.mediawiki.org/wiki/API:Login MediaWiki Login API Docs
     # @since 0.1.0
-    # @return [Boolean] True if the login was successful, false if not.
-    def login(username, password)
+    # @raise [AuthenticationError]
+    # @return [Boolean] True if the login was successful.
+    def login(username, password, token = nil)
       params = {
         action: 'login',
         lgname: username,
         lgpassword: password
       }
+      params[:lgtoken] = token if token
+      header = {}
+      header['Set-Cookie'] = @cookie if @cookie
 
-      result = post(params)
-      if check_login(result['login']['result'], false)
-        @logged_in = true
-        @tokens.clear
-        true
-      elsif result['login']['result'] == 'NeedToken' &&
-            !result['login']['token'].nil?
-        token = result['login']['token']
-        token_params = {
-          action: 'login',
-          lgname: username,
-          lgpassword: password,
-          lgtoken: token
-        }
+      response = post(params, true, header)
+      result = response['login']['result']
 
-        # Consider refactor the @cookie initialization.
-        @cookie = "#{result['login']['cookieprefix']}" \
-                  "Session=#{result['login']['sessionid']}"
-        result = post(token_params, true, 'Set-Cookie' => @cookie)
-        @name = username if check_login(result['login']['result'], true)
+      if result == 'NeedToken'
+        token = response['login']['token']
+        return login(username, password, token)
       end
+
+      if result == 'Success'
+        @cookie = "#{response['login']['cookieprefix']}Session=#{response['login']['sessionid']}"
+        @name = username
+        @logged_in = true
+        return true
+      end
+
+      raise MediaWiki::Butt::AuthenticationError.new(result)
     end
 
     # Logs the current user out.
     # @see https://www.mediawiki.org/wiki/API:Logout MediaWiki Logout API Docs
     # @since 0.1.0
-    # @return [Boolean] True if it was able to log anyone out, false if not
-    #   (basically, if someone was logged in, it returns true).
+    # @return [Boolean] True if it was able to log anyone out, false if not.
     def logout
       if @logged_in
         params = {
@@ -157,117 +52,81 @@ module MediaWiki
 
         post(params)
         @logged_in = false
-        @tokens.clear
-        return true
+
+        true
       else
-        return false
+        false
       end
     end
 
     # Creates an account using the standard procedure.
     # @param username [String] The desired username.
     # @param password [String] The desired password.
-    # @param language [String] The language code to be set as default for the
-    #   account. Defaults to 'en', or English. Use the language code, not
-    #   the name.
-    # @param reason [String] The reason for creating the account, as shown in
-    #   the account creation log. Optional.
-    # @see check_create
-    # @see https://www.mediawiki.org/wiki/API:Account_creation MediaWiki Account
-    #   Creation Docs
+    # @param language [String] The language code to be set as default for the account. Defaults to 'en', or English.
+    # Use the language code, not the name.
+    # @param reason [String] The reason for creating the account, as shown in the account creation log. Optional.
+    # @param token [String] The account creation token to use. Only set this if you know what you are doing. You
+    # probably want to just let the function get the token and set it on its own.
+    # @see #check_create
+    # @see https://www.mediawiki.org/wiki/API:Account_creation MediaWiki Account Creation Docs
     # @since 0.1.0
     # @return [Boolean] True if successful, false if not.
-    def create_account(username, password, language = 'en', reason = nil)
+    def create_account(username, password, language = 'en', reason = nil, token = '')
       params = {
         name: username,
         password: password,
         language: language,
-        token: ''
+        token: token
       }
       params[:reason] = reason unless reason.nil?
 
       result = post(params)
       unless result['error'].nil?
-        check_create(result['error']['code'])
-        return false
+        raise MediaWiki::Butt::AuthenticationError.new(result['error']['code'])
       end
 
       if result['createaccount']['result'] == 'Success'
         @tokens.clear
+
         return true
       elsif result['createaccount']['result'] == 'NeedToken'
-        params = {
-          name: username,
-          password: password,
-          reason: reason,
-          language: language,
-          token: result['createaccount']['token']
-        }
-
-        result = post(params, true, true)
-        if !result['error'].nil?
-          check_create(result['error']['code'])
-          return false
-        elsif result['createaccount']['result'] == 'Success'
-          return true
-        else
-          return false
-        end
+        return create_account(username, password, language, reason, result['createaccount']['token'])
       end
+
+      false
     end
 
     # Creates an account using the random password sent by email procedure.
-    # @param username [String] The desired username
     # @param email [String] The desired email address
-    # @param language [String] The language code to be set as default for the
-    #   account. Defaults to 'en', or English. Use the language code, not
-    #   the name.
-    # @param reason [String] The reason for creating the account, as shown in
-    #   the account creation log. Optional.
-    # @see check_create
-    # @see https://www.mediawiki.org/wiki/API:Account_creation MediaWiki Account
-    #   Creation Docs
+    # @param (see #create_account)
+    # @see #check_create
+    # @see https://www.mediawiki.org/wiki/API:Account_creation MediaWiki Account Creation Docs
     # @since 0.1.0
     # @return [Boolean] True if successful, false if not.
-    def create_account_email(username, email, language = 'en', reason = nil)
+    def create_account_email(username, email, language = 'en', reason = nil, token = '')
       params = {
         name: username,
         email: email,
         mailpassword: 'value',
         language: language,
-        token: ''
+        token: token
       }
       params[:reason] = reason unless reason.nil?
 
       result = post(params)
       unless result['error'].nil?
-        check_create(result['error']['code'])
-        return false
+        raise MediaWiki::Butt::AuthenticationError.new(result['error']['code'])
       end
 
       if result['createaccount']['result'] == 'Success'
         @tokens.clear
+
         return true
       elsif result['createaccount']['result'] == 'NeedToken'
-        params = {
-          name: username,
-          email: email,
-          mailpassword: 'value',
-          reason: reason,
-          language: language,
-          token: result['createaccount']['token']
-        }
-
-        result = post(params, true, true)
-        if !result['error'].nil?
-          check_create(result['error']['code'])
-          return false
-        elsif result['createaccount']['result'] == 'Success'
-          return true
-        else
-          return false
-        end
+        return create_account_email(username, email, language, reason, result['createaccount']['token'])
       end
+
+      false
     end
   end
 end