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};
      }
    }
  }
}

Ссылки[править]

См. также[править]

Источник — https://ru.wikibooks.org/w/index.php?title=MediaWiki_(perl)&oldid=227325