Package: earwigbot
EarwigBotis aPythonrobot that editsWikipediaand interacts with people
overIRC. This file provides a basic overview of how to install and setup the
bot; more detailed information is located in thedocs/directory (available
online atPyPI).HistoryDevelopment began, based on thePywikipedia framework, in early 2009.
Approval for its first task, acopyright violation detector, was carried out
in May, and the bot has been running consistently ever since (with the
exception of Jan/Feb 2011). It currently handlesseveral ongoing tasksranging from statistics generation to category cleanup, and on-demand tasks
such as WikiProject template tagging. Since it started running, the bot has
made over 50,000 edits.A project to rewrite it from scratch began in early April 2011, thus moving
away from the Pywikipedia framework and allowing for less overall code, better
integration between bot parts, and easier maintenance.InstallationThis package contains the coreearwigbot, abstracted enough that it should
be usable and customizable by anyone running a bot on a MediaWiki site. Since
it is component-based, the IRC components can be disabled if desired. IRC
commands and bot tasks specific tomy instance of EarwigBotthat I don’t
feel the average user will need are available from the repositoryearwigbot-plugins.It’s recommended to run the bot’s unit tests before installing. Runpython setup.py testfrom the project’s root directory. Note that some
tests require an internet connection, and others may take a while to run.
Coverage is currently rather incomplete.Latest release (v0.3)EarwigBot is available from thePython Package Index, so you can install the
latest release withpip install earwigbot(get pip).If you get an error while pip is installing dependencies, you may be missing
some header files. For example, on Ubuntu, seethis StackOverflow post.You can also install it from source[1]directly:curl -Lo earwigbot.tgz https://github.com/earwig/earwigbot/tarball/v0.3
tar -xf earwigbot.tgz
cd earwig-earwigbot-*
python setup.py install
cd ..
rm -r earwigbot.tgz earwig-earwigbot-*Development versionYou can install the development version of the bot fromgitby using
setuptools’sdevelopcommand[1], probably on thedevelopbranch which
contains (usually) working code.mastercontains the latest release.
EarwigBot usesgit flow, so you’re free to browse by tags or by new features
(feature/*branches):git clone git://github.com/earwig/earwigbot.git earwigbot
cd earwigbot
python setup.py developSetupThe bot stores its data in a “working directory”, including its config file and
databases. This is also the location where you will place custom IRC commands
and bot tasks, which will be explained later. It doesn’t matter where this
directory is, as long as the bot can write to it.Start the bot withearwigbot path/to/working/dir, or justearwigbotif
the working directory is the current directory. It will notice that noconfig.ymlfile exists and take you through the setup process.There is currently no way to edit theconfig.ymlfile from within the bot
after it has been created, but YAML is a very straightforward format, so you
should be able to make any necessary changes yourself. Check out theexplanation of YAMLon Wikipedia for help.After setup, the bot will start. This means it will connect to the IRC servers
it has been configured for, schedule bot tasks to run at specific times, and
then wait for instructions (as commands on IRC). For a list of commands, say
“!help” (commands are messages prefixed with an exclamation mark).You can stop the bot at any time with Control+C, same as you stop a normal
Python program, and it will try to exit safely. You can also use the
“!quit” command on IRC.CustomizingThe bot’s working directory contains acommandssubdirectory and ataskssubdirectory. Custom IRC commands can be placed in the former,
whereas custom wiki bot tasks go into the latter. Developing custom modules is
explained below, and in more detail through the bot’s documentation onPyPI(or in thedocs/dir).Note that custom commands will override built-in commands and tasks with the
same name.BotandBotConfigearwigbot.bot.Botis EarwigBot’s main class. You don’t have to instantiate
this yourself, but it’s good to be familiar with its attributes and methods,
because it is the main way to communicate with other parts of the bot. ABotobject is accessible as an attribute of commands and tasks (i.e.,self.bot).earwigbot.config.BotConfigstores configuration information for the bot. Its
docstring explains what each attribute is used for, but essentially each “node”
(one ofconfig.components,wiki,irc,commands,tasks, andmetadata) maps to a section of the bot’sconfig.ymlfile. For example,
ifconfig.ymlincludes something like:irc:
    frontend:
        nick: MyAwesomeBot
        channels:
            - "##earwigbot"
            - "#channel"
            - "#other-channel"…thenconfig.irc["frontend"]["nick"]will be"MyAwesomeBot"andconfig.irc["frontend"]["channels"]will be["##earwigbot","#channel","#other-channel"].Custom IRC commandsCustom commands are subclasses ofearwigbot.commands.Commandthat overrideCommand’sprocess()(and optionallycheck(),setup(), orunload()) methods.The bot has a wide selection of built-in commands and plugins to act as sample
code and/or to give ideas. Start withtest, and then check outchanopsandafc_statusfor some more complicated scripts.Custom bot tasksCustom tasks are subclasses ofearwigbot.tasks.Taskthat overrideTask’srun()(and optionallysetup()orunload()) methods.See the built-inwikiproject_taggertask for a relatively straightforward
task, or theafc_statisticsplugin for a more complicated one.The Wiki ToolsetEarwigBot’s answer to thePywikipedia frameworkis the Wiki Toolset
(earwigbot.wiki), which you will mainly access throughbot.wiki.bot.wikiprovides three methods for the management of Sites -get_site(),add_site(), andremove_site(). Sites are objects that
simply represent a MediaWiki site. A single instance of EarwigBot (i.e. a
singleworking directory) is expected to relate to a single site or group of
sites using the same login info (like all WMF wikis with CentralAuth).Load your default site (the one that you picked during setup) withsite = bot.wiki.get_site().Not all aspects of the toolset are covered in the docs. Exploreits code and
docstringsto learn how to use it in a more hands-on fashion. For reference,bot.wikiis an instance ofearwigbot.wiki.SitesDBtied to thesites.dbfile in the bot’s working directory.FootnotesQuestions, comments, or suggestions about the documentation?Let me knowso I can improve it for other people.[1](1,2)python setup.py install/developmay require root, or use the--userswitch to install for the current user only.