[bugfix] Bot class arguments for constructor

Bot class arguments for constructor should be called as keyword argument

Bot class handles 'site' and ' always' as keyword arguments. In replace.py
instantiating the bot uses postional argument which breaks this rule and
derived bots may be break if not all (positional) arguments are given.

- instantiate ReplaceRobot with keyword arguments for 'always' and 'site'
  handled by bot class to allow other bots to use this special bot.
- catch them with **kwargs
- remove unused and deprecated acceptall variable
- change parameter description for ReplaceRobot constructor, markup for epydoc
- move __init__ doc to class because doc strings of hidden methods aren't
  shown in epydoc's documentation.
- this also solves the 2nd warning issue of https://gerrit.wikimedia.org/r/#/c/266321/

Bug: T125046
Bug: T125049
Change-Id: I23570783fda9f497a6f57aaa8f5e17895534af50

scripts/replace.py

@@ -128,7 +128,7 @@
 """
 #
 # (C) Daniel Herding, 2004-2012
-# (C) Pywikibot team, 2004-2015
+# (C) Pywikibot team, 2004-2016
 #
 # Distributed under the terms of the MIT license.
 #
@@ -494,53 +494,58 @@ def isTextExcepted(self, text):
 
 class ReplaceRobot(Bot):
 
-    """A bot that can do text replacements."""
+    """A bot that can do text replacements.
+
+    @param generator: generator that yields Page objects
+    @type generator: generator
+    @param replacements: a list of Replacement instances or sequences of
+        length 2 with the  original text (as a compiled regular expression)
+        and replacement text (as a string).
+    @type replacements: list
+    @param exceptions: a dictionary which defines when not to change an
+        occurrence. This dictionary can have these keys:
+
+        title
+            A list of regular expressions. All pages with titles that
+            are matched by one of these regular expressions are skipped.
+        text-contains
+            A list of regular expressions. All pages with text that
+            contains a part which is matched by one of these regular
+            expressions are skipped.
+        inside
+            A list of regular expressions. All occurrences are skipped which
+            lie within a text region which is matched by one of these
+            regular expressions.
+        inside-tags
+            A list of strings. These strings must be keys from the
+            exceptionRegexes dictionary in textlib.replaceExcept().
+
+    @type exceptions: dict
+    @param allowoverlap: when matches overlap, all of them are replaced.
+    @type allowoverlap: bool
+    @param recursive: Recurse replacement as long as possible.
+    @type recursice: bool
+    @warning: Be careful, this might lead to an infinite loop.
+    @param addedCat: category to be added to every page touched
+    @type addedCat: pywikibot.Category or str or None
+    @param sleep: slow down between processing multiple regexes
+    @type sleep: int
+    @param summary: Set the summary message text bypassing the default
+    @type summary: str
+    @keyword always: the user won't be prompted before changes are made
+    @type keyword: bool
+    @keyword site: Site the bot is working on.
+    @warning: site parameter should be passed to constructor.
+        Otherwise the bot takes the current site and warns the operator
+        about the missing site
+    """
 
     @deprecated_args(acceptall='always')
     def __init__(self, generator, replacements, exceptions={},
-                 always=False, allowoverlap=False, recursive=False,
-                 addedCat=None, sleep=None, summary='', site=None, **kwargs):
-        """
-        Constructor.
-
-        Arguments:
-            * generator    - A generator that yields Page objects.
-            * replacements - A list of Replacement instances or sequences of
-                             length 2 with the  original text (as a compiled
-                             regular expression) and replacement text (as a
-                             string).
-            * exceptions   - A dictionary which defines when not to change an
-                             occurrence. See below.
-            * always       - If True, the user won't be prompted before changes
-                             are made.
-            * allowoverlap - If True, when matches overlap, all of them are
-                             replaced.
-            * addedCat     - If set to a value, add this category to every page
-                             touched.
-                             It can be a string or a Category object.
-
-        Structure of the exceptions dictionary:
-        This dictionary can have these keys:
-
-            title
-                A list of regular expressions. All pages with titles that
-                are matched by one of these regular expressions are skipped.
-            text-contains
-                A list of regular expressions. All pages with text that
-                contains a part which is matched by one of these regular
-                expressions are skipped.
-            inside
-                A list of regular expressions. All occurrences are skipped which
-                lie within a text region which is matched by one of these
-                regular expressions.
-            inside-tags
-                A list of strings. These strings must be keys from the
-                exceptionRegexes dictionary in textlib.replaceExcept().
-
-        """
+                 allowoverlap=False, recursive=False, addedCat=None,
+                 sleep=None, summary='', **kwargs):
+        """Constructor."""
         super(ReplaceRobot, self).__init__(generator=generator,
-                                           always=always,
-                                           site=site,
                                            **kwargs)
 
         for i, replacement in enumerate(replacements):
@@ -554,7 +559,6 @@ def __init__(self, generator, replacements, exceptions={},
                                                             replacement[1])
         self.replacements = replacements
         self.exceptions = exceptions
-        self.acceptall = always  # deprecated
         self.allowoverlap = allowoverlap
         self.recursive = recursive
 
@@ -1130,9 +1134,9 @@ def main(*args):
         return False
 
     preloadingGen = pagegenerators.PreloadingGenerator(gen)
-    bot = ReplaceRobot(preloadingGen, replacements, exceptions, acceptall,
+    bot = ReplaceRobot(preloadingGen, replacements, exceptions,
                        allowoverlap, recursive, add_cat, sleep, edit_summary,
-                       site)
+                       always=acceptall, site=site)
     site.login()
     bot.run()