Apibot

Основните понятия

Много често уикитата от типа на Уикипедия изискват голямо количество повтаряща се простичка работа – например, ако една категория е прекръстена, името й да бъде променено във всички статии, включени в нея. Или всички статии в уикито да бъдат прегледани за списък типични правописни грешки, и коригирани при нужда. Или да се направи списък на всички шаблони в уикито, и статистика кой от тях колко пъти се използва… Подобни задачи са лесно изпълними и от програми, така че влагането на човешки усилия в тях е неоправдано. Затова има написани специални програми, които да улесняват такива задачи. Тези програми се наричат бот-софтуери, или често на жаргон само ботове.

Редакторът, който използва бот-софтуер за подобни задачи, обикновено бива наричан в уикитата бот-оператор. Като правило той прави за бот-софтуера си отделна сметка (име и парола); по-рядко може да използва за него своето име и парола. (Някои от бот-задачите са изпълними и без име и парола: много уикита позволяват и анонимни редакции. Други обаче изискват правата на регистрирана сметка, а понякога е удобно да й бъдат дадени и допълнителни права.) Такава сметка се нарича бот-сметка (често на жаргон – също само бот).

Apibot е бот-софтуер, който преди няколко години написах, и оттогава усъвършенствам, когато ми остане време. Остава ми рядко, но въпреки това малко по малко напредвам. Към момента вече е достатъчно стабилен, за да може да бъде предложен като бета на желаещите да използват собствен бот. Тази статия обяснява как се прави това.

Написан е изцяло на PHP – пускането му изисква да имате инсталиран PHP (който е свободен софтуер, и го има за всички по-разпространени операционни системи). Задачите за него също обикновено се пишат на PHP, тоест ще ви е трудно да пишете и пускате задачи, ако нямате известни познания по езика. (Ако имате опит в програмирането, особено на скрипт-езици и/или на C/C++, научаването на PHP до достатъчно ниво е въпрос на ден-два. Ако нямате, може да ви отнеме повече време, но също може да е добро въведение в света на програмирането.)

Лицензиран е под GNU Affero Public License, версия 3.0 или по-висока. С една дума – свободен софтуер. 🙂

Историята

Преди време вездесъщият Борислав Манолов ми беше дал Bgbot – бот за МедияУики (софтуерът, който задвижва уикитата на Уикипедия, а и повечето мои уикита), за да мога да отметна малко работа. Ботът му беше простичък и ефективен, и ми свърши чудесна работа.

С времето обаче реших, че мога да го направя и по-удобен, и се заех да го дописвам. След достатъчно дописване се получи каша, която пренаписах няколко пъти. Сегашната структура датира от около година и половина (към момента, в който пиша този запис); оттогава само е допълван по малко и чистен от бъгове.

Структурата

Състои се от няколко модула. Следва кратко описание за всеки:

utils.php

Библиотека функции, които се използват от другите модули на софтуера. Написан основно от Борислав; няколко от функциите са допълнени от мен. Някои са остарели вече – прилично съвременните версии PHP имат стандартни за целта им.

browser.php

Модул, който осигурява прехвърлянето на информация от и към уебсайт, подобно на браузер. Написан е от Борислав, на базата основно на Snoopy. Единственото добавено от мен е поддръжката за Content-Transfer: chunked; все се каня да добавя поддръжка за компресирани трансфери, и все не смогвам. (А е нужно – ботовете харчат страшно много трафик, който не е безплатен.)

logins.php

Списък с няколко уикита и един-два примера за логини за тях. Тук трябва да направите логин за бота си (може няколко, ако имате няколко бот-сметки, или уикита). Структурата му е елементарна; ако имате начални понятия от PHP, няма да е проблем да се справите с нея.

apibot_dataobjects.php

Обменяната с уикито информация се получава от бота (и му се подава) във вид на обекти, или масиви от обекти. В този файл са дефинирани основните обекти, с които ботът работи (например страница, категория, запис от Последни промени, ревизия на страница, запис в лог, запис за блокиране или разблокиране на сметка, и т.н.). Тук можете да видите полетата, които съдържат тези обекти. Имайте предвид, че някои операции с бота създават в тях и други полета, неописани тук; също, че има заявки за информация към бота, които не попълват задължително всички полета на обекта.

apibot.php

Този модул е “сърцевината” на бота. Той е, който извършва и разпределя обмена на информация с уикитата. Условно може да бъде разделен на няколко части:

– “разни и дребни”: библиотечни функции, използвани само в този модул.
– заявки на ниско ниво към API интерфейса на МедияУики: функцията api (използват се от функциите от ниско ниво за различните типове действия)
– функции от ниско ниво за различните типове действия: функциите api_action_* (използват се от средното ниво функции)
– функции от средно ниво за различните типове заявки за информация и действия (използват се от потребителското ниво функции; някои от тях, например заявките за страници, ревизии и списъци могат да бъдат използвани от потребителското ниво)
– функции от високо ниво за заявки за информация (използват се също от потребителското ниво функции)
– потребителско ниво функции: те са, които вие ще използвате в модулите си.

Начинът на използване на бота е да създадете (във ваш скрипт) обект от класа Apibot, и да работите с функциите от потребителското ниво, които той съдържа. Те могат да бъдат разделени на следните групи:

Функции за работа със страници, редактори, редакции

– функции, които работят със сметката (логване, от-логване, проверка дали е логнат…)
– функции, които редактират страници (четене на страница, запис на страница…)
– функции за местене, изтриване и възстановяване на изтрити страници
– функции за защитаване и сваляне на защитата на страници
– функции за блокиране и разблокиране на потребители
– функции за маркиране и размаркиране на страница като наблюдавана, за пращане на е-майл на друг редактор, за маркиране на последна промяна като патрулирана, за импорт на страници от друго уики, за промяна на потребителски права…

Някои от тези функции в повечето уикита изискват сметката на бота да има администраторски права.

Функции за информация за уикито и сметката

Още при логване ботът изтегля всичката информация за уикито и текущата му сметка, която може да получи. Public функциите в частта Wiki and user chanarcteristics реално дават достъп до изтеглената и кеширана информация. Много от тези функции служат за удобства при използването на тази информация – например намиране на номер на именно пространство по име, или имената му по номера, или информация за междууикитата, или списък на магическите думи, или списък на инсталираните разширения, или дали текущата сметка има едно или друго право, и т.н.

Изтеглената информация зависи от правата на сметката (не всяка информация се представя на сметки с твърде ниски права) и от версията на МедияУики отсреща (по-новите версии представят повече информация).

Други функции

Ботът включва и малко други улесняващи функции – към версия 0.20b те служат предимно за работа с имена на страници. Могат да бъдат намерени в частта General support.

Поддържат се и възможности за записване на информация в логфайл. Използват се от бота, и могат да бъдат използвани и от външните модули. Степента на подробност на записваните данни и името на логфайла могат да се задават.

apibot_iterators.php

Обикновено ботовете се използват за обработки, които се повтарят върху голям брой страници или други неща в уикито. Този модул е надстройка над apibot.php. Той реализира класове, наречени “итератори”, които повтарят едно и също действие върху голям набор обекти.

Различните итератори позволяват действието да бъде извършвано върху различни типове обекти – всички страници по азбучен ред, или страниците в определена категория, или последните промени, или приносите на определен редактор, или записите в лога на уикито, или списъка на потребителите, или включените в определена страница шаблони, или линкнатите в нея други страници, и т.н. Обикновено на итератора могат да се задават различни параметри – например да листва само страници, които започват по определен начин, и т.н.

Освен всички итерации, които предоставя API-интерфейсът на МедияУики, тук има реализирани за удобство и други итератори. Могат да бъдат итерирани списъчните информации за уикито – именните му пространства, или групите потребители, или инсталираните разширения, и т.н.

Тук има и няколко специализирани итератора, които итерират категория заедно с подкатегориите в нея, или списък страници заедно с подстраниците им, и т.н. Най-сетне, тук има няколко итератора за популярни видове “не-уики” списъци – за редовете във файл, за месеците в година или дните в месец, и т.н.

apibot_actionobjects.php

Предишният файл съдържа класовете за итератори, които обхождат указани групи “неща” в уикито. Този пък съдържа класовете за действия, които могат да бъдат прилагани върху тях.

Съществуват например клас за действие, който просто брои обходените обекти, и друг, който просто ги добавя към масив. Има класове, които изтриват обходените страници, или ги местят под нови имена, или ги защитават, и т.н. (Не ви съветвам да ги пробвате с итератор, който обхожда нещо различно от страници – не са чак толкова универсални.) Има класове, които (раз)блокират потребител, и т.н. Вероятно ще допълвам набора с времето.

Малко от класовете тук обаче са “завършени”, готови да изпълняват стандартно действие – на ботовете рядко се налага да вършат нещо съвсем стандартно. Повечето са предвидени да бъдат надградени до нещо, което върши желаната работа. Така например, класът за извършване на замени в страница сам по себе си не върши нищо. Но е много просто и лесно при надграждане само да му се укаже списък какво с какво да замени – например популярни правописни грешки с правилните изписвания – и имате работещ модул: машинарията вече е реализирана в класа за замени.

Като цяло, принципът на работа тук е, че създавате обект от нужния ви клас итератор и му задавате желаните настройки. След това създавате обект от нужния ви клас обект за действие (евентуално допълнен от вас), и го предавате на итератора, за да обходи каквото е нужно, прилагайки върху него необходимото действие. Тази технология позволява да комбинирате различни действия с различни итератори, за да получите желания ефект.

/despam

В тази поддиректория може да бъде намерен пример как нещата работят на практика. Това е модулът, който чисти някои хостнати от мен уикита от мръсотията на спамботовете. Алгоритъмът му засега се оказва доста добър – прави не повече от 1 грешка на 1000 редакции. (Щеше да е по-добре да беше направен като разширение за уикито, което при засечен спам предлага потвърждаване чрез капча, но все не смогвам.)

Файлът despam.php съдържа основния алгоритъм. В него има и родителски клас за външни източници на инфо за спамери, и реализиран негов наследник за база данни със спамери. (Honeywiki е ценна работа. 🙂 ) Ако имате свои бази данни със спамери, можете да настроите системата да използва тях; ако имате друг вид източник на списъци със спамери, можете да си направите класове за черпене на информация от тях.

В spamwords.list съм въвел няколко най-популярни в спама думи; можете да го промените по желание.

В local_wikis_clean.php се съдържа настройката на параметри за модула, и повикванията към чистенето на някои от хостнатите от мен уикита – той е файлът, който трябва да подадете на PHP.

При работа ще бъдат създадени (ако не го отмените чрез настройките) два допълнителни файла. Единият е списък на откритите и определени спамери, заедно със статистики за тях. Другият – (вероятно непълен) списък на URL-овете, определени като спамерски. И двата файла са във формат CSV. При стартиране първият (ако съществува) се прочита, и статистиките от него се използват при маркирането и блокирането на спамерите.

Архивът с бота може да бъде свален оттук (корекция от 16 ноември 2010 г. – вече има собствен сайт). Към момента, в който пиша тази статия, поставям там версия 0.20b (бета). Ако четете това доста време след написването му, е възможно там да има по-късна версия на бота, и/или други модули към него; ако съм го изоставил, може изобщо да няма нищо. (В този случай, ако държите да го получите, пробвайте да се свържете с мен – има, макар и малък, шанс още да пазя някъде нещо.)