mediawiki-butt 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e92d6477086ed671ae506b7dab213c47777e004c
-  data.tar.gz: 3bcb59b71c5d084cb8f27f365934710e2e60015f
+  metadata.gz: 01b96931127f32d0a59b62876f5de8c80657cbc3
+  data.tar.gz: 3ef158346ca14fe0073eca30714e48c87b44684d
 SHA512:
-  metadata.gz: 4048a9e68a138b23e8412e4c991504fb894a20632f0fe673b4c9b62ee169d03e8a965991e912a61d23c4466a6fe60de97a21b0db2c10f2becad7a727468e5bc9
-  data.tar.gz: 2cc73a41fae56f3e0c535f589e3ee9fecde5f6b74892e7bd968035739126d818e17f935b8aaf6c2a1494aca5b65aa89369c2dc9d693f086fe1110084eb267d44
+  metadata.gz: 47a2a279b141b771ebef8a84702d7f42422ee0baa789e0ef2fd6f74e5b616c2861f9d2509df4fb5565145a1876334095965988fdaebdf3b59c0749c82f3bf862
+  data.tar.gz: 220e119d425714af14b50df518e02f6ff9bcacaccf799cb87c0d0ac52322fddf90fbd5a74bf580d44f97d5a7425307cb6bf6af3c600f47a10410e6f8ff25a5df

data/CHANGELOG.md

@@ -1,4 +1,13 @@
 # Changelog
 ## Version 0
+### Version 0.1.1
+* 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.
+* Account creation stuff actually returns true/false on success/fail. It also handles errors now.
+* Better Category title regex in get_category_members
+
 ### Version 0.1.0
 * Initial version.

data/lib/mediawiki/auth.rb

@@ -3,16 +3,10 @@ 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.
+    # 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.
+    # @return [Boolean] true if successful, else false.
     def check_login(result, secondtry)
       if result == "Success"
         @logged_in = true
@@ -49,17 +43,57 @@ module MediaWiki
         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")
+
+    # Checks the account creation result's error and raises the corresponding error.
+    # @param error [String] The parsed error "code" string
+    # @return [Boolean] Always false
+    def check_create(error)
+      if error == "noname"
+        raise MediaWiki::Butt::NoNameError
+        return false
+      elsif error == "userexists"
+        raise MediaWiki::Butt::UserExistsError
+        return false
+      elsif error == "password-name-match"
+        raise MediaWiki::Butt::UserPassMatchError
+        return false
+      elsif error == "password-login-forbidden"
+        raise MediaWiki::Butt::PasswordLoginForbiddenError
+        return false
+      elsif error == "noemailtitle"
+        raise MediaWiki::Butt::NoEmailTitleError
+        return false
+      elsif error == "invalidemailaddress"
+        raise MediaWiki::Butt::InvalidEmailAddressError
+        return false
+      elsif error == "passwordtooshort"
+        raise MediaWiki::Butt::PasswordTooShortError
+        return false
+      elsif error == "noemail"
+        raise MediaWiki::Butt::NoEmailError
+        return false
+      elsif error == "acct_creation_throttle_hit"
+        raise MediaWiki::Butt::ThrottledError
+        return false
+      elsif error == "aborted"
+        raise MediaWiki::Butt::AbortedError
+        return false
+      elsif error == "blocked"
+        raise MediaWiki::Butt::BlockedError
+        return false
+      elsif error == "permdenied-createaccount"
+        raise MediaWiki::Butt::PermDeniedError
+        return false
+      elsif error == "createaccount-hook-aborted"
+        raise MediaWiki::Butt::HookAbortedError
+        return false
+      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
+    # @param username [String] The username
+    # @param password [String] The password
+    # @return [Boolean] True if the login was successful, false if not.
     def login(username, password)
       params = {
         action: 'login',
@@ -68,10 +102,11 @@ module MediaWiki
         format: 'json'
       }
 
-      result = post(params, true, false)
+      result = post(params)
       if check_login(result["login"]["result"], false) == true
         @logged_in = true
         @tokens.clear
+        return true
       elsif result["login"]["result"] == "NeedToken" && result["login"]["token"] != nil
         token = result["login"]["token"]
         token_params = {
@@ -89,13 +124,8 @@ module MediaWiki
       end
     end
 
-    # Logs the current user out
-    #
-    # ==== Examples
-    #
-    # => butt.login("MyUsername", "My5up3r53cur3P@55w0rd")
-    # => # do stuff
-    # => butt.logout
+    # Logs the current user out.
+    # @return [Boolean] True if it was able to log anyone out, false if not (basically, if someone was logged in, it returns true).
     def logout
       if @logged_in == true
         params = {
@@ -105,21 +135,18 @@ module MediaWiki
         post(params)
         @logged_in = false
         @tokens.clear
+        return true
+      else
+        return false
       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")
+    # @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.
+    # @return [Boolean] True if successful, false if not.
     def create_account(username, password, language = 'en', *reason)
       params = {
         name: username,
@@ -130,9 +157,14 @@ module MediaWiki
       }
 
       result = post(params)
+      if result["error"] != nil
+        check_create(result["error"]["code"])
+        return false
+      end
 
       if result["createaccount"]["result"] == "Success"
         @tokens.clear
+        return true
       elsif result["createaccount"]["result"] == "NeedToken"
         params = {
           name: username,
@@ -141,21 +173,25 @@ module MediaWiki
           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
       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")
+    # 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.
+    # @return [Boolean] True if successful, false if not.
     def create_account_email(username, email, language = 'en', *reason)
       params = {
         name: username,
@@ -167,9 +203,15 @@ module MediaWiki
       }
 
       result = post(params)
+      result = post(params)
+      if result["error"] != nil
+        check_create(result["error"]["code"])
+        return false
+      end
 
       if result["createaccount"]["result"] == "Success"
         @tokens.clear
+        return true
       elsif result["createaccount"]["result"] == "NeedToken"
         params = {
           name: username,
@@ -179,6 +221,16 @@ module MediaWiki
           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
       end
     end
   end

data/lib/mediawiki/butt.rb

@@ -9,20 +9,12 @@ module MediaWiki
     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")
+
+    # Creates a new instance of MediaWiki::Butt. To work with any MediaWiki::Butt methods, you must first create an instance of it.
     #
-    # 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)
+    # @param url [String] The FULL wiki URL. api.php can be omitted, but it will make harsh assumptions about your wiki configuration.
+    # @param use_ssl [Boolean] Whether or not to use SSL. Will default to true.
+    # @return [MediaWiki::Butt] new instance of MediaWiki::Butt
     def initialize(url, use_ssl = true)
       if url =~ /api.php$/
         @url = url
@@ -39,15 +31,10 @@ module MediaWiki
 
     # 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'})
+    # @param params [Hash] A basic hash containing MediaWiki API parameters. Please see the MediaWiki API for more information.
+    # @param autoparse [Boolean] Whether or not to provide a parsed version of the response's JSON. Will default to true.
+    # @param setcookie [Boolean] Whether you want to set the auth cookie. Only used in authentication. Defaults to false.
+    # @return [JSON/Response] Parsed JSON if autoparse is true, or raw response if not.
     def post(params, autoparse = true, setcookie = false)
       if setcookie == true
         header = { 'Set-Cookie' => @cookie }
@@ -63,8 +50,8 @@ module MediaWiki
       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.
+    # Returns true if the currently logged in user is in the "bot" group. This can be helpful to some developers, but it is mostly for use internally in MediaWiki::Butt.
+    # @return [Boolean] true if logged in as a bot, false if not logged in or logged in as a non-bot
     def is_current_user_bot()
       if @logged_in == true
         params = {
@@ -74,7 +61,6 @@ module MediaWiki
           format: 'json'
         }
 
-        ret = Array.new
         response = post(params)
         response["query"]["userinfo"]["groups"].each do |g|
           if g == "bot"

data/lib/mediawiki/exceptions.rb

@@ -61,5 +61,66 @@ module MediaWiki
         "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
   end
 end

data/lib/mediawiki/query.rb

@@ -4,11 +4,8 @@ module MediaWiki
     # 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()
+      # Returns an array of all the wiki's file repository names.
+      # @return [Array] All wiki's file repository names.
       def get_filerepo_names()
         params = {
           action: 'query',
@@ -28,15 +25,9 @@ module MediaWiki
 
     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")
+      # Gets the wiki text for the given page. Returns nil if it for some reason cannot get the text, for example, if the page does not exist. Returns a string.
+      # @param title [String] The page title
+      # @return [String/nil] String containing page contents, or nil
       def get_text(title)
         params = {
           action: 'query',
@@ -60,19 +51,11 @@ module MediaWiki
     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
+
+      # Gets an array of backlinks to a given title.
+      # @param title [String] The page to get the backlinks of.
+      # @param limit [Int] The maximum number of pages to get. Defaults to 500, and cannot be greater than that unless the user is a bot. If the user is a bot, the limit cannot be greater than 5000.
+      # @return [Array] All backlinks until the limit
       def what_links_here(title, limit = 500)
         params = {
           action: 'query',
@@ -101,19 +84,11 @@ module MediaWiki
         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
+
+      # Returns an array of all pagee titles that belong to a given category.
+      # @param category [String] The category title. It can include "Category:", or not, it doesn't really matter because we will add it if it is missing.
+      # @param limit [Int] The maximum number of members to get. Defaults to 500, and cannot be greater than that unless the user is a bot. If the user is a bot, the limit cannot be greater than 5000.
+      # @return [Array] All category members until the limit
       def get_category_members(category, limit = 500)
         params = {
           action: 'query',
@@ -122,7 +97,7 @@ module MediaWiki
           format: 'json'
         }
 
-        if category =~ /Category\:/
+        if category =~ /[Cc]ategory\:/
           params[:cmtitle] = category
         else
           params[:cmtitle] = "Category:#{category}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mediawiki-butt
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Eli Foster
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-25 00:00:00.000000000 Z
+date: 2015-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient