jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/699760 )
Change subject: [doc] Add the library usage to the documentation ......................................................................
[doc] Add the library usage to the documentation
Also require sphinx 3.5+ due to auto indentation
Depends-On: I8c9a92adf4be4b29f69ee3723ab81054328be351 Change-Id: Ic0fd512b442833b2807fea6fc47fa7c9a5306073 --- M docs/library_usage.rst M docs/requirements-py3.txt 2 files changed, 85 insertions(+), 2 deletions(-)
Approvals: JJMC89: Looks good to me, approved jenkins-bot: Verified
diff --git a/docs/library_usage.rst b/docs/library_usage.rst index 36ef39a..95da419 100644 --- a/docs/library_usage.rst +++ b/docs/library_usage.rst @@ -1,5 +1,88 @@ Using pywikibot as library --------------------------
+Pywikibot provides bot classes to develop your own script easily. Here +is a minimal example script which shows their usage: + +.. code-block:: python + :linenos: + :emphasize-lines: 5,12,18 + + import pywikibot + from pywikibot import pagegenerators + from pywikibot.bot import ExistingPageBot + + class MyBot(ExistingPageBot): + + update_options = { + 'text': 'This is a test text', + 'summary': 'Bot: a bot test edit with Pywikbot.', + } + + def treat_page(self): + """Load the given page, do some changes, and save it.""" + text = self.current_page.text + text += '\n' + self.opt.text + self.put_current(text, summary=self.opt.summary) + + def main(): + """Parse command line arguments and invoke bot.""" + options = {} + gen_factory = pagegenerators.GeneratorFactory() + # Option parsing + local_args = pywikibot.handle_args(args) # global options + local_args = gen_factory.handle_args(local_args) # generators options + for arg in local_args: + opt, sep, value = arg.partition(':') + if opt in ('-summary', '-text'): + options[opt[1:]] = value + MyBot(generator=gen_factory.getCombinedGenerator(), **options).run() + + if __name == '__main__': + main() + +The script can be invoked from commandline like:: + + python mybot -site:wikipedia:test -page:Sandbox -text:"A text added to the sandbox" + +**Explanations:** + +:1-3: Import necessary framework code parts +:5: The bot is derived from ExistingPageBot. All pages from generator + which does not exists are skipped. +:7: Every Bot has an *always* option which autoconfirms any changes if + set to True. To expand all available options of a bot and set the + default values of them, use `update_options` attribute or update + `available_options` like it is shown in BasicBot below. +:12: All changes for each page are made in this method. +:14: `currentpage` is the current :py:obj:`pywikibot.Page` object from + generator. +:15: All bot options which are passed to the bot class when + instantiating it are accessable via opt attribute. `opt.always`, + `opt.text` and `opt.summary` are all available options for this + bot class. +:16: Save the changes to the live wiki. +:18: Parse command line options inside this function. +:20: A dict which holds all options for the bot. +:21: :py:obj:`pywikibot.pagegenerators.GeneratorFactory` supports + generators and filter options. +:23: Pywikibot provides global options like site specification or + a simulate switch to prevent live wiki changes. +:24: Generators and filter options of :py:obj:`pywikibot.pagegenerators` + are parsed here. +:25: Local options which are are available for the current bot are + parsed in this loop. +:29: Create the bot passing keyword only parameters and run it. + +Basic script +~~~~~~~~~~~~ + +:py:obj:`scripts.basic` is a more advanced sample script and shipped +with the scripts folder. Here is the content: + +.. literalinclude:: ../scripts/basic.py + :language: python + .. note:: - Please see the documentation at `Manual:Pywikibot/Create your own script https://www.mediawiki.org/wiki/Manual:Pywikibot/Create_your_own_script`_ + Please also see the documentation at + `Manual:Pywikibot/Create your own script https://www.mediawiki.org/wiki/Manual:Pywikibot/Create_your_own_script`_ diff --git a/docs/requirements-py3.txt b/docs/requirements-py3.txt index d455bf2..f6022b4 100644 --- a/docs/requirements-py3.txt +++ b/docs/requirements-py3.txt @@ -1,4 +1,4 @@ # This is a PIP requirements file for building Sphinx documentation of pywikibot # requirements.txt is also needed
-sphinx >= 1.8, != 3.1.0, != 3.5.0, != 4.0.0 \ No newline at end of file +sphinx > 3.5.0, != 4.0.0 \ No newline at end of file