| Name | earwigbot JSON |
| Version |
0.4
JSON |
| download |
| home_page | None |
| Summary | EarwigBot is a bot that edits Wikipedia and interacts over IRC |
| upload_time | 2024-08-29 03:49:09 |
| maintainer | None |
| docs_url | https://pythonhosted.org/earwigbot/ |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
earwig
earwigbot
irc
wikipedia
wiki
mediawiki
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
EarwigBot
=========
EarwigBot_ is a Python bot that edits Wikipedia_ and interacts over IRC_.
This README provides a basic overview of how to install and setup the bot;
more detailed information is located in the ``docs/`` directory
(`available online_`).
History
-------
Development began, based on `Pywikibot`_, in early 2009. Approval for its
first task, a `copyright violation detector`_, was carried out in May, and the
bot has been running consistently ever since. It currently handles
`several ongoing tasks`_ ranging from statistics generation to category
cleanup, and on-demand tasks such as WikiProject template tagging. Since it
started running, the bot has made over 300,000 edits.
The current version of its codebase began development in April 2011, moving
away from Pywikibot to a custom framework.
Installation
------------
This package contains the core ``earwigbot``, abstracted to be usable and
customizable by anyone running a bot on a MediaWiki site. Since it is modular,
the IRC components can be disabled if desired. IRC commands and bot tasks
specific to `my instance of EarwigBot`_ that I don't feel the average user
will need are available from the repository `earwigbot-plugins`_.
Latest release
~~~~~~~~~~~~~~
EarwigBot is available from the `Python Package Index`_, so you can install
the latest release with:
pip install earwigbot
There are a few sets of optional dependencies:
- ``crypto``: Allows encrypting bot passwords and secrets in the config
- ``sql``: Allows interfacing with MediaWiki databases (e.g. on Toolforge_)
- ``copyvios``: Includes parsing libraries for checking copyright violations
- ``dev``: Installs development dependencies (e.g. test runners)
For example, to install all non-dev dependencies:
pip install 'earwigbot[crypto,sql,copyvios]'
Errors while pip is installing dependencies may be due to missing header
files. For example, on Ubuntu, see `this StackOverflow post`_.
Development version
~~~~~~~~~~~~~~~~~~~
You can install the development version of the bot::
git clone https://github.com/earwig/earwigbot.git
cd earwigbot
python3 -m venv venv
. venv/bin/activate
pip install -e '.[crypto,sql,copyvios,dev]'
To run the bot's unit tests, run ``pytest`` (requires the ``dev``
dependencies). Coverage is currently rather incomplete.
Setup
-----
The 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 with ``earwigbot path/to/working/dir``, or just ``earwigbot`` if
the working directory is the current directory. It will notice that no
``config.yml`` file exists and take you through the setup process.
There is currently no way to edit the ``config.yml`` file from within the bot
after it has been created, but you should be able to make any necessary
changes yourself.
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.
Customizing
-----------
The bot's working directory contains a ``commands`` subdirectory and a
``tasks`` subdirectory. 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_ or in the
``docs/`` dir.
Note that custom commands will override built-in commands and tasks with the
same name.
``Bot`` and ``BotConfig``
~~~~~~~~~~~~~~~~~~~~~~~~~
`earwigbot.bot.Bot`_ is 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. A
``Bot`` object is accessible as an attribute of commands and tasks (i.e.,
``self.bot``).
`earwigbot.config.BotConfig`_ stores configuration information for the bot.
Its docstring explains what each attribute is used for, but essentially each
"node" (one of ``config.components``, ``wiki``, ``irc``, ``commands``,
``tasks``, and ``metadata``) maps to a section of the bot's ``config.yml``
file. For example, if ``config.yml`` includes something like::
irc:
frontend:
nick: MyAwesomeBot
channels:
- "##earwigbot"
- "#channel"
- "#other-channel"
then ``config.irc["frontend"]["nick"]`` will be ``"MyAwesomeBot"`` and
``config.irc["frontend"]["channels"]`` will be ``["##earwigbot", "#channel",
"#other-channel"]``.
Custom IRC commands
~~~~~~~~~~~~~~~~~~~
Custom commands are subclasses of `earwigbot.commands.Command`_ that override
``Command``'s ``process()`` (and optionally ``check()``, ``setup()``, or
``unload()``) methods.
The bot has a wide selection of built-in commands and plugins to act as sample
code and/or to give ideas. Start with test_, and then check out chanops_ and
afc_status_ for some more complicated scripts.
Custom bot tasks
~~~~~~~~~~~~~~~~
Custom tasks are subclasses of `earwigbot.tasks.Task`_ that override
``Task``'s ``run()`` (and optionally ``setup()`` or ``unload()``) methods.
See the built-in wikiproject_tagger_ task for a relatively straightforward
task, or the afc_statistics_ plugin for a more complicated one.
The Wiki Toolset
----------------
EarwigBot's answer to the Pywikibot_ is the Wiki Toolset (``earwigbot.wiki``),
which you will mainly access through ``bot.wiki``.
``bot.wiki`` provides three methods for the management of Sites:
``get_site()``, ``add_site()``, and ``remove_site()``. Sites are objects that
simply represent a MediaWiki site. A single instance of EarwigBot (i.e. a
single *working 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) with
``site = bot.wiki.get_site()``.
Not all aspects of the toolset are covered in the docs. Explore `its code and
docstrings`_ to learn how to use it in a more hands-on fashion. For reference,
``bot.wiki`` is an instance of ``earwigbot.wiki.SitesDB`` tied to the
``sites.db`` file in the bot's working directory.
.. _EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot
.. _Wikipedia: https://en.wikipedia.org/
.. _IRC: https://en.wikipedia.org/wiki/Internet_Relay_Chat
.. _available online: https://pythonhosted.org/earwigbot/
.. _Pywikibot: https://www.mediawiki.org/wiki/Manual:Pywikibot
.. _copyright violation detector: https://en.wikipedia.org/wiki/Wikipedia:Bots/Requests_for_approval/EarwigBot_1
.. _several ongoing tasks: https://en.wikipedia.org/wiki/User:EarwigBot#Tasks
.. _my instance of EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot
.. _earwigbot-plugins: https://github.com/earwig/earwigbot-plugins
.. _Python Package Index: https://pypi.python.org/pypi/earwigbot
.. _Toolforge: https://wikitech.wikimedia.org/wiki/Portal:Toolforge
.. _this StackOverflow post: https://stackoverflow.com/questions/6504810/how-to-install-lxml-on-ubuntu/6504860#6504860
.. _documentation: https://pythonhosted.org/earwigbot/
.. _earwigbot.bot.Bot: https://github.com/earwig/earwigbot/blob/main/earwigbot/bot.py
.. _earwigbot.config.BotConfig: https://github.com/earwig/earwigbot/blob/main/earwigbot/config.py
.. _earwigbot.commands.Command: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/__init__.py
.. _test: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/test.py
.. _chanops: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/chanops.py
.. _afc_status: https://github.com/earwig/earwigbot-plugins/blob/main/commands/afc_status.py
.. _earwigbot.tasks.Task: https://github.com/earwig/earwigbot/blob/main/earwigbot/tasks/__init__.py
.. _wikiproject_tagger: https://github.com/earwig/earwigbot/blob/main/earwigbot/tasks/wikiproject_tagger.py
.. _afc_statistics: https://github.com/earwig/earwigbot-plugins/blob/main/tasks/afc_statistics.py
.. _its code and docstrings: https://github.com/earwig/earwigbot/tree/main/earwigbot/wiki
Raw data
{
"_id": null,
"home_page": null,
"name": "earwigbot",
"maintainer": null,
"docs_url": "https://pythonhosted.org/earwigbot/",
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "earwig, earwigbot, irc, wikipedia, wiki, mediawiki",
"author": null,
"author_email": "Ben Kurtovic <ben@benkurtovic.com>",
"download_url": "https://files.pythonhosted.org/packages/ef/1a/5758c3b68c022d52afd2669ab5109d7c5c6e0e27622b4857bc1ad49bd38f/earwigbot-0.4.tar.gz",
"platform": null,
"description": "EarwigBot\n=========\n\nEarwigBot_ is a Python bot that edits Wikipedia_ and interacts over IRC_.\nThis README provides a basic overview of how to install and setup the bot;\nmore detailed information is located in the ``docs/`` directory\n(`available online_`).\n\nHistory\n-------\n\nDevelopment began, based on `Pywikibot`_, in early 2009. Approval for its\nfirst task, a `copyright violation detector`_, was carried out in May, and the\nbot has been running consistently ever since. It currently handles\n`several ongoing tasks`_ ranging from statistics generation to category\ncleanup, and on-demand tasks such as WikiProject template tagging. Since it\nstarted running, the bot has made over 300,000 edits.\n\nThe current version of its codebase began development in April 2011, moving\naway from Pywikibot to a custom framework.\n\nInstallation\n------------\n\nThis package contains the core ``earwigbot``, abstracted to be usable and\ncustomizable by anyone running a bot on a MediaWiki site. Since it is modular,\nthe IRC components can be disabled if desired. IRC commands and bot tasks\nspecific to `my instance of EarwigBot`_ that I don't feel the average user\nwill need are available from the repository `earwigbot-plugins`_.\n\nLatest release\n~~~~~~~~~~~~~~\n\nEarwigBot is available from the `Python Package Index`_, so you can install\nthe latest release with:\n\n pip install earwigbot\n\nThere are a few sets of optional dependencies:\n\n- ``crypto``: Allows encrypting bot passwords and secrets in the config\n- ``sql``: Allows interfacing with MediaWiki databases (e.g. on Toolforge_)\n- ``copyvios``: Includes parsing libraries for checking copyright violations\n- ``dev``: Installs development dependencies (e.g. test runners)\n\nFor example, to install all non-dev dependencies:\n\n pip install 'earwigbot[crypto,sql,copyvios]'\n\nErrors while pip is installing dependencies may be due to missing header\nfiles. For example, on Ubuntu, see `this StackOverflow post`_.\n\nDevelopment version\n~~~~~~~~~~~~~~~~~~~\n\nYou can install the development version of the bot::\n\n git clone https://github.com/earwig/earwigbot.git\n cd earwigbot\n python3 -m venv venv\n . venv/bin/activate\n pip install -e '.[crypto,sql,copyvios,dev]'\n\nTo run the bot's unit tests, run ``pytest`` (requires the ``dev``\ndependencies). Coverage is currently rather incomplete.\n\nSetup\n-----\n\nThe bot stores its data in a \"working directory\", including its config file\nand databases. This is also the location where you will place custom IRC\ncommands and bot tasks, which will be explained later. It doesn't matter where\nthis directory is, as long as the bot can write to it.\n\nStart the bot with ``earwigbot path/to/working/dir``, or just ``earwigbot`` if\nthe working directory is the current directory. It will notice that no\n``config.yml`` file exists and take you through the setup process.\n\nThere is currently no way to edit the ``config.yml`` file from within the bot\nafter it has been created, but you should be able to make any necessary\nchanges yourself.\n\nAfter setup, the bot will start. This means it will connect to the IRC servers\nit has been configured for, schedule bot tasks to run at specific times, and\nthen wait for instructions (as commands on IRC). For a list of commands, say\n\"``!help``\" (commands are messages prefixed with an exclamation mark).\n\nYou can stop the bot at any time with Control+C, same as you stop a normal\nPython program, and it will try to exit safely. You can also use the\n\"``!quit``\" command on IRC.\n\nCustomizing\n-----------\n\nThe bot's working directory contains a ``commands`` subdirectory and a\n``tasks`` subdirectory. Custom IRC commands can be placed in the former,\nwhereas custom wiki bot tasks go into the latter. Developing custom modules is\nexplained below, and in more detail through the bot's documentation_ or in the\n``docs/`` dir.\n\nNote that custom commands will override built-in commands and tasks with the\nsame name.\n\n``Bot`` and ``BotConfig``\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\n`earwigbot.bot.Bot`_ is EarwigBot's main class. You don't have to instantiate\nthis yourself, but it's good to be familiar with its attributes and methods,\nbecause it is the main way to communicate with other parts of the bot. A\n``Bot`` object is accessible as an attribute of commands and tasks (i.e.,\n``self.bot``).\n\n`earwigbot.config.BotConfig`_ stores configuration information for the bot.\nIts docstring explains what each attribute is used for, but essentially each\n\"node\" (one of ``config.components``, ``wiki``, ``irc``, ``commands``,\n``tasks``, and ``metadata``) maps to a section of the bot's ``config.yml``\nfile. For example, if ``config.yml`` includes something like::\n\n irc:\n frontend:\n nick: MyAwesomeBot\n channels:\n - \"##earwigbot\"\n - \"#channel\"\n - \"#other-channel\"\n\nthen ``config.irc[\"frontend\"][\"nick\"]`` will be ``\"MyAwesomeBot\"`` and\n``config.irc[\"frontend\"][\"channels\"]`` will be ``[\"##earwigbot\", \"#channel\",\n\"#other-channel\"]``.\n\nCustom IRC commands\n~~~~~~~~~~~~~~~~~~~\n\nCustom commands are subclasses of `earwigbot.commands.Command`_ that override\n``Command``'s ``process()`` (and optionally ``check()``, ``setup()``, or\n``unload()``) methods.\n\nThe bot has a wide selection of built-in commands and plugins to act as sample\ncode and/or to give ideas. Start with test_, and then check out chanops_ and\nafc_status_ for some more complicated scripts.\n\nCustom bot tasks\n~~~~~~~~~~~~~~~~\n\nCustom tasks are subclasses of `earwigbot.tasks.Task`_ that override\n``Task``'s ``run()`` (and optionally ``setup()`` or ``unload()``) methods.\n\nSee the built-in wikiproject_tagger_ task for a relatively straightforward\ntask, or the afc_statistics_ plugin for a more complicated one.\n\nThe Wiki Toolset\n----------------\n\nEarwigBot's answer to the Pywikibot_ is the Wiki Toolset (``earwigbot.wiki``),\nwhich you will mainly access through ``bot.wiki``.\n\n``bot.wiki`` provides three methods for the management of Sites:\n``get_site()``, ``add_site()``, and ``remove_site()``. Sites are objects that\nsimply represent a MediaWiki site. A single instance of EarwigBot (i.e. a\nsingle *working directory*) is expected to relate to a single site or group of\nsites using the same login info (like all WMF wikis with CentralAuth).\n\nLoad your default site (the one that you picked during setup) with\n``site = bot.wiki.get_site()``.\n\nNot all aspects of the toolset are covered in the docs. Explore `its code and\ndocstrings`_ to learn how to use it in a more hands-on fashion. For reference,\n``bot.wiki`` is an instance of ``earwigbot.wiki.SitesDB`` tied to the\n``sites.db`` file in the bot's working directory.\n\n.. _EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot\n.. _Wikipedia: https://en.wikipedia.org/\n.. _IRC: https://en.wikipedia.org/wiki/Internet_Relay_Chat\n.. _available online: https://pythonhosted.org/earwigbot/\n.. _Pywikibot: https://www.mediawiki.org/wiki/Manual:Pywikibot\n.. _copyright violation detector: https://en.wikipedia.org/wiki/Wikipedia:Bots/Requests_for_approval/EarwigBot_1\n.. _several ongoing tasks: https://en.wikipedia.org/wiki/User:EarwigBot#Tasks\n.. _my instance of EarwigBot: https://en.wikipedia.org/wiki/User:EarwigBot\n.. _earwigbot-plugins: https://github.com/earwig/earwigbot-plugins\n.. _Python Package Index: https://pypi.python.org/pypi/earwigbot\n.. _Toolforge: https://wikitech.wikimedia.org/wiki/Portal:Toolforge\n.. _this StackOverflow post: https://stackoverflow.com/questions/6504810/how-to-install-lxml-on-ubuntu/6504860#6504860\n.. _documentation: https://pythonhosted.org/earwigbot/\n.. _earwigbot.bot.Bot: https://github.com/earwig/earwigbot/blob/main/earwigbot/bot.py\n.. _earwigbot.config.BotConfig: https://github.com/earwig/earwigbot/blob/main/earwigbot/config.py\n.. _earwigbot.commands.Command: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/__init__.py\n.. _test: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/test.py\n.. _chanops: https://github.com/earwig/earwigbot/blob/main/earwigbot/commands/chanops.py\n.. _afc_status: https://github.com/earwig/earwigbot-plugins/blob/main/commands/afc_status.py\n.. _earwigbot.tasks.Task: https://github.com/earwig/earwigbot/blob/main/earwigbot/tasks/__init__.py\n.. _wikiproject_tagger: https://github.com/earwig/earwigbot/blob/main/earwigbot/tasks/wikiproject_tagger.py\n.. _afc_statistics: https://github.com/earwig/earwigbot-plugins/blob/main/tasks/afc_statistics.py\n.. _its code and docstrings: https://github.com/earwig/earwigbot/tree/main/earwigbot/wiki\n",
"bugtrack_url": null,
"license": null,
"summary": "EarwigBot is a bot that edits Wikipedia and interacts over IRC",
"version": "0.4",
"project_urls": {
"Changelog": "https://github.com/earwig/earwigbot/blob/main/CHANGELOG",
"Documentation": "https://pythonhosted.org/earwigbot/",
"Homepage": "https://github.com/earwig/earwigbot",
"Issues": "https://github.com/earwig/earwigbot/issues"
},
"split_keywords": [
"earwig",
" earwigbot",
" irc",
" wikipedia",
" wiki",
" mediawiki"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f09a76fe9aaa16e97eca0958c6a1db4644d142f3ab84adb50ffa2877496b9a4",
"md5": "f501ebba241190c8f6dd5d1888c8e6df",
"sha256": "cca2a851a16dc0df966ad4da3a68d4fc4fdae07630bb87ab6bfb13c9a8748d5d"
},
"downloads": -1,
"filename": "earwigbot-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f501ebba241190c8f6dd5d1888c8e6df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 174260,
"upload_time": "2024-08-29T03:49:07",
"upload_time_iso_8601": "2024-08-29T03:49:07.951615Z",
"url": "https://files.pythonhosted.org/packages/3f/09/a76fe9aaa16e97eca0958c6a1db4644d142f3ab84adb50ffa2877496b9a4/earwigbot-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ef1a5758c3b68c022d52afd2669ab5109d7c5c6e0e27622b4857bc1ad49bd38f",
"md5": "5c8d4704d074ec6289d17f659e9144d6",
"sha256": "a7fff9066ef80a7199063e2bd3693c3ae688dc3f48e13eac0fe4c8d183ace456"
},
"downloads": -1,
"filename": "earwigbot-0.4.tar.gz",
"has_sig": false,
"md5_digest": "5c8d4704d074ec6289d17f659e9144d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 122834,
"upload_time": "2024-08-29T03:49:09",
"upload_time_iso_8601": "2024-08-29T03:49:09.178129Z",
"url": "https://files.pythonhosted.org/packages/ef/1a/5758c3b68c022d52afd2669ab5109d7c5c6e0e27622b4857bc1ad49bd38f/earwigbot-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 03:49:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "earwig",
"github_project": "earwigbot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "earwigbot"
}
