earwigbot Package

earwigbot Package

EarwigBot is a Python robot that edits Wikipedia and interacts with people over IRC.

See README.rst for an overview, or the docs/ directory for details. This documentation is also available online.

bot Module

class earwigbot.bot.Bot(root_dir, level=20)

EarwigBot: Main Bot Class

The Bot class is the core of EarwigBot, essentially responsible for starting the various bot components and making sure they are all happy.

EarwigBot has three components that can run independently of each other: an IRC front-end, an IRC watcher, and a wiki scheduler.

• The IRC front-end runs on a normal IRC server and expects users to interact with it/give it commands.
• The IRC watcher runs on a wiki recent-changes server and listens for edits. Users cannot interact with this part of the bot.
• The wiki scheduler runs wiki-editing bot tasks in separate threads at user-defined times through a cron-like interface.

The Bot object is accessible from within commands and tasks as self.bot. This is the primary way to access data from other components of the bot. For example, our BotConfig object is accessable from bot.config, tasks can be started with bot.tasks.start(), and sites can be loaded from the wiki toolset with bot.wiki.get_site().

is_running

Whether or not the bot is currently running.

This may return False even if the bot is still technically active, but in the process of shutting down.

restart(msg=None)

Reload config, commands, tasks, and safely restart IRC components.

This is thread-safe, and it will gracefully stop IRC components before reloading anything. Note that you can safely reload commands or tasks without restarting the bot with bot.commands.load() or bot.tasks.load(). These should not interfere with running components or tasks.

If given, msg will be used as our quit message.

run()

Main entry point into running the bot.

Starts all config-enabled components and then enters an idle loop, ensuring that all components remain online and restarting components that get disconnected from their servers.

stop(msg=None)

Gracefully stop all bot components.

If given, msg will be used as our quit message.

exceptions Module

EarwigBot: Exceptions

This module contains all exceptions used by EarwigBot:

EarwigBotError
 +-- NoConfigError
 +-- IRCError
 |    +-- BrokenSocketError
 +-- WikiToolsetError
      +-- SiteNotFoundError
      +-- ServiceError
      |    +-- APIError
      |    +-- SQLError
      +-- NoServiceError
      +-- LoginError
      +-- PermissionsError
      +-- NamespaceNotFoundError
      +-- PageNotFoundError
      +-- InvalidPageError
      +-- RedirectError
      +-- UserNotFoundError
      +-- EditError
      |    +-- EditConflictError
      |    +-- NoContentError
      |    +-- ContentTooBigError
      |    +-- SpamDetectedError
      |    +-- FilteredError
      +-- CopyvioCheckError
           +-- UnknownSearchEngineError
           +-- UnsupportedSearchEngineError
           +-- SearchQueryError
           +-- ParserExclusionError

exception earwigbot.exceptions.APIError

Bases: earwigbot.exceptions.ServiceError

Couldn’t connect to a site’s API.

Perhaps the server doesn’t exist, our URL is wrong or incomplete, or there are temporary problems on their end.

Raised by Site.api_query.

exception earwigbot.exceptions.BrokenSocketError

Bases: earwigbot.exceptions.IRCError

A socket has broken, because it is not sending data.

Raised by IRCConnection._get.

exception earwigbot.exceptions.ContentTooBigError

Bases: earwigbot.exceptions.EditError

The edit we tried to push exceeded the article size limit.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.CopyvioCheckError

Bases: earwigbot.exceptions.WikiToolsetError

An error occured when checking a page for copyright violations.

This is a base class for multiple exceptions; usually one of those will be raised instead of this.

Raised by Page.copyvio_check and Page.copyvio_compare.

exception earwigbot.exceptions.EarwigBotError

Bases: exceptions.Exception

Base exception class for errors in EarwigBot.

exception earwigbot.exceptions.EditConflictError

Bases: earwigbot.exceptions.EditError

We gotten an edit conflict or a (rarer) delete/recreate conflict.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.EditError

Bases: earwigbot.exceptions.WikiToolsetError

An error occured while editing.

This is used as a base class for all editing errors; this one specifically is used only when a generic error occurs that we don’t know about.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.FilteredError

Bases: earwigbot.exceptions.EditError

The edit filter refused our edit.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.IRCError

Bases: earwigbot.exceptions.EarwigBotError

Base exception class for errors in IRC-relation sections of the bot.

exception earwigbot.exceptions.InvalidPageError

Bases: earwigbot.exceptions.WikiToolsetError

Attempted to get information about a page whose title is invalid.

Raised by Page.

exception earwigbot.exceptions.LoginError

Bases: earwigbot.exceptions.WikiToolsetError

An error occured while trying to login.

Perhaps the username/password is incorrect.

Raised by Site._login.

exception earwigbot.exceptions.NamespaceNotFoundError

Bases: earwigbot.exceptions.WikiToolsetError

A requested namespace name or namespace ID does not exist.

Raised by Site.namespace_id_to_name and Site.namespace_name_to_id.

exception earwigbot.exceptions.NoConfigError

Bases: earwigbot.exceptions.EarwigBotError

The bot cannot be run without a config file.

This occurs if no config file exists, and the user said they did not want one to be created.

exception earwigbot.exceptions.NoContentError

Bases: earwigbot.exceptions.EditError

We tried to create a page or new section with no content.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.NoServiceError

Bases: earwigbot.exceptions.WikiToolsetError

No service is functioning to handle a specific task.

Raised by Site.delegate.

exception earwigbot.exceptions.PageNotFoundError

Bases: earwigbot.exceptions.WikiToolsetError

Attempted to get information about a page that does not exist.

Raised by Page.

exception earwigbot.exceptions.ParserExclusionError

Bases: earwigbot.exceptions.CopyvioCheckError

A content parser detected that the given source should be excluded.

Raised internally by Page.copyvio_check; should not be exposed in client code.

exception earwigbot.exceptions.PermissionsError

Bases: earwigbot.exceptions.WikiToolsetError

A permissions error ocurred.

We tried to do something we don’t have permission to, like trying to delete a page as a non-admin, or trying to edit a page without login information and AssertEdit enabled. This will also be raised if we have been blocked from editing.

Raised by Page.edit, Page.add_section, and other API methods depending on settings.

exception earwigbot.exceptions.RedirectError

Bases: earwigbot.exceptions.WikiToolsetError

A redirect-only method was called on a malformed or non-redirect page.

Raised by Page.get_redirect_target.

exception earwigbot.exceptions.SQLError

Bases: earwigbot.exceptions.ServiceError

Some error involving SQL querying occurred.

Raised by Site.sql_query.

exception earwigbot.exceptions.SearchQueryError

Bases: earwigbot.exceptions.CopyvioCheckError

Some error ocurred while doing a search query.

Raised by Page.copyvio_check.

exception earwigbot.exceptions.ServiceError

Bases: earwigbot.exceptions.WikiToolsetError

Base exception class for an error within a service (the API or SQL).

This is caught by Site.delegate to indicate a service is non-functional so another, less-preferred one can be tried.

exception earwigbot.exceptions.SiteNotFoundError

Bases: earwigbot.exceptions.WikiToolsetError

A particular site could not be found in the sites database.

Raised by SitesDB.

exception earwigbot.exceptions.SpamDetectedError

Bases: earwigbot.exceptions.EditError

The spam filter refused our edit.

Raised by Page.edit and Page.add_section.

exception earwigbot.exceptions.UnknownSearchEngineError

Bases: earwigbot.exceptions.CopyvioCheckError

Attempted to do a copyvio check with an unknown search engine.

Search engines are specified in config.yml as config.wiki["search"]["engine"].

Raised by Page.copyvio_check.

exception earwigbot.exceptions.UnsupportedSearchEngineError

Bases: earwigbot.exceptions.CopyvioCheckError

Attmpted to do a copyvio check using an unavailable engine.

This might occur if, for example, an engine requires oauth2 but the package couldn’t be imported.

Raised by Page.copyvio_check.

exception earwigbot.exceptions.UserNotFoundError

Bases: earwigbot.exceptions.WikiToolsetError

Attempted to get certain information about a user that does not exist.

Raised by User.

exception earwigbot.exceptions.WikiToolsetError

Bases: earwigbot.exceptions.EarwigBotError

Base exception class for errors in the Wiki Toolset.

lazy Module

Implements a hierarchy of importing classes as defined in PEP 302 to load modules in a safe yet lazy manner, so that they can be referred to by name but are not actually loaded until they are used (i.e. their attributes are read or modified).

class earwigbot.lazy.LazyImporter

An importer for modules that are loaded lazily.

This inserts itself into sys.meta_path, storing a dictionary of _LazyModules (which is added to with new()).

find_module(fullname, path=None)

load_module(fullname)

new(name)

managers Module

class earwigbot.managers._ResourceManager(bot, name, base)

Bases: object

EarwigBot: Resource Manager

Resources are essentially objects dynamically loaded by the bot, both packaged with it (built-in resources) and created by users (plugins, aka custom resources). Currently, the only two types of resources are IRC commands and bot tasks. These are both loaded from two locations: the earwigbot.commands and earwigbot.tasks packages, and the commands/ and tasks/ directories within the bot’s working directory.

This class handles the low-level tasks of (re)loading resources via load(), retrieving specific resources via get(), and iterating over all resources via __iter__().

get(key)

Return the class instance associated with a certain resource.

Will raise KeyError if the resource (a command or task) is not found.

load()

Load (or reload) all valid resources into _resources.

lock

The resource access/modify lock.

class earwigbot.managers.CommandManager(bot)

Bases: earwigbot.managers._ResourceManager

Manages (i.e., loads, reloads, and calls) IRC commands.

call(hook, data)

Respond to a hook type and a Data object.

Note

The special rc hook actually passes a RC object.

class earwigbot.managers.TaskManager(bot)

Bases: earwigbot.managers._ResourceManager

Manages (i.e., loads, reloads, schedules, and runs) wiki bot tasks.

schedule(now=None)

Start all tasks that are supposed to be run at a given time.

start(task_name, **kwargs)

Start a given task in a new daemon thread, and return the thread.

kwargs are passed to task.run(). If the task is not found, None will be returned and an error will be logged.

util Module

usage: earwigbot [-h] [-v] [-d | -q] [-t NAME] [PATH] ...

This is EarwigBot’s command-line utility, enabling you to easily start the bot or run specific tasks.

PATH

path to the bot’s working directory, which will be created if it doesn’t exist; current directory assumed if not specified

-h, --help

show this help message and exit

-v, --version

show program’s version number and exit

-d, --debug

print all logs, including DEBUG-level messages

-q, --quiet

don’t print any logs except warnings and errors

-t NAME, --task NAME

given the name of a task, the bot will run it instead of the main bot and then exit

TASK_ARGS

with –task, will pass any remaining arguments to the task’s Task.run() method

earwigbot.util.main()

Main entry point for the command-line utility.

Subpackages

• commands Package
  • commands Package
• config Package
  • config Package
  • formatter Module
  • node Module
  • ordered_yaml Module
  • permissions Module
  • script Module
• irc Package
  • irc Package
  • connection Module
  • data Module
  • frontend Module
  • rc Module
  • watcher Module
• tasks Package
  • tasks Package
  • wikiproject_tagger Module
• wiki Package
  • wiki Package
  • category Module
  • constants Module
  • page Module
  • site Module
  • sitesdb Module
  • user Module
  • Subpackages
    • copyvios Package
      • copyvios Package
      • exclusions Module
      • markov Module
      • parsers Module
      • result Module
      • search Module