Tutorial de bots/Llibreries a pywikipediabot

Pywikipedia conté diversos mòduls amb llibreries que es poden carregar als programes escrits en python per tal de facilitar la manipulació dels continguts de Viquièdia i d'altres wikis.

Per tal de poder-les fer servir primer cal importar-les amb la instrucció:

import nom_de_la_llibreria

Vegeu el capítol sobre ús de mòduls en Python per a més detalls.

Els principals mòduls són:

wikipedia.py       Per tractar les pàgines de wikipèdia.
catlib.py          Per tractar categories.  
userlib.py         Per usuaris.
pagegenerators.py  Per obtenir llistes de pàgines de diferents tipus.

wikipedia.py

En aquest mòdul es troben les classes page (pàgina) i site (lloc mediawik)

per manipular una pàgina primer cal crear un objecte de tipus pàgina amb la instrucció

pagina = wikipedia.Page(lloc, títol_de_la_pàgina)

El que fa aquesta instrucció és crear l'objecte de tipus pàgina i emmagatzemar-lo a la variable pagina, el paràmetre lloc ha de ser un objecte de tipus lloc mediawiki que es pot haver creat abans amb una instrucció site emmagatzemant-la en una variable o es pot crear en la mateixa instrucció. Per exemple aquests dos codis creen el mateix objecte:

lloc = wikipedia.getSite("ca","wikipedia")
objecte_pagina_que_te_el_titol_peu = wikipedia.Page(lloc, "peu")

Fa el mateix que:

objecte_pagina_que_te_el_titol_peu = wikipedia.Page(wikipedia.getSite("ca","wikipedia"), "peu")

En el dos casos es crea un objecte que permet manipular la pàgina de la Viquipèdia que té per títol "peu".

Fixeu-vos que la sintaxis de la instrucció per crear el lloc mediawiki requereix passar-li dos paràmetres: el codi de la llengua i el nom del projecte.

Un cop es té un objecte corresponent a una pàgina se li poden aplicar els mètodes que proporciona el mòdul pywikipedia.

Mètodes get() i put()

Els mètodes més habituals són get() i put()

Observeu el següent programa:

import wikipedia.py
objecte_pagina_de_la_pagina_de_proves = wikipedia.Page(wikipedia.getSite("ca","wikipedia"), u"Viquipèdia:Pàgina de proves")
text_actual_de_la_pagina_de_proves = objecte_pagina_de_la_pagina_de_proves.get()
text_nou_de_la_pagina_de_proves = u"prova d'edició amb bot" + text_actual_de_la_pagina_de_proves
objecte_pagina_de_la_pagina_de_proves.put(text_nou_de_la_pagina_de_proves,u"Proves de programació d'un bot")

Primer es crea un objecte que correspon a la pàgina de proves de la Viquipèdia en català. Llavors es llegeix aquesta pàgina i el seu contingut s'emmagatzema en la variable text_actual_de_la_pagina_de_proves. El contingut d'una pàgina és una cadena i per tant es pot manipular com qualsevol cadena. Per això la següent instrucció crea una nova cadena empalmant "prova d'edició amb bot" al començament del contingut de la pàgina de proves. Per acabar el mètode put de l'objecte pàgina de proves permet gravar aquest nou contingut. Si observeu ara la pàgina de proves vuereu que s'ha fet una modificació afegint la cadena "prova d'edició amb bot" al començament de tot i que el comentari d'edició és: "Proves de programació d'un bot".

Altres mètodes de la classe pàgina

A demés dels mètodes get() i put() la classe pàgina ofereix altres mètodes útils:

• Per reanomenar la pàgina

move(nou_titol,motiu) : Li canvia el nom. És com el reanomena manual

• Per obtenir informacions de la pàgina

title                 : El nom de la pàgina. És útil perquè no sempre s'obté l'objecte pàgina creant-lo a partir del títol. El resultat és una cadena.
interwiki             : Retorna una llista d'objectes de tipus pàgina amb tots els interwikis que hi ha a la pàgina.
categories            : Retorna una llista d'objectes de tipus pàgina amb totes les categories de la pàgina.
linkedPages           : Retorna una llista d'objectes de tipus pàgina amb tots els enllaços interns que hi ha a la pàgina.
imagelinks            : Retorna una llista d'objectes de tipus pàgina amb totes les imatges.
templates             : Retorna una llista d'objectes de tipus pàgina amb les plantilles
templatesWithParams   : Retorna una llista de llistes per cada plantilla una  llista de tots els paràmetres, el paràmetre 0 és el nom de la plantilla, són tots cadenes. Si un paràmetre té nom = valor això és el que retorna , si només té valor llavors el que retorna és el valor.
getReferences         : Retorna una llista d'objectes de tipus pàgina amb les pàgines que apunten a la pàgina en qüestió. També funciona amb pàgines que no existeixen si hi ha pàgines que hi apunten.
userName              : Cadena amb el nom de l'últim usuari que ha editat la pàgina

• Per saber quin tipus de pàgina és. Retornen una variable booleana veritat o fals.

exists               : Retorna veritat si la pàgina existeix
isEmpty              : Retorna veritat si la pàgina té 4 caràcters o menys, no conta les interwikis i les categories   
isCategory           : Retorna veritat si la pàgina és una categoria altrament retorna fals.
isDisambig           : Retorna veritat si la pàgina és una pàgina de desambiguació.
isImage              : Retorna veritat si és una imatge
isRedirectPag        : Retorna veritat si és una desambiguació
isTalkPage           : Retorna veritat si és una pàgina de discussió

• Per llegir versions antigues de la pàgina

latestRevision        : Retorna l'identificador de la última revisió de la pàgina
previousRevision      : Retorna l'identificador de la verssió prèvia de la pàgina
getOldVersion(id)     : Llegeix el text de la vessió de la pàgina corresponent al identificador "id" com el get() però amb una vesió antiga.
getVersionHistory     : Retorna una llista de tuples. Cada tupla correspon a una edició i conté: identificador, data/hora, usuari i resum d'edició.  L'odre per omissió és començant per l'edició més recent.

Altres mètodes de la classe site

search(cadena)           : La llista de pàgines que resulten de cercar la "cadena"
allpages()               : Una llista amb totes les pàgines
newpages()               : Llista amb les últimes pàgines creades
newimages()              : Llista amb les últimes imatges carregades
deadendpages()           : Llista de pàgines cul de sac
lonelypages()            : Llista de pàgines orfes
recentchanges()          : Llista dels últims canvis
unwatchedpages()         : Llista de pàgines no vigilades
uncategorizedcategories(): Llista de categories sense categoria
uncategorizedpages()     : Llista de pàgines sense categoria
uncategorizedimages()    : Llista d'imatges sense categoria
unusedcategories()       : Llista de categories buides
unusedfiles()            : Llista d'imatges no utilitzades
randompage               : Pàgina aleatòria
randomredirectpage       : Pàgina de redirecció aleatòria
withoutinterwiki         : Llista de pàgines sense interwikis

Altres funcions del mòdul wikipedia.py

El mòdul pywikipedia conté també altres funciona que són pràctiques a l'hora de manipular textos procedents de pàgines de Viquipèdia. Les pàgines de Viquipèdia fan servir caràcters unicode per tal de poder codificar les lletres de tots els alfabets del món, però moltes instruccions de Python donen problemes en manipular aquest tipus de cadenes per exemple la instrucció print avorta en trobar-se un caràcter que no és ASCII.

Com que les funcions estan dins del mòdul wikipedia cal cridar-les escrivint wikipedia.nom_de_la_funcio</codi>.

Funcions de interacció amb l'operador del bot:

output(text): Fa el mateix que la instrucció print de Python però sense problemes amb els caràcters unicode.
inputChoice(pregunta, respostes, tecles_de_resposta, omisio) : Presenta una llista d'alternatives i i retorna la que trii l'usuari.  
              Preginta ha de ser una cadena que es presentarà a la pantalla, respostes és una llista de cadenes, una per cada resposta possible, 
              tecles_de_resposta és una llista de cadenes d'una sola lletra que corresponen cada una a una a la tecla que cal prémer per donar la 
              resposta corresponent i omissió és la resposta que es dóna per omissió.
showDiff(text_antic, text_nou): Presenta les diferències entre els dos textos. Molt útil per bots semiautomàtics per presentar el que han fet abans 
              de decidir si es grava o no a la Viquipèdia.

Funcions per evitar manipular caràcters unicode. De vegades per poder emprar altres intruccions o funcions convé treballar amb cadenes sense caràcters unicode. Una manera de fer-ho és codificant-los en HTML llavors manipular la cadena i abans de tornar a graver text a la Viquipèdia tornar a transformar la codificació HTML a unicode, les següents funcions permeten fer-ho:

UnicodeToAsciiHtml: Transforma una cadena unicode en una cadena HTML.
html2unicode      : Transforma una cadena HTML en una cadena unicode.

Un cop acabat el programa el mòdul wikipedia subministra una funció per aturar el bot i evitar que continuí ocupant recursos.

stopme(): Desconnecta el bot de la wiki

Escriviu el següent programa (modificat del d'abans) i proveu-lo:

import wikipedia.py
pagina_de_proves = wikipedia.Page(wikipedia.getSite("ca","wikipedia"), u"Viquipèdia:Pàgina de proves")
text_actual = pagina_de_proves.get()
text_nou = u"prova d'edició amb bot\n" + text_actual
wikipedia.showDiff(text_actual, text_nou)
decisio = wikipedia.inputChoice(u"voleu gravar la pàgina modificada?", ["si","no"], ["s","n"], "n")
if decisio == "S" :
     pagina_de_proves.put(text_nou,u"Proves de programació d'un bot")
     wikipedia.output(u"s'ha gravat la pàgina de proves modificada")
wikipedia.stopme()

catlib.py

El mòdul catlib permet treballar amb categories. Primer cal obtenir un objecte de tipus categoria. Això es fa amb la instrucció: categoria = catlib.Category(llocwiki, nom_de_la_categoria). Llavors es poden emprar els mètodes que subministra el mòdul:

articles(recursiu, començant_per): Torna una llista d'objectes pàgina amb totes les pàgines de la categoria. Els arguments són opcionals. Si es posa
                                   _TRUE_  a l'argument "recursiu", llavors també torna les pàgines de les subcategories. "començant_per" és per 
                                   indicar per on es vol començar si no es diu res comença  pel començament.

subcategories(recursiu, començant_per) : Torna totes les subcategories d'una categoria. Els arguments són opcionals. Si es posa _TRUE_  a l'argument 
                                         "recursiu", llavors també torna les subcategories de les subcategories. "començant_per" és per indicar 
                                         per on es vol començar si no es diu res comença  pel començament.

supercategories()                      : Torna la llista de categories a les quals pertany la categoria.

userlib.py

Aquest mòdul proporciona mètodes per tractar amb usuaris. Primer cal crear un objecte de tipus usuari amb la funció User. El següent programa il·lustra els principals mètodes que hi ha al mòdul:

import wikipedia, userlib
pagina_meva = userlib.User('ca', u"Poseu_aqui_el_vostre_nom_d'usuari")
x = pagina_meva.getUserPage()
wikipedia.output(x.get())
x = pagina_meva.contributions(5)
for contribucio in x :
	pagina = contribucio[0]
	id = contribucio[1]
	data_i_hora = contribucio[2]
	comentari = contribucio[3]
	print "pagina: ", pagina, "id: ", id, "data i hora: ", data_i_hora, "comentari: ",comentari
x = pagina_meva.editedPages(5)
for pagina in x :
	print "pagina: ", pagina
pagina_meva.sendMail("Resultat del programa", u"S'ha acabat d'executar el programa de prova del curs de programació de bots\n\nSalutacions.")

La primera instrucció carrega els mòduls "wikipedia" i "userlib". Llavors es crea un objecte usuari corresponent al vostre (recordeu de posar el vostre nom d'usuari).

Després es fa servir el mètode getUserPage per obtenir un objecte pàgina que correspon a la vostra pàgina d'usuari, la següent instrucció llegeix la vostra pàgina d'usuari (amb el mètode get del mòdul wikipedia) i presenta en pantalla el contingut.

Tot seguit s'obtenen les 5 últimes contribucions que heu fet amb el mètode contributions. Les contribucions són una llista de llistes, cada element de la llista conté una llista amb quatre elements: la pàgina, l'identificador de l'edició (vegeu accés a edicions antigues del mòdul wikipedia), la data i hora i el comentari. Fixeu-vos que el que fa el bucla for és presentar-vos en pantalla el detall d'aquestes 5 contribucions.

Les següents instruccions fan el mateix però sense el detall de cada contribució, només obtenen les pàgines. Per axó es fa servir el mètode editedPages.

Finalment us envia un correu-e indicant-vos el rsultat d'acabar l'execució del programa emprant el mètode sendMail. Aquest mètode té 3 paràmetres (a l'exemple només fa servir els dos primers): 1)Concepte del correu-e (una cadena) 2)Contingut del correu-e (una cadena) 3)Si voleu que us faci copia a vosaltres del correu-e que ha enviat (un booleà _TRUE_ o _FALSE_).

pagegenerators.py

Aquest mòdul conté una sèrie de funcions que permeten crear objectes de tipus generador de pàgines. Un objecte generador de pàgines és un objecte iterable que dóna objectes de tipus pàgina.

Exemple:

import pagegenerators
x = pagegenerators.AllpagesPageGenerator("Joan", 3)
contador = 0
for usuari in x :
	print usuari
	contador += 1
	if contador > 5 : break

La primera instrucció carrega el mòdul pagegenerators.

La segona instrucció crea un objecte de tipus generador de pàgines i l'emmagatzema a la variable "x". Aquest objecte genera totes les pàgines de l'espai de noms 3 (l'espai de pàgines de discussió d'usuari) començant per la pàgina "joan". Si no es posa el paràmetre espai de noms els agafa tots i si no es posa pàgina de començament comença per la primera.

Llavors s'itera aquest objecte amb la instrucció for i s'escriuen per pantalla les 5 primeres pàgines generades.

Altres funcions per crear generadors de pàgines que hi ha disponibles en aquest mòdul són:

Elements creats recentment a la viquipèdia:

NewpagesPageGenerator(nombre)         Pàgines noves. Si no es diu el nombre en dóna 100.
NewimagesPageGenerator(nombre)        Imatges noves. Si no es diu el nombre en dóna 100.
RecentchangesPageGenerator(nombre)    Pàgines modificades recentment. Si no es diu el nombre en dóna 100. 

Pàgines amb "problemes":

UnusedFilesGenerator(nombre)          Imatges no utilitzades enlloc.  Si no es diu el nombre en dóna 100. 
WithoutInterwikiPageGenerator(nombre) Pàgines sense interwikis. Id.
UnCategorizedPageGenerator(nombre)    Pàgines sense categoria. Id.
LonelyPagesPageGenerator(nombre)      Pàgines a les que no enllaça ningú. Id.
UnwatchedPagesPageGenerator(nombre)   Pàgines que no vigila ningú. Id.
DeadendPagesPageGenerator(nombre)     Pàgines sense cap enllaç intern. (culs de sac). Id.

Pàgines al atzar:

RandomPageGenerator(nombre)           Pàgines aleatòries. Si no es diu el nombre en dóna 10.

Resultat d'una cerca:

SearchPageGenerator(text, nombre)     Pàgines que resulten d'una cerca a viquipèdia. Text és una cadena amb el text de cerca. Si no es diu el nombre