Page.save

Waldir Pimenta edited this page May 25, 2014 · 1 revision
Clone this wiki locally

Page.save() is used to edit a page. It must follow a previous Page.edit() call. Here's a typical usage that moves a page from one category to another:

text = page.edit()
text = text.replace('[[Category:Apples]]', '[[Category:Pears]]')
page.save(text, summary='Moved from category Apples to category Pears')

Associated API: API:Edit

Parameters

  • text: The text to replace the page with. This will completely replace the previous text of the page. For existing pages, it is usually a modified version of the text returned by Page.edit().
  • (optional) summary: The edit summary. It is recommended to always include a descriptive edit summary. Limited to 200 characters or 250 UTF-8 octets, whichever is smaller. (Default: empty string)
  • (optional) minor: True to mark the edit as a minor edit. Not recommended for any edits that may be contentious, incorrect, or require review. (Default: False)
  • (optional) bot: True to mark the edit as a bot edit (only effective if logged in as a bot account). Setting this to False may be useful to make some of your bot's changes show up on Recent Changes. (Default: True)

Result

The page is updated on the site and an entry is added to the page history. The method returns a dict with the following keys:

  • 'result': One of 'Success' or 'Failure'. The remaining items appear only when result is 'Success'.
  • 'pageid': Database ID number of the page
  • 'title': Canonical title of the page that was edited
  • 'oldrevid': Revision ID of the previous revision (before the edit)
  • 'newrevid': Revision ID of the current revision (after the edit)

Errors

  • LoginError: No user was logged in, and force_login=False was not passed to Site.__init__. Performing automated edits while not logged in is not recommended.
  • UserBlocked: User is blocked and forbidden from editing the associated page.
  • ProtectedPageError: The page is protected and the user does not have the privileges needed to edit it. This error will also appear when trying to create or edit a page or image redirect, if the user does not have those privileges in general, or when trying to create a page with a blacklisted title.
  • EditError: An edit conflict occurred (an edit was made to the page by another user between the "Page.edit" and "save" calls).
  • (other errors possible, incomplete)

Examples

A typical edit that moves a page from one category to another by replacing a piece of text:

 text = page.edit()
 text = text.replace('[[Category:Apples]]', '[[Category:Pears]]')
 page.save(text, summary='Moved from category Apples to category Pears')

Omitting summary gives a blank summary (this should be avoided):

 page.save(text)

Marking the edit as a minor edit:

 page.save(text, summary='Moved from category Apples to category Pears', minor=True)

Marking the edit as not a bot edit (will not be hidden from Recent Changes as usual):

 page.save(text, summary='Moved from category Apples to category Pears', bot=False)

To blank a page, save with the empty string as text:

 page.save('', summary='Blanking the page')

Although unlikely, edit conflicts can occur on any edit, so in a robust script editing operations should always be done in a loop until they no longer conflict:

 while True:
     text = page.edit()
     text = text.replace('[[Category:Apples]]', '[[Category:Pears]]')
     try:
         page.save(text, summary='Moved from category Apples to category Pears')
     except EditError:
         continue
     break

The "save" operation should not be retried by itself, since this will discard changes by the conflicting user.

When handling long lists of pages, some may be protected. In this case you should handle ProtectedPageError and take some alternative action, such as ignoring the page, logging an error message and continuing, adding it to a list of pages to process later, or automatically editing the corresponding talk page to request an edit. Below we take the simple error message approach:

 for page in site.Categories['My category']:
     text = page.edit()
     text = text.replace('[[Category:Apples]]', '[[Category:Pears]]')
     try:
         page.save(text, summary='Moved from category Apples to category Pears')
     except [[ProtectedPageError]]:
         print 'Could not edit ' + page.page_title + ' due to protection'

This can be combined with the previous handling of edit conflicts:

 while True:
     text = page.edit()
     text = text.replace('[[Category:Apples]]', '[[Category:Pears]]')
     try:
         page.save(text, summary='Moved from category Apples to category Pears')
     except [[EditError]]:
         continue
     except [[ProtectedPageError]]:
         print 'Could not edit ' + page.page_title + ' due to protection'
     break

TODO: does it work with CAPTCHAs?


This page was originally imported from the old mwclient wiki at SourceForge. The imported version was dated from 20:47, 21 February 2012, and its only editor was Derrickcoetzee (@dcoetzee).