mediawiki-butt 0.11.1 → 1.0.0

data/lib/mediawiki/edit.rb

@@ -1,18 +1,21 @@
+require_relative 'exceptions'
+
 module MediaWiki
   module Edit
     # Performs a standard non-creation edit.
     # @param title [String] The page title.
     # @param text [String] The new content.
     # @param minor [Boolean] Will mark the edit as minor if true.
-    #   Defaults to false.
-    # @param bot [Boolean] Will mark the edit as bot edit if true.
-    #   Defualts to true, for your convenience, bot developers.
+    # @param bot [Boolean] Will mark the edit as bot edit if true. Defaults to true, for your convenience, bot
+    #   developers.
     # @param summary [String] The edit summary. Optional.
-    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing
-    #   wiki content on the MediaWiki API documentation
+    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing wiki content on the MediaWiki API
+    #   documentation
     # @see https://www.mediawiki.org/wiki/API:Edit MediaWiki Edit API Docs
     # @since 0.2.0
-    # @return [String] The new revision ID, or if it failed, the error code.
+    # @raise [EditError] if the edit failed somehow
+    # @return [String] The new revision ID
+    # @return [Boolean] False if there was no change in the edit.
     def edit(title, text, minor = false, bot = true, summary = nil)
       params = {
         action: 'edit',
@@ -31,24 +34,26 @@ module MediaWiki
 
       response = post(params)
 
-      if response['edit']['result'] == 'Success'
-        return response['edit']['newrevid']
-      else
-        return response['error']['code']
+      if response.dig('edit', 'result') == 'Success'
+        return false if response.dig('edit', 'nochange')
+        return response.dig('edit', 'newrevid')
       end
+
+      raise MediaWiki::Butt::EditError.new(response.dig('error', 'code') || 'Unknown error code')
     end
 
     # Creates a new page.
     # @param title [String] The new page's title.
     # @param text [String] The new page's content.
-    # @param summary [String] The edit summary. Defaults to 'New page'.
-    # @param bot [Boolean] Will mark the edit as a bot edit if true.
-    #   Defaults to true, for your convenience, bot developers.
-    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing
-    #   wiki content on the MediaWiki API documentation
+    # @param summary [String] The edit summary.
+    # @param bot [Boolean] Will mark the edit as a bot edit if true. Defaults to true, for your convenience, bot
+    #   developers.
+    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing wiki content on the MediaWiki API
+    #   documentation
     # @see https://www.mediawiki.org/wiki/API:Edit MediaWiki Edit API Docs
     # @since 0.3.0
-    # @return [String] The new page ID, or if it failed, the error code.
+    # @raise [EditError] If there was some error when creating the page.
+    # @return [String] The new page ID
     def create_page(title, text, summary = 'New page', bot = true)
       params = {
         action: 'edit',
@@ -66,26 +71,21 @@ module MediaWiki
 
       response = post(params)
 
-      if response['edit']['result'] == 'Success'
-        return response['edit']['pageid']
-      else
-        return response['error']['code']
-      end
+      return response['edit']['pageid'] if response.dig('edit', 'result') == 'Success'
+      raise MediaWiki::Butt::EditError.new(response.dig('error', 'code') || 'Unknown error code')
     end
 
     # Uploads a file from a URL.
     # @param url [String] The URL to the file.
-    # @param filename [String] The preferred filename.
-    #   This can include File: at the beginning, but it will be removed
-    #   through regex. Optional. If ommitted, it will be everything after
-    #   the last slash in the URL.
-    # @return [Boolean] True if the upload was successful, false if the
-    #   file extension is not valid.
-    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing
-    #   wiki content on the MediaWiki API documentation
+    # @param filename [String] The preferred filename. This can include File: at the beginning, but it will be
+    #   removed through regex. Optional. If omitted, it will be everything after the last slash in the URL.
+    # @return [Boolean] True if the upload was successful, false if the file extension is not valid.
+    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing wiki content on the MediaWiki API
+    #   documentation
     # @see https://www.mediawiki.org/wiki/API:Upload MediaWiki Upload API Docs
     # @since 0.3.0
-    # @return [String] The warning's key if it was unsuccessful.
+    # @return [Boolean] Whether the upload was successful. It is likely that if it returns false, it also raised a
+    #   warning.
     def upload(url, filename = nil)
       params = {
         action: 'upload',
@@ -93,45 +93,37 @@ module MediaWiki
         format: 'json'
       }
 
-      if filename.nil?
-        filename = url.split('/')[-1]
-      else
-        filename = filename.sub(/^File:/, '')
-      end
+      filename = filename.nil? ? url.split('/')[-1] : filename.sub(/^File:/, '')
 
       ext = filename.split('.')[-1]
       allowed_extensions = get_allowed_file_extensions
-      if allowed_extensions.include? ext
-
-        token = get_token('edit', filename)
-        params[:filename] = filename
-        params[:token] = token
-
-        response = post(params)
-        if response['upload']['result'] == 'Success'
-          return true
-        elsif response['upload']['result'] == 'Warning'
-          return response['upload']['warnings'].keys[0]
-        end
-      else
-        return false
+      return false unless allowed_extensions.include?(ext)
+
+      token = get_token('edit', filename)
+      params[:filename] = filename
+      params[:token] = token
+
+      response = post(params)
+
+      response.dig('upload', 'warnings')&.each do |warning|
+        warn warning
       end
+
+      response.dig('upload', 'result') == 'Success'
     end
 
     # Performs a move on a page.
     # @param from [String] The page to be moved.
     # @param to [String] The destination of the move.
-    # @param reason [String] The reason for the move, which shows up in the log.
-    #   Optionl.
+    # @param reason [String] The reason for the move, which shows up in the log. Optional.
     # @param talk [Boolean] Whether to move the associated talk page.
-    #   Defaults to true.
-    # @param redirect [Boolean] Whether to create a redirect. Defaults to false.
-    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing
-    #   wiki content on the MediaWiki API documentation
+    # @param redirect [Boolean] Whether to create a redirect.
+    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing wiki content on the MediaWiki API
+    #   documentation
     # @see https://www.mediawiki.org/wiki/API:Move MediaWiki Move API Docs
     # @since 0.5.0
+    # @raise [EditError]
     # @return [Boolean] True if it was successful.
-    # @return [String] The error code if it was unsuccessful.
     def move(from, to, reason = nil, talk = true, redirect = false)
       params = {
         action: 'move',
@@ -141,27 +133,25 @@ module MediaWiki
 
       token = get_token('move', from)
       params[:reason] = reason unless reason.nil?
-      params[:movetalk] = '1' if talk == true
-      params[:noredirect] = '1' if redirect == false
+      params[:movetalk] = '1' if talk
+      params[:noredirect] = '1' if redirect
       params[:token] = token
 
       response = post(params)
-      if !response['move'].nil?
-        return true
-      else
-        return response['error']['code']
-      end
+
+      return true if response['move']
+      raise MediaWiki::Butt::EditError.new(response.dig('error', 'code') || 'Unknown error code')
     end
 
     # Deletes a page.
     # @param title [String] The page to delete.
     # @param reason [String] The reason to be displayed in logs. Optional.
-    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing
-    #   wiki content on the MediaWiki API documentation
+    # @see https://www.mediawiki.org/wiki/API:Changing_wiki_content Changing wiki content on the MediaWiki API
+    #   documentation
     # @see https://www.mediawiki.org/wiki/API:Delete MediaWiki Delete API Docs
     # @since 0.5.0
+    # @raise [EditError]
     # @return [Boolean] True if successful.
-    # @return [String] The error code if it was not successful.
     def delete(title, reason = nil)
       params = {
         action: 'delete',
@@ -173,11 +163,8 @@ module MediaWiki
       params[:token] = token
 
       response = post(params)
-      if !response['delete'].nil?
-        return true
-      else
-        return response['error']['code']
-      end
+      return true if response['delete']
+      raise MediaWiki::Butt::EditError.new(response.dig('error', 'code') || 'Unknown error code')
     end
   end
 end

data/lib/mediawiki/exceptions.rb

@@ -1,128 +1,7 @@
 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
-
-    # Start creation-specific errors
-    class UserExistsError < AuthenticationError
-      def message
-        'Username entered is already in use.'
-      end
-    end
-
-    class UserPassMatchError < AuthenticationError
-      def message
-        'Your password must be different from your username.'
-      end
-    end
-
-    class PasswordLoginForbiddenError < AuthenticationError
-      def message
-        'The use of this username and password has been forbidden.'
-      end
-    end
-
-    class NoEmailTitleError < AuthenticationError
-      def message
-        'No email address.'
-      end
-    end
-
-    class InvalidEmailAddressError < AuthenticationError
-      def message
-        'The email address is invalid.'
-      end
-    end
-
-    class PasswordTooShortError < AuthenticationError
-      def message
-        'The password was shorter than the value of $wgMinimalPasswordLength'
-      end
-    end
-
-    class NoEmailError < AuthenticationError
-      def message
-        'There is no email address recorded for the user.'
-      end
-    end
-
-    class AbortedError < AuthenticationError
-      def message
-        'Aborted by an extension.'
-      end
-    end
-
-    class PermDeniedError < AuthenticationError
-      def message
-        'You do not have the right to make an account.'
-      end
-    end
-
-    class HookAbortedError < AuthenticationError
-      def message
-        'An extension aborted the account creation.'
-      end
-    end
+    class EditError < StandardError; end
+    class BlockError < StandardError; end
   end
 end

data/lib/mediawiki/query/lists/all.rb

@@ -3,14 +3,12 @@ module MediaWiki
     module Lists
       module All
         # Gets all categories on the entire wiki.
-        # @param limit [Int] The maximum number of categories to get. Defaults
-        #   to 500. Cannot be greater than 500 for normal users, or 5000 for
-        #   bots.
-        # @see https://www.mediawiki.org/wiki/API:Allcategories MediaWiki
-        #   Allcategories API Docs
+        # @param limit [Fixnum] The maximum number of categories to get. Cannot be greater than 500 for users or 5000
+        #   for bots.
+        # @see https://www.mediawiki.org/wiki/API:Allcategories MediaWiki Allcategories API Docs
         # @since 0.7.0
-        # @return [Array] An array of all categories.
-        def get_all_categories(limit = 500)
+        # @return [Array<String>] An array of all categories.
+        def get_all_categories(limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'allcategories',
@@ -26,13 +24,11 @@ module MediaWiki
         end
 
         # Gets all the images on the wiki.
-        # @param limit [Int] The maximum number of images to get. Defaults to
-        #   500. Cannot be greater than 500 for normal users, or 5000 for bots.
-        # @see https://www.mediawiki.org/wiki/API:Allimages MediaWiki Allimages
-        #   API Docs
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Allimages MediaWiki Allimages API Docs
         # @since 0.7.0
-        # @return [Array] An array of all images.
-        def get_all_images(limit = 500)
+        # @return [Array<String>] An array of all images.
+        def get_all_images(limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'allimages',
@@ -48,13 +44,12 @@ module MediaWiki
         end
 
         # Gets all pages within a namespace integer.
-        # @param namespace [Int] The namespace ID.
-        # @param limit [Int] See #get_all_images
-        # @see https://www.mediawiki.org/wiki/API:Allpages MediaWiki Allpages
-        #   API Docs
+        # @param namespace [Fixnum] The namespace ID.
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Allpages MediaWiki Allpages API Docs
         # @since 0.8.0
-        # @return [Array] An array of all page titles.
-        def get_all_pages_in_namespace(namespace, limit = 500)
+        # @return [Array<String>] An array of all page titles.
+        def get_all_pages_in_namespace(namespace, limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'allpages',
@@ -72,12 +67,11 @@ module MediaWiki
 
         # Gets all users, or all users in a group.
         # @param group [String] The group to limit this query to.
-        # @param limit [Int] See #get_all_images.
-        # @see https://www.mediawiki.org/wiki/API:Allusers MediaWiki Allusers
-        #   API Docs
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Allusers MediaWiki Allusers API Docs
         # @since 0.8.0
-        # @return [Hash] A hash of all users, names are keys, IDs are values.
-        def get_all_users(group = nil, limit = 500)
+        # @return [Hash<String, Fixnum>] A hash of all users, names are keys, IDs are values.
+        def get_all_users(group = nil, limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'allusers',
@@ -93,13 +87,13 @@ module MediaWiki
           ret
         end
 
-        # Gets all block IDs on the wiki. It seems like this only gets non-IP
-        #   blocks, but the MediaWiki docs are a bit unclear.
-        # @param limit [Int] See #get_all_images.
+        # Gets all block IDs on the wiki. It seems like this only gets non-IP blocks, but the MediaWiki docs are a
+        # bit unclear.
+        # @param (see #get_all_categories)
         # @see https://www.mediawiki.org/wiki/API:Blocks MediaWiki Blocks API Docs
         # @since 0.8.0
-        # @return [Array] All block IDs as strings.
-        def get_all_blocks(limit = 500)
+        # @return [Array<Fixnum>] All block IDs as strings.
+        def get_all_blocks(limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'blocks',
@@ -117,12 +111,11 @@ module MediaWiki
 
         # Gets all page titles that transclude a given page.
         # @param page [String] The page name.
-        # @param limit [Int] See #get_all_images.
-        # @see https://www.mediawiki.org/wiki/API:Embeddedin MediaWiki Embeddedin
-        #   API Docs
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Embeddedin MediaWiki Embeddedin API Docs
         # @since 0.8.0
-        # @return [Array] All transcluder page titles.
-        def get_all_transcluders(page, limit = 500)
+        # @return [Array<String>] All transcluder page titles.
+        def get_all_transcluders(page, limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'embeddedin',
@@ -139,13 +132,11 @@ module MediaWiki
         end
 
         # Gets an array of all deleted or archived files on the wiki.
-        # @param limit [Int] See #get_all_images
-        # @see https://www.mediawiki.org/wiki/API:Filearchive MediaWiki
-        #   Filearchive API Docs
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Filearchive MediaWiki Filearchive API Docs
         # @since 0.8.0
-        # @return [Array] All deleted file names. These are not titles, so they do
-        #   not include "File:".
-        def get_all_deleted_files(limit = 500)
+        # @return [Array<String>] All deleted file names. These are not titles, so they do not include "File:".
+        def get_all_deleted_files(limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'filearchive',
@@ -162,12 +153,11 @@ module MediaWiki
 
         # Gets a list of all protected pages, by protection level if provided.
         # @param protection_level [String] The protection level, e.g., sysop
-        # @param limit [Int] See #get_all_images.
-        # @see https://www.mediawiki.org/wiki/API:Protectedtitles MediaWiki
-        #   Protectedtitles API Docs
+        # @param (see #get_all_categories)
+        # @see https://www.mediawiki.org/wiki/API:Protectedtitles MediaWiki Protectedtitles API Docs
         # @since 0.8.0
-        # @return [Array] All protected page titles.
-        def get_all_protected_titles(protection_level = nil, limit = 500)
+        # @return [Array<String>] All protected page titles.
+        def get_all_protected_titles(protection_level = nil, limit = @query_limit_default)
           params = {
             action: 'query',
             list: 'protectedtitles',