Википедия: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 получает в первом параметре указатель на хэш-массив со следующими полями:
Эта функция использует тот же кэш истории, что и 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};
}
}
}
}
[править] Ссылки
- Страница модуля на CPAN Проверено 28 августа 2006 г.
- Исходный код версии 1.08 Проверено 28 августа 2006 г.
