projects.mako.cc - wikipedia-api-cdsw/blob - REFERENCE.md.mwclient

   1 This file is intended to be a reference to mwclient.
   2 The current version is mwclient 0.6.5.
   3
   4 The mwclient framework provides access to the MediaWiki API.
   5 It provides the functions of the MediaWiki API in a Pythonic manner.
   6
   7 ## Sites ##
   8 The `Site` object is the most important class.
   9 It represents a MediaWiki site.
  10 Its constructor accepts various arguments,
  11 of which the first two, `host` and `path`, are the most important.
  12 They represent respectively
  13 the hostname without protocol
  14 and the root directory where `api.php` is located.
  15 The path parameter should end with a slash, /.
  16 Protocols other than HTTP and HTTPS are currently not supported.
  17
  18 ```python
  19 #http
  20 site = mwclient.Site(host, path = '/w/', ...)
  21
  22 #https
  23 site = mwclient.Site(('https', host), path = '/w/', ...)
  24 ```
  25
  26 ### Pages ###
  27 Sites provide access to pages via various generators and the Pages object.
  28 The base Page object is called Page
  29 and from that derive Category and Image.
  30 When the page is retrieved via `Site.Pages` or a generator,
  31 it will check automatically which of those three specific types
  32 should be returned.
  33 To get a page by its name, call `Site.Pages` as a scriptable object:
  34
  35 ```python
  36 page = site.Pages['Template:Stub']
  37 image = site.Pages['Image:Wiki.png'] # This will return an Image object
  38 image2 = site.Images['Wiki.png'] # The same image
  39 ```
  40
  41 Alternatively, `Site.Images` and `Site.Categories` are provided,
  42 which do exactly the same as `Site.Pages`,
  43 except that they require the page name without its namespace prefixed.
  44
  45 #### PageProperties ####
  46 The `Page` object provides many generators available in the API.
  47 In addition to the page properties listed in the API documentation,
  48 also the lists backlinks and embedded in are members of the Page object. For more information about using generators
  49 see the section on generators below.
  50
  51 `Category` objects provide an extra function, `members`
  52 to list all members of a category.
  53 The Category object can also be used itself
  54 as an iterator yielding all its members.
  55
  56 ```python
  57 #list pages in Category:Help by name
  58 category = site.Pages['Category:Help']
  59 for page in category:
  60         print page.name
  61 ```
  62
  63 `Image` objects have additional functions `imagehistory` and `imageusage`
  64 which represent the old versions of the image and its usage, respectively.
  65 `Image.download` returns a file object to the full size image.
  66
  67 ```python
  68 fr = image.download()
  69 fw = open('Wiki.png', 'rb')
  70 while True:
  71         s = fr.read(4096)
  72         if not s: break
  73         fw.write(s)
  74 fr.close() # Always close those file objects !!!
  75 fw.close()
  76 ```
  77
  78 #### Editing pages ####
  79 Call `Page.text()` to retrieve the page content.
  80 Use `Page.save(text, summary = u'', ...)` to save the page.
  81 If available, `Page.save` uses the API to edit,
  82 but falls back to the old way if the write API is not available.
  83
  84 ## Generators ##
  85
  86 ## Exceptions ##
  87
  88 ## Implementation notes ##
  89 Most properties and generators accept the same parameters as the API,
  90 without their two-letter prefix.
  91 Exceptions:
  92 * `Image.imageinfo` is the `imageinfo` of the *latest* image.
  93 Earlier versions can be fetched using `imagehistory()`
  94 * `Site.all*`: parameter `(ap)from` renamed to `start`
  95 * `categorymembers` is implemented as `Category.members`
  96 * `deletedrevs` is `deletedrevisions`
  97 * `usercontribs` is `usercontributions`
  98 * First parameters of `search` and `usercontributions`
  99   are `search` and `user`, respectively
 100
 101 Properties and generators are implemented as Python generators.
 102 Their limit parameter is only an indication
 103 of the number of items in one chunk.
 104 It is not the total limit.
 105 Doing `list(generator(limit = limit))` will return
 106 ALL items of generator, and not be limited by the limit value.
 107 Use `list(generator(max_items = max_items))`
 108 to limit the amount of items returned.
 109 Default chunk size is generally the maximum chunk size.
 110
 111 ## Links ##
 112 * Project page at GitHub: https://github.com/mwclient/mwclient
 113 * More in-depth documentation on the GitHub wiki:
 114 https://github.com/mwclient/mwclient/wiki
 115 * MediaWiki API documentation: https://mediawiki.org/wiki/API