mediawiki-butt 0.11.1 → 1.0.0

data/lib/mediawiki/butt.rb

@@ -3,6 +3,7 @@ require_relative 'query/query'
 require_relative 'constants'
 require_relative 'edit'
 require_relative 'administration'
+require_relative 'watch'
 require 'httpclient'
 require 'json'
 
@@ -18,35 +19,37 @@ module MediaWiki
     include MediaWiki::Constants
     include MediaWiki::Edit
     include MediaWiki::Administration
+    include MediaWiki::Watch
 
-    # Creates a new instance of MediaWiki::Butt. To work with any
-    # MediaWiki::Butt methods, you must first create an instance of it.
-    # @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.
-    # @param custom_agent [String] A custom User-Agent to use. Optional.
-    # @since 0.1.0
-    def initialize(url, use_ssl = true, custom_agent = nil)
+    attr_accessor :query_limit_default
+
+    # Creates a new instance of MediaWiki::Butt.
+    # @param url [String] The FULL wiki URL. api.php can be omitted, but it will make harsh assumptions about
+    #   your wiki configuration.
+    # @param opts [Hash<Symbol, Any>] The options hash for configuring this instance of Butt.
+    # @option opts [String] :custom_agent A custom User-Agent to use. Optional.
+    # @option opts [Fixnum] :query_limit_default The query limit to use if no limit parameter is explicitly given to
+    #   the various query methods. In other words, if you pass a limit parameter to the valid query methods, it will
+    #   use that, otherwise, it will use this. Defaults to 500. It can be set to 'max' to use MW's default max for
+    #   each API.
+    def initialize(url, opts = {})
       @url = url =~ /api.php$/ ? url : "#{url}/api.php"
+      @query_limit_default = opts[:query_limit_default] || 500
       @client = HTTPClient.new
       @uri = URI.parse(@url)
-      @ssl = use_ssl
       @logged_in = false
-      @custom_agent = custom_agent unless custom_agent.nil?
-      @tokens = {}
+      @custom_agent = opts[:custom_agent]
     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.
-    # @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.
+    # Performs a generic HTTP POST request and provides the response. This method generally should not be used by the
+    # user, unless there is not a helper method provided by Butt for a particular action.
+    # @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.
     # @param header [Hash] The header hash. Optional.
     # @since 0.1.0
-    # @return [JSON/HTTPMessage] Parsed JSON if autoparse is true.
-    # @return [HTTPMessage] Raw HTTP response.
+    # @return [Hash] Parsed JSON if autoparse is true.
+    # @return [HTTPMessage] Raw HTTP response if autoparse is not true.
     def post(params, autoparse = true, header = nil)
       params[:format] = 'json'
       header = {} if header.nil?
@@ -56,11 +59,7 @@ module MediaWiki
 
       res = @client.post(@uri, params, header)
 
-      if autoparse
-        return JSON.parse(res.body)
-      else
-        return res
-      end
+      autoparse ? JSON.parse(res.body) : res
     end
 
     # Gets whether the currently logged in user is a bot.
@@ -73,18 +72,38 @@ module MediaWiki
     # @since 0.4.1 as user_bot?
     def user_bot?(username = nil)
       groups = false
+      name = username || @name
+      groups = get_usergroups(name) if name
+      groups && groups.include?('bot')
+    end
 
-      if !username.nil?
-        groups = get_usergroups(username)
-      else
-        groups = get_usergroups if @logged_in
+    protected
+
+    # Gets the limited version of the integer, to ensure nobody provides an int that is too large.
+    # @param integer [Fixnum] The number to limit.
+    # @param max_user [Fixnum] The maximum limit for normal users.
+    # @param max_bot [Fixnum] The maximum limit for bot users.
+    # @since 0.8.0
+    # @return [Fixnum] The capped number.
+    def get_limited(integer, max_user = 500, max_bot = 5000)
+      if integer.is_a?(String)
+        return integer if integer == 'max'
+        return 500
       end
+      return integer if integer <= max_user
 
-      if groups != false
-        return groups.include?('bot')
+      if user_bot?
+        integer > max_bot ? max_bot : integer
       else
-        return false
+        max_user
       end
     end
+
+    # Safely validates the given namespace ID, and returns 0 for the main namespace if invalid.
+    # @param namespace [Fixnum] The namespace ID.
+    # @return [Fixnum] Either the given namespace, if valid, or the main namespace ID 0 if invalid.
+    def validate_namespace(namespace)
+      MediaWiki::Constants::NAMESPACES.value?(namespace) ? namespace : 0
+    end
   end
 end

data/lib/mediawiki/constants.rb

@@ -3,224 +3,221 @@ module MediaWiki
     # @since 0.2.0 as a module with individual global constants
     # @since 0.4.0 as a module with a single global hash identical to this.
     # @since 0.8.0 as its current state.
-    # @see https://www.mediawiki.org/wiki/Extension_default_namespaces
-    #   MediaWiki's list of extension namespace IDs and names.
-    # @return [Hash<String, Integer>] The upcased namespace names, and their according ID. The keys, values, and
+    # @see https://www.mediawiki.org/wiki/Extension_default_namespaces MediaWiki's list of extension namespace IDs
+    #   and names.
+    # @return [Hash<String, Fixnum>] The upcased namespace names, and their according ID. The keys, values, and
     #   return value itself are all immutable.
     NAMESPACES = {
-      'MAIN'.freeze => 0.freeze,
-      'TALK'.freeze => 1.freeze,
-      'USER'.freeze => 2.freeze,
-      'USER_TALK'.freeze => 3.freeze,
-      'PROJECT'.freeze => 4.freeze,
-      'PROJECT_TALK'.freeze => 5.freeze,
-      'FILE'.freeze => 6.freeze,
-      'FILE_TALK'.freeze => 7.freeze,
-      'MEDIAWIKI'.freeze => 8.freeze,
-      'MEDIAWIKI_TALK'.freeze => 9.freeze,
-      'TEMPLATE'.freeze => 10.freeze,
-      'TEMPLATE_TALK'.freeze => 11.freeze,
-      'HELP'.freeze => 12.freeze,
-      'HELP_TALK'.freeze => 13.freeze,
-      'CATEGORY'.freeze => 14.freeze,
-      'CATEGORY_TALK'.freeze => 15.freeze,
-      'SPECIAL'.freeze => -1.freeze,
-      'MEDIA'.freeze => -2.freeze,
+      'MAIN'.freeze => 0,
+      'TALK'.freeze => 1,
+      'USER'.freeze => 2,
+      'USER_TALK'.freeze => 3,
+      'PROJECT'.freeze => 4,
+      'PROJECT_TALK'.freeze => 5,
+      'FILE'.freeze => 6,
+      'FILE_TALK'.freeze => 7,
+      'MEDIAWIKI'.freeze => 8,
+      'MEDIAWIKI_TALK'.freeze => 9,
+      'TEMPLATE'.freeze => 10,
+      'TEMPLATE_TALK'.freeze => 11,
+      'HELP'.freeze => 12,
+      'HELP_TALK'.freeze => 13,
+      'CATEGORY'.freeze => 14,
+      'CATEGORY_TALK'.freeze => 15,
+      'SPECIAL'.freeze => -1,
+      'MEDIA'.freeze => -2,
 
       # Extension:LiquidThreads
-      'LQT_THREAD'.freeze => 90.freeze,
-      'LQT_THREAD_TALK'.freeze => 91.freeze,
-      'LQT_SUMMARY'.freeze => 92.freeze,
-      'LQT_SUMMARY_TALK'.freeze => 93.freeze,
+      'LQT_THREAD'.freeze => 90,
+      'LQT_THREAD_TALK'.freeze => 91,
+      'LQT_SUMMARY'.freeze => 92,
+      'LQT_SUMMARY_TALK'.freeze => 93,
 
       # Extension:Semantic MediaWiki / Extension:Semantic Forms
-      'SMW_RELATION'.freeze => 100.freeze,
-      'SMW_RELATION_TALK'.freeze => 101.freeze,
-      'SMW_PROPERTY'.freeze => 102.freeze,
-      'SMW_PROPERTY_TALK'.freeze => 103.freeze,
-      'SMW_TYPE'.freeze => 104.freeze,
-      'SMW_TYPE_TALK'.freeze => 105.freeze,
-      'SMW_FORM'.freeze => 106.freeze,
-      'SMW_FORM_TALK'.freeze => 107.freeze,
-      'SF_CONCEPT'.freeze => 108.freeze,
-      'SF_CONCEPT_TALK'.freeze => 109.freeze,
+      'SMW_RELATION'.freeze => 100,
+      'SMW_RELATION_TALK'.freeze => 101,
+      'SMW_PROPERTY'.freeze => 102,
+      'SMW_PROPERTY_TALK'.freeze => 103,
+      'SMW_TYPE'.freeze => 104,
+      'SMW_TYPE_TALK'.freeze => 105,
+      'SMW_FORM'.freeze => 106,
+      'SMW_FORM_TALK'.freeze => 107,
+      'SF_CONCEPT'.freeze => 108,
+      'SF_CONCEPT_TALK'.freeze => 109,
 
       # Extension:DPLforum
-      'DPLF_FORUM'.freeze => 110.freeze,
-      'DPLF_FORUM_TAlK'.freeze => 111.freeze,
+      'DPLF_FORUM'.freeze => 110,
+      'DPLF_FORUM_TAlK'.freeze => 111,
 
       # Extension:RefHelper
-      'RFH_CITE'.freeze => 120.freeze,
-      'RFH_CITE_TALK'.freeze => 121.freeze,
+      'RFH_CITE'.freeze => 120,
+      'RFH_CITE_TALK'.freeze => 121,
 
       # Extension:SemanticAccessControl
-      'ACL_USERGROUP'.freeze => 160.freeze,
-      'ACL_ACL'.freeze => 162.freeze,
+      'ACL_USERGROUP'.freeze => 160,
+      'ACL_ACL'.freeze => 162,
 
       # Extension:Semantic Drilldown
-      'SED_FILTER'.freeze => 170.freeze,
-      'SED_FILTER_TALK'.freeze => 171.freeze,
+      'SED_FILTER'.freeze => 170,
+      'SED_FILTER_TALK'.freeze => 171,
 
       # Extension:SocialProfile
-      'SCP_USERWIKI'.freeze => 200.freeze,
-      'SCP_USERWIKI_TALK'.freeze => 201.freeze,
-      'SCP_USERPROFILE'.freeze => 202.freeze,
-      'SCP_USERPROFILE_TALK'.freeze => 203.freeze,
+      'SCP_USERWIKI'.freeze => 200,
+      'SCP_USERWIKI_TALK'.freeze => 201,
+      'SCP_USERPROFILE'.freeze => 202,
+      'SCP_USERPROFILE_TALK'.freeze => 203,
 
       # Extension:Proofread Page
-      'PRP_PAGE'.freeze => 250.freeze,
-      'PRP_PAGE_TALK'.freeze => 251.freeze,
-      'PRP_INDEX'.freeze => 252.freeze,
-      'PRP_INDEX_TALK'.freeze => 253.freeze,
+      'PRP_PAGE'.freeze => 250,
+      'PRP_PAGE_TALK'.freeze => 251,
+      'PRP_INDEX'.freeze => 252,
+      'PRP_INDEX_TALK'.freeze => 253,
 
       # Extension:TrustedMath
-      'TRM_MATH'.freeze => 262.freeze,
-      'TRM_MATH_TALK'.freeze => 263.freeze,
+      'TRM_MATH'.freeze => 262,
+      'TRM_MATH_TALK'.freeze => 263,
 
       # Extension:Widgets
-      'WID_WIDGET'.freeze => 274.freeze,
-      'WID_WIDGET_TALK'.freeze => 275.freeze,
+      'WID_WIDGET'.freeze => 274,
+      'WID_WIDGET_TALK'.freeze => 275,
 
       # Extension:EmbedScript
-      'EMS_JSAPPLET'.freeze => 280.freeze,
-      'EMS_JSAPPLET_TALK'.freeze => 281.freeze,
+      'EMS_JSAPPLET'.freeze => 280,
+      'EMS_JSAPPLET_TALK'.freeze => 281,
 
       # Extension:PollNY
-      'PLN_POLL'.freeze => 300.freeze,
-      'PLN_POLL_TALK'.freeze => 301.freeze,
+      'PLN_POLL'.freeze => 300,
+      'PLN_POLL_TALK'.freeze => 301,
 
       # Extension:Semantic Image Annotator
-      'SIA_IMAGE_ANNOTATOR'.freeze => 380.freeze,
+      'SIA_IMAGE_ANNOTATOR'.freeze => 380,
 
       # Extension:Wiki2LaTeX
-      'WTL_WIKI2LATEX'.freeze => 400.freeze,
-      'WTL_WIKI2LATEX_TALK'.freeze => 401.freeze,
+      'WTL_WIKI2LATEX'.freeze => 400,
+      'WTL_WIKI2LATEX_TALK'.freeze => 401,
 
       # Extension:Workflow
-      'WRF_WORKFLOW'.freeze => 410.freeze,
-      'WRF_WORKFLOW_TALK'.freeze => 411.freeze,
+      'WRF_WORKFLOW'.freeze => 410,
+      'WRF_WORKFLOW_TALK'.freeze => 411,
 
       # Extension:Maps
-      'MAP_LAYER'.freeze => 420.freeze,
-      'MAP_LAYER_TALK'.freeze => 421.freeze,
+      'MAP_LAYER'.freeze => 420,
+      'MAP_LAYER_TALK'.freeze => 421,
 
       # Extension:QuizTabulate
-      'QTB_QUIZ'.freeze => 430.freeze,
-      'QTB_QUIZ_TALK'.freeze => 431.freeze,
+      'QTB_QUIZ'.freeze => 430,
+      'QTB_QUIZ_TALK'.freeze => 431,
 
       # Extension:Education Program
-      'EDP_EDUCATION_PROGRAM'.freeze => 446.freeze,
-      'EDP_EDUCATION_PROGRAM_TALK'.freeze => 447.freeze,
+      'EDP_EDUCATION_PROGRAM'.freeze => 446,
+      'EDP_EDUCATION_PROGRAM_TALK'.freeze => 447,
 
       # Extension:BoilerRoom
-      'BLR_BOILERPLATE'.freeze => 450.freeze,
-      'BLR_BOILERPLATE_TALK'.freeze => 451.freeze,
+      'BLR_BOILERPLATE'.freeze => 450,
+      'BLR_BOILERPLATE_TALK'.freeze => 451,
 
       # Extension:UploadWizard
-      'UPW_CAMPAIGN'.freeze => 460.freeze,
-      'UPW_CAMPAIGN_TALK'.freeze => 461.freeze,
+      'UPW_CAMPAIGN'.freeze => 460,
+      'UPW_CAMPAIGN_TALK'.freeze => 461,
 
       # Extension:EventLogging
-      'ELG_SCHEMA'.freeze => 470.freeze,
-      'ELG_SCHEMA_TALK'.freeze => 471.freeze,
+      'ELG_SCHEMA'.freeze => 470,
+      'ELG_SCHEMA_TALK'.freeze => 471,
 
       # Extension:ZeroBanner
-      'ZRB_ZERO'.freeze => 480.freeze,
-      'ZRB_ZERO_TALK'.freeze => 481.freeze,
+      'ZRB_ZERO'.freeze => 480,
+      'ZRB_ZERO_TALK'.freeze => 481,
 
       # Extension:JsonConfig
-      'JSC_CONFIG'.freeze => 482.freeze,
-      'JSC_CONFIG_TALK'.freeze => 483.freeze,
-      'JSC_DATA'.freeze => 486.freeze,
-      'JSC_DATA_TALK'.freeze => 487.freeze,
+      'JSC_CONFIG'.freeze => 482,
+      'JSC_CONFIG_TALK'.freeze => 483,
+      'JSC_DATA'.freeze => 486,
+      'JSC_DATA_TALK'.freeze => 487,
 
       # Extension:Graph
-      'GRP_GRAPH'.freeze => 484.freeze,
-      'GRP_GRAPH_TALK'.freeze => 485.freeze,
+      'GRP_GRAPH'.freeze => 484,
+      'GRP_GRAPH_TALK'.freeze => 485,
 
       # Extension:OpenStackManager
-      'OSM_NOVA_RESOURCE'.freeze => 488.freeze,
-      'OSM_NOVA_RESOURCE_TALK'.freeze => 489.freeze,
+      'OSM_NOVA_RESOURCE'.freeze => 488,
+      'OSM_NOVA_RESOURCE_TALK'.freeze => 489,
 
       # Extension:GWToolset
-      'GWT_GWTOOLSET'.freeze => 490.freeze,
-      'GWT_GWTOOLSET_TALK'.freeze => 491.freeze,
+      'GWT_GWTOOLSET'.freeze => 490,
+      'GWT_GWTOOLSET_TALK'.freeze => 491,
 
       # Extension:BlogPage
-      'BLP_BLOG'.freeze => 500.freeze,
-      'BLP_BLOG_TALK'.freeze => 501.freeze,
+      'BLP_BLOG'.freeze => 500,
+      'BLP_BLOG_TALK'.freeze => 501,
 
       # Extension:XMLContentExtension
-      'XCE_XML'.freeze => 580.freeze,
-      'XCE_XML_TALK'.freeze => 581.freeze,
-      'XCE_SCHEMA'.freeze => 582.freeze,
-      'XCE_SCHEMA_TALK'.freeze => 583.freeze,
+      'XCE_XML'.freeze => 580,
+      'XCE_XML_TALK'.freeze => 581,
+      'XCE_SCHEMA'.freeze => 582,
+      'XCE_SCHEMA_TALK'.freeze => 583,
 
       # Extension:FanBoxes
-      'FNB_USERBOX'.freeze => 600.freeze,
-      'FNB_USERBOX_TALK'.freeze => 601.freeze,
+      'FNB_USERBOX'.freeze => 600,
+      'FNB_USERBOX_TALK'.freeze => 601,
 
       # Extension:LinkFilter
-      'LFT_LINK'.freeze => 700.freeze,
-      'LFT_LINK_TALK'.freeze => 701.freeze,
+      'LFT_LINK'.freeze => 700,
+      'LFT_LINK_TALK'.freeze => 701,
 
       # Extension:TimedMediaHandler
-      'TMH_TIMEDTEXT'.freeze => 710.freeze,
-      'TMH_TIMEDTEXT_TALK'.freeze => 711.freeze,
+      'TMH_TIMEDTEXT'.freeze => 710,
+      'TMH_TIMEDTEXT_TALK'.freeze => 711,
 
       # Extension:QPoll
-      'QPL_INTERPRETATION'.freeze => 800.freeze,
-      'QPL_INTERPRETATION_TALK'.freeze => 801.freeze,
+      'QPL_INTERPRETATION'.freeze => 800,
+      'QPL_INTERPRETATION_TALK'.freeze => 801,
 
       # Extension:SemanticMustacheFormat :3
-      'SMF_MUSTACHE'.freeze => 806.freeze,
-      'SMF_MUSTACHE_TALK'.freeze => 807.freeze,
+      'SMF_MUSTACHE'.freeze => 806,
+      'SMF_MUSTACHE_TALK'.freeze => 807,
 
       # Extension:R
-      'R_R'.freeze => 814.freeze,
-      'R_R_TALK'.freeze => 815.freeze,
+      'R_R'.freeze => 814,
+      'R_R_TALK'.freeze => 815,
 
       # Extension:Scribunto
-      'SCR_MODULE'.freeze => 828.freeze,
-      'SCR_MODULE_TALK'.freeze => 829.freeze,
+      'SCR_MODULE'.freeze => 828,
+      'SCR_MODULE_TALK'.freeze => 829,
 
       # Extension:SecurePoll
-      'SEP_SECUREPOLL'.freeze => 830.freeze,
-      'SEP_SECUREPOLL_TALK'.freeze => 831.freeze,
+      'SEP_SECUREPOLL'.freeze => 830,
+      'SEP_SECUREPOLL_TALK'.freeze => 831,
 
       # Extension:CentralNotice
-      'CNT_CNBANNER'.freeze => 866.freeze,
-      'CNT_CNBANNER_TALK'.freeze => 867.freeze,
+      'CNT_CNBANNER'.freeze => 866,
+      'CNT_CNBANNER_TALK'.freeze => 867,
 
       # Extension:Translate
-      'TRN_TRANSLATIONS'.freeze => 1198.freeze,
-      'TRN_TRANSLATIOTALK'.freeze => 1199.freeze,
+      'TRN_TRANSLATIONS'.freeze => 1198,
+      'TRN_TRANSLATIOTALK'.freeze => 1199,
 
       # Extension:PackageForce
-      'PKF_PACKAGEFORCE'.freeze => 1300.freeze,
-      'PKF_PACKAGEFORCE_TALK'.freeze => 1301.freeze,
+      'PKF_PACKAGEFORCE'.freeze => 1300,
+      'PKF_PACKAGEFORCE_TALK'.freeze => 1301,
 
       # Extension:BlueSpice
-      'BLS_BLOG'.freeze => 1502.freeze,
-      'BLS_BLOG_TALK'.freeze => 1503.freeze,
-      'BLS_BOOK'.freeze => 1504.freeze,
-      'BLS_BOOK_TALK'.freeze => 1505.freeze,
+      'BLS_BLOG'.freeze => 1502,
+      'BLS_BLOG_TALK'.freeze => 1503,
+      'BLS_BOOK'.freeze => 1504,
+      'BLS_BOOK_TALK'.freeze => 1505,
 
       # Extension:Gadgets
-      'GDG_GADGET'.freeze => 2300.freeze,
-      'GDG_GADGET_TALK'.freeze => 2301.freeze,
-      'GDG_GADGET_DEFININTION'.freeze => 2302.freeze,
-      'GDG_GADGET_DEFININTION_TALK'.freeze => 2303.freeze,
+      'GDG_GADGET'.freeze => 2300,
+      'GDG_GADGET_TALK'.freeze => 2301,
+      'GDG_GADGET_DEFININTION'.freeze => 2302,
+      'GDG_GADGET_DEFININTION_TALK'.freeze => 2303,
 
       # Extension:VisualEditor
-      'VSE_VISUALEDITOR'.freeze => 2500.freeze,
-      'VSE_VISUALEDITOR_TALK'.freeze => 2501.freeze,
+      'VSE_VISUALEDITOR'.freeze => 2500,
+      'VSE_VISUALEDITOR_TALK'.freeze => 2501,
 
       # Extension:Flow
-      'FLW_TOPIC'.freeze => 2600.freeze
+      'FLW_TOPIC'.freeze => 2600
     }.freeze
-
-    # @return [String] MediaWiki's timestamp format as an immutable string for DateTime uses.
-    TIME_FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
   end
 end