README
1wikitools -- Package for working with MediaWiki wikis
2-----------------------------------------------------------
3
4Requirements:
5
6 * Python 2.5 or newer. (not tested on older versions)
7 * Bob Ippolito's simplejson module, if using Python < 2.6
8 <http://pypi.python.org/pypi/simplejson>
9 * To upload files or import XML, you need Chris AtLee's poster package
10 <http://pypi.python.org/pypi/poster>
11 * The wiki this is used for should be running at least MediaWiki
12 version 1.13 and have the API enabled.
13
14Installation:
15
16 * Run "python setup.py install" or copy the wikitools directory
17 to an appropriate Python module directory.
18 * An exe installer for Windows is also available (should be run as an
19 administrator to avoid errors)
20 * An RPM for Linux is also available.
21
22Available modules:
23
24 * api.py - Contains the APIRequest class, for doing queries directly,
25 see API examples below
26 * wiki.py - Contains the Wiki class, used for logging in to the site,
27 storing cookies, and storing basic site information
28 * page.py - Contains the Page class for dealing with individual pages
29 on the wiki. Can be used to get page info and text, as well as edit and
30 other actions if enabled on the wiki
31 * category.py - Category is a subclass of Page with extra functions for
32 working with categories
33 * wikifile.py - File is a subclass of Page with extra functions for
34 working with files - note that there may be some issues with shared
35 repositories, as the pages for files on shared repos technically don't
36 exist on the local wiki.
37 * user.py - Contains the User class for getting information about and
38 blocking/unblocking users
39 * pagelist.py - Contains several functions for getting a list of Page
40 objects from lists of titles, pageids, or API query results
41
42Current limitations:
43
44 * Can only do what the API can do. On a site without the edit-API enabled
45 (disabled by default prior to MediaWiki 1.14), you cannot edit/delete/
46 protect pages, only retrieve information about them.
47 * May have issues with some non-ASCII characters. Most of these bugs
48 should be resolved, though full UTF-8 support is still a little flaky
49 * Usage on restricted-access (logged-out users can't read) wikis is
50 mostly untested
51
52API examples:
53To do a simple query:
54
55from wikitools import wiki
56from wikitools import api
57# create a Wiki object
58site = wiki.Wiki("http://my.wikisite.org/w/api.php")
59# define the params for the query
60params = {'action':'query', 'titles':'Main Page'}
61# create the request object
62request = api.APIRequest(site, params)
63# query the API
64result = request.query()
65
66The result will look something like:
67{u'query':
68 {u'pages':
69 {u'15580374':
70 {u'ns': 0, u'pageid': 15580374, u'title': u'Main Page'}
71 }
72 }
73}
74
75For most normal usage, you may not have to do API queries yourself and can just
76use the various classes. For example, to add a template to the top of all the
77pages in namespace 0 in a category:
78
79from wikitools import wiki
80from wikitools import category
81site = wiki.Wiki("http://my.wikisite.org/w/api.php")
82# Create object for "Category:Foo"
83cat = category.Category(site, "Foo")
84# iterate through all the pages in ns 0
85for article in cat.getAllMembersGen(namespaces=[0]):
86 # edit each page
87 article.edit(prependtext="{{template}}\n")
88
89
90See the MediaWiki API documentation at <http://www.mediawiki.org/wiki/API>
91for more information about using the MediaWiki API. You can get an example of
92what query results will look like by doing the queries in your web browser using
93the "jsonfm" format option
94
95Licensed under the GNU General Public License, version 3. A copy of the
96license is included with this release.
97
98Author/maintainer:
99Alex Z. (User:Mr.Z-man @ en.wikipedia) <mrzmanwiki@gmail.com>
100Some code/assistance from:
101(User:Bjweeks @ en.wikipedia)
102