MediaWiki (perl)

MediaWiki — библиотека (модуль) для Perl 5, созданный Эдуардом Черненко и предназначенный для написания ботов для Википедии. Последняя версия — 1.13 (2008-01-06). Код модуля исходно распространялся через CPAN; в настоящее время может быть получен через snapshot.debian.org.

Возможности

Получение и сохранение кода страниц.
«Prepared get» — получение вики-текста из формы редактирования вместе со спец-полями, значения которых понадобятся при сохранении страницы.
Отметка малых изменений; ведение списка наблюдения.
Загрузка изображений.
Просмотр истории страниц и функция быстрого отката (пока что всегда в обход админ-интерфейса).
Получение списка страниц в категории.
Привилегированные операции:
- установка и снятие защиты страниц;
- удаление и восстановление страниц;
- блокировка/разблокировка пользователей.

Недоработки

Нет контроля предупреждений при загрузке изображений.

Пример конфигурационного файла

[bot]
user = VasyaPupkinBot
pass = 123456

[wiki]
host = ru.wikipedia.org
path = w

has_filepath = 1    ; установите в 1, если доступна страница Служебная:Filepath.
has_query = 1       ; установите в 1, если доступен интерфейс Query API.

[tmp]
msgcache = /tmp/mediawiki.msg

Интерфейс

use MediaWiki;

$c = MediaWiki->new;
$is_ok = $c->setup("config.ini");
$is_ok = $c->setup({
        'bot' => { 'user' => 'Vasya', 'pass' => '123456' },
        'wiki' => {
                'host' => 'en.wikipedia.org',
                'path' => 'w'
        }})
$is_ok = $c->switch('starwars.wikia.com');
$is_ok = $c->switch('en.wikipedia.org',
                    'w', { 'has_query' => 1, 'has_filepath' => 1 });
$whoami = $c->user();

$text = $c->text("page_name_here");
$is_ok = $c->text("page_name_here", "some new text");

$c->refresh_messages();
$msg = $c->message("MediaWiki_message_name");

die unless $c->exists("page_name");

my($articles_p, $subcats_p) = $c->readcat("category_name");

$is_ok = $c->upload("image_name", `cat myfoto.jpg`, "some notes", $force);

$is_ok = $c->block("VasyaPupkin", "2 days");
$is_ok = $c->unblock("VasyaPupkin");

$c->{summary} = "Automatic auto-replacements 1.2";
$c->{minor} = 1;
$c->{watch} = 1;

if(!$is_ok)
{
  $err = $c->{error};
  # do something
}

$pg = $c->random();
$pg = $c->get("page_name");
$pg = $c->get("page_name", "");
$pg = $c->get("page_name", "rw");

$is_ok = $pg->load();
$is_ok = $pg->save();
$text = $pg->oldid($old_version_id);
$text = $pg->content();
$title = $pg->title();

$is_ok = $pg->delete();
$is_ok = $pg->restore();
$is_ok = $pg->protect();
$is_ok = $pg->protect($edit_protection);
$is_ok = $pg->protect($edit_protection, $move_protection);

$is_ok = $pg->move("new_name");
$is_ok = $pg->watch();
$is_ok = $pg->unwatch();

$is_ok = $pg->upload(`cat myfoto.jpg`, "some notes", $force);

$is_ok = $pg->block("2 days");
$is_ok = $pg->unblock();

$pg->history(sub { my $edit_p = shift; } );
$pg->history_clear();
my $edit_p = $pg->last_edit;
my $edit_p = $pg->find_diff(qr/some_regex/);
$is_ok = $pg->markpatrolled();
$is_ok = $pg->revert();

$pg->{history_step} = 10;

$is_ok = $pg->replace(sub { my $text_p = shift; } );
$is_ok = $pg->remove("some_regex_here");
$is_ok = $pg->remove_template("template_name");

$pg->{content} = "new text";
$pg->{summary} = "do something strange";
$pg->{minor} = 0;
$pg->{watch} = 1;

Подробное описание функций и свойств

Функция/Свойство	Описание
`MediaWiki->new ()`	Создаёт и возвращает структуру клиента MediaWiki
$c->setup ([ $ini_file_name \| $config_hash_pointer ])	Читает конфигурационный файл (если не указан, то берётся файл `.bot.ini` из домашнего каталога текущего пользователя) и настраивает клиент. Если указаны имя пользователя и пароль, то вызывает `$c->login()`. Если в качестве параметра передаётся указатель на хэш-массив, то он будет использован как источник конфигурации (`{ 'bot' => { 'user' => ..., 'pass' => ...}, 'wiki' => ... }`).
$c->login ([$user [, $password]])	Выполняет «вход» в вики и сохраняет полученные cookie в файле `.lwpcookies.txt` в домашнем каталоге пользователя.
$wiki_host [, $wiki_path] [, $wiki_hash_pointer]))	Частично перенастраивает клиент (обычно используется для интервики-ботов). Первый необязательный параметр — имя сервера (например, `'ru.wikipedia.org'`), второй необязательный — путь к `index.php/query.php` (например, `'w'`). Самый последний параметр (первый встретившийся указатель на хэш-массив) воспринимается как дополнительные ключи, которые необходимо изменить в разделе конфигурации `wiki` (например, `'has_filepath'`). Все ключи, не изменяемые явно, сохранят своё значение. После перенастройки будет выполнена попытка входа под тем же именем и паролем, что и при начальной конфигурации, если таковые были заданы. Примечание: информация о всех вызовах `$c->login ()` сохраняется — при обратном переключении будут использованы cookie, полученные при первом входе.
`$c->user ()`	Возвращает имя пользователя, полученное из конфигурационного файла, или делает правку в песочнице и получает IP-адрес из истории страницы. В последнем случае результат не кэшируется (не вызывайте эту функцию несколько раз, а запоминайте результат, если он используется несколько раз).
$c->text ($page_name [, $new_text ])	Если задан параметр `$new_text`, то сохраняет страницу `$page_name` с его содержимым в качестве текста. В противном случае возвращает текущий вики-текст.
`$c->refresh_messages ()`	Скачивает все сообщения MediaWiki и сохраняет их в кэше.
`$c->message ($message_name)`	Возвращает сообщение с указанным именем из кэша. Если кэш отсутствует, то получает это сообщение отдельно.
`$c->exists ($page_name)`	Возвращает истину, если страница существует.
`$c->readcat($category_name)`	Читает содержимое категории. Возвращает два указателя на массивы, первый со списком статей, а второй — со списком подкатегорий (без префикса пространства имён «Категория:»). MediaWiki (perl)/QUERY
$c->upload($image_name, $content [, $description [, $force]])	Выгружает картинку под именем «Файл:$image_name» и содержимым $content. Если описание не указано, то будет использована пустая строка. Флаг $force заставляет игнорировать предупреждения (важно: в этой версии предупреждение приводит к отказу от загрузки).
`$c->filepath ($image_name)`	Возвращает прямой URL на изображение.
`$c->download($image_name)`	Скачивает и возвращает содержимое изображения.
`$c->block ($user_name, $block_time)`	Блокирует указанного пользователя на заданный срок. MediaWiki (perl)/SYSOP
`$c->unblock ($user_name)`	Разблокирует указанного пользователя. MediaWiki (perl)/SYSOP
`$c->random ()`	Возвращает дескриптор страницы (MediaWiki::page) случайной статьи.
$c->get ($page [, $mode])	Возвращает дескриптор страницы $page. Параметр $mode может принимать значения «», «r», «w» или «rw» (по умолчанию «r»). Если указан флаг r, то будет получен текст страницы, а если указан флаг w, то страница будет подготовлена к сохранению — загружается не сырой текст, а сразу форма редактирования, из которой получаются значения полей, которые понадобятся при сохранении страницы. Примечание: режим подготовки автоматически отключается после первого сохранения страницы.
`$c->{minor}`	Если задано в 1, то все изменения отмечаются как малые, установка значения в 0 отключает это поведение. Если значение не определено, то используется значение настроек аккаунта.
`$c->{watch}`	Если задано в 1, то изменяемые страницы будут включаться в список наблюдения, установка значения в 0 отключает это поведение. Если значение не определено, то используется значение настроек аккаунта.
`$c->{summary}`	Краткое описание для правок, производимых ботом. Также используется в качестве причины переименования страниц, блокировки пользователей и т. п. Если значение неопределено и не задано в дескрипторе страницы, то используется строка `"Bot: Edward's framework"`.
`$c->{error}`	В данном поле хранится расширенный код ошибки (см. #Обработка ошибок)
`$c->{on_error}`	В данном поле можно поместить указатель на функцию-обработчик ошибок (см. #Обработка ошибок)
`$pg->load ()`	Получает содержимое страницы. Автоматически вызывается из `$c->random` и `$c->get`, если флаг `r` не был отключён.
`$pg->save ()`	Сохраняет изменения, сделанные в этой странице.
`$pg->content ()`	Возвращает текущее содержимое страницы
`$pg->oldid ($id)`	Получает содержимое старой версии текста
`$pg->title ()`	Возвращает заголовок страницы
`$pg->delete ()`	Удаляет страницу. MediaWiki (perl)/SYSOP
`$pg->restore ()`	Восстанавливает недавно удалённую страницу. MediaWiki (perl)/SYSOP
$pg->protect([$edit_mode [, $move_mode]])	Защищает страницу от изменений. Понимаются следующие режимы защиты: 2 — изменения может производить только администратор, 1 — все, кроме анонимов и новичков, 0 — нет защиты. Первый параметр указывает защиту от правок текста, второй — от переименований. Если указан лишь один параметр, то второй устанавливается в такое же значение. Вызов без параметров аналогичен $pg->protect(1, 1). Для снятия защиты используется вызов $pg->protect(0).
`$pg->move ($new_name)`	Переименовывает страницу в $new_name.
$pg->watch ([$unwatch])	Добавляет страницу в список наблюдения. Если параметр $unwatch равен 1, то удаляет страницу из списка наблюдения.
`$pg->unwatch ()`	Синоним $pg->watch(1).
$pg->upload ($content, [, $description [, $force]])	См. $c->upload()
`$pg->block ($block_time)`	См. $c->block()
`$pg->unblock ()`	См. $c->unblock()
`$pg->history (&cb)`	Запускает функцию-callback для каждой из правок в истории статьи, которая должна возвращать неопределённое значение. Callback может прервать функцию history, вернув истинное значение (при этом history вернёт его же). Callback получает в первом параметре указатель на хэш-массив со следующими полями: page указатель на дескриптор страницы ($pg). oldid номер версии (для использования в $pg->oldid()). user имя пользователя или IP-адрес. anon равно 1, если в поле user задан IP-адрес, и 0 в противном случае. minor равно 1, если это малое изменение. comment краткое описание правки. section название секции (так называемый автокомментарий). time время правки в виде 'HH:MM'. date дата правки в виде 'D MONTH YYYY', название месяца приведено на английском языке. datetime содержит время и дату, разделённые запятой и пробелом. Эта функция использует тот же кэш истории, что и last_edit (), revert () и т. п.
`$pg->history_clear ()`	Очищает кэш истории. Автоматически вызывается при изменении страницы (к примеру, через $pg->save())
`$pg->last_edit ()`	Возвращает указатель на хэш-массив, описывающий последнюю правку в статье.
`$pg->find_diff ($regex)`	Возвращает указатель на последнюю правку, в которой было внесено изменение согласно регулярному выражению (то есть предыдущая правка ему не соответствовала, а эта соответствует), или undef в случае ненахождения таковой.
`$pg->markpatrolled ()`	Отмечает последнюю версию статьи как проверенную администратором. В Википедии пока ещё нет этой возможности. MediaWiki (perl)/SYSOP
`$pg->revert ()`	Откатывает изменения, внесённые пользователем, который последним редактировал эту страницу. Эта функция не использует администраторский инструмент быстрого отката и может использоваться кем угодно. В качестве краткого описания будет использовано MediaWiki-сообщение Revertpage. Примечание: если вы определили необходимость отката из функции history(), то опережение бота другим пользователем не приведёт к откату к неправильной версии — эта ситуация будет обработана корректно (но только если между вызовами history/last_edit и revert не очищался кэш).
`$pg->replace (&cb)`	Эта функция представляет собой наиболее общую реализацию бота автозамен. Она разбивает вики-код на части, для которых могут применяться замены и для которых не должны (внутри тегов pre, nowiki или math), а затем вызывает callback, передавая ему указатель на каждый обрабатываемый кусок текста. Впоследствии части склеиваются и сравниваются с оригиналом, и если были произведены изменения, то сохраняется новый текст. Примечание: для совместимости с существующими ботами автозамен страницы, имеющие отметку {{NO_BOT_TEXT_PROCESSING}} (можно в комментарии), не обрабатываются.
`$pg->remove ($regex)`	Упрощённый бот автозамен: удаляет из текста всё, подпадающее под регулярное выражение $regex.
`$pg->remove_template ($template_name)`	Интерфейс к $pg->remove(), убирающий из текста все вхождения шаблона $template_name.
`$pg->{content}`	Сырое содержимое страницы. В этот элемент записывается новый текст перед вызовом $pg->save().
`$pg->{minor}`	Аналог $c->{minor} только для этой страницы.
`$pg->{watch}`	Аналог $c->{watch} только для этой страницы.
`$pg->{summary}`	Аналог $c->{summary} только для этой страницы.
`$pg->{history_step}`	Указывает, сколько элементов истории загружать за раз. Значение по умолчанию — 50.

Обработка ошибок

На данный момент все функции, для которых явно не описано возвращаемое значение, возвращают 1 при успехе и undef при ошибке. Можно проверить код ошибки в $c->{error}, но пока ещё не все ошибки модуль обрабатывает должным образом (0 в $c->{error} может означать как успех, так и неизвестную ошибку).

Также можно указать callback (указатель на функцию), который будет вызываться при возникновении ошибки; он помещается в $c->{on_error}. Данная функция вызывается без параметров (код ошибки — в $c->{error}).

Известные ошибки

ERR_NO_INIHASH: Функция $c->setup() вызвана с конфигурационным файлом в качестве параметра, но отсутствует модуль Config::IniHash
ERR_PARSE_INI: Парсер конфигурационного файла вернул ошибку
ERR_NO_AUTHINFO: Вызвана функция $c->login(), но не указано, какое имя пользователя и пароль использовать
ERR_NO_MSGCACHE: Вызвана функция $c->refresh_messages(), но в конфигурации не задан путь к кэшу сообщений (или же отсутствует модуль Data::Dumper)
ERR_LOGIN_FAILED: Попытка входа не вернула HTTP-ответ 302; возможно, задан неправильный пароль
ERR_LOOP: Бесконечный цикл в модуле (либо внутренняя ошибка модуля, либо баг в вики-движке)
ERR_NOT_FOUND: Вызвана функция $c->text(), но требуемой страницы не существует

Примеры

Примеры приводятся в порядке «от простого к сложному».

Примечание: все примеры начинаются со следующих строк.

use MediaWiki;
my $c = MediaWiki->new();
$c->setup();

Создание подготовленных страниц

opendir D, "articles";
while (defined ($file = readdir (D))) {
  if (($file =~ s/\.txt$//) == 1) {
    my $text;
    open F, "$file.txt";
    read F, $text, -s F;
    close F;

    $c->text ($file, $text);
  }
}
closedir D;

Бот автозамен

for (my $i = 0; $i < 10000; $i++) {
  my $pg = $c->random ();
  $pg->replace (\&my_replacements);
}

Антивандальный бот

Откатывает «очистку страниц» ({{lang |en|blanking}) и блокирует того, кто очищает страницы более пяти раз, на срок 1 час. Если это делает единственный автор страницы, то ставит пометку {{db-author}} (но не удаляет статью — возможно, это была ошибка).

$c->{summary} = "Vandalism: blanking more than 5 times";

my %users = ();
my %articles = ();
while (1)
{
  my $pg = $c->random ();
  if ($pg->content () eq '')
  {
    my $e = $pg->last_edit;
    $blanker = $e->{user};

    $pg->revert ();
    $e = $pg->last_edit;

    if($e->{user} eq $blanker) { # Only author
      $pg->{content} .= "{{db-author}}"; # Delete note for admins
      $pg->{summary} = "+ {{db-author}}"
      $pg->save ();
    } else {
      $users{$blanker}
        = 1 + (exists $users{$blanker} ? $users{$blanker} : 0);
      if ($users{$blanker} > 5) {
        $c->block($blanker, "1 hour");
        delete $users{$blanker};
      }
    }
  }
}

Ссылки

http://snapshot.debian.org/archive/debian/20120328T101221Z/pool/main/libm/libmediawiki-perl/
Черненко Эдуард Павлович MediaWiki-1.12 search.cpan.org(недоступная ссылка — история) Архивировано из первоисточника 25 января 2008.
MediaWiki.pm Исходный код версии 1.12(недоступная ссылка — история) Архивировано из первоисточника 1 мая 2009.
http://mediawiki.ru/ — русское сообщество MediaWiki.

См. также

Википедия:Правила применения ботов в Википедии
Manual:Pywikibot в MediaWiki Wiki