MediaWiki (perl)

Perl-модуль MediaWiki — интерфейс на Perl, созданный Эдуардом Черненко и предназначенный для написания ботов для Википедии. Текущая версия — 1.08. Код модуля можно получить в архиве CPAN.

Содержание

Возможности

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

Недоработки

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

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

 [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) Читает содержимое категории. Возвращает два указателя на массивы, первый со списком статей, а второй - со списком подкатегорий (без префикса пространства имён «Категория:»). Если доступно расширение Query API, то будет использоваться оптимизированная реализация.
$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) Блокирует указанного пользователя на заданный срок. Требует наличия флага sysop.
$c->unblock($user_name) Разблокирует указанного пользователя. Требует наличия флага 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() Удаляет страницу. Требует наличия флага sysop.
$pg->restore() Восстанавливает недавно удалённую страницу. Требует наличия флага 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() Отмечает последнюю версию статьи как проверенную администратором. В Википедии пока ещё нет этой возможности. Требует наличия флага 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);
 }

Более сложные примеры

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

Откатывает 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};
        }
      }
    }
 }

Ссылки

См. также

 
Начальная страница  » 
А Б В Г Д Е Ж З И Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ы Э Ю Я
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9 Home