Skip to content

Latest commit

 

History

History
107 lines (89 loc) · 3.94 KB

library_usage.rst

File metadata and controls

107 lines (89 loc) · 3.94 KB

Using pywikibot as library

Pywikibot provides bot classes to develop your own script easily.

Minimal example

Here is a minimal example script which shows their usage:

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 Pywikibot.',
    }

    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()  # 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"

Explanation

1-3:Import necessary framework code parts: :mod:`pywikibot`, :mod:`pywikibot.pagegenerators`, :class:`bot.ExistingPageBot`.
5:The bot is derived from :class:`ExistingPageBot<bot.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 :attr:`update_options<bot.BaseBot.update_options>` attribute or update :attr:`available_options<bot.BaseBot.available_options>` like it is shown in :ref:`BasicBot<Basic script>` below.
12:All changes for each page are made in this :meth:`treat_page<bot.CurrentPageBot.treat_page>` method.
14::attr:`current_page<bot.BaseBot.current_page>` is the current :class:`pywikibot.Page` object from :attr:`generator<bot.BaseBot.generator>`.
15:All bot options which are passed to the bot class when instantiating it are accessable via :class:`opt attribute<bot.OptionHandler>`. opt.always, opt.text and opt.summary are all available options for this bot class.
16:Save the changes to the live wiki with :meth:`put_current<bot.CurrentPageBot.put_current>`.
18:Parse command line options inside this function.
20:A dict which holds all options for the bot.
21::py:obj:`pagegenerators.GeneratorFactory` supports generators and filter options.
23:Pywikibot provides :ref:`global options<Global Options>` like site specification or a simulate switch to prevent live wiki changes. These options are parsed by :func:`pywikibot.handle_args`.
24::ref:`Generators<Generator Options>` and :ref:`filter options<Filter Options>` of :mod:`pywikibot.pagegenerators` are parsed here using :meth:`GeneratorFactory.handle_args() <pagegenerators.GeneratorFactory.handle_args>`.
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

Also see the documentation at :manpage:`Create your own script`