Revision: 5108
Author: russblau
Date: 2008-03-07 18:33:09 +0000 (Fri, 07 Mar 2008)
Log Message:
-----------
Start how-to on converting to new version.
Added Paths:
-----------
branches/rewrite/pywikibot/README-conversion.txt
Added: branches/rewrite/pywikibot/README-conversion.txt
===================================================================
--- branches/rewrite/pywikibot/README-conversion.txt (rev 0)
+++ branches/rewrite/pywikibot/README-conversion.txt 2008-03-07 18:33:09 UTC (rev 5108)
@@ -0,0 +1,67 @@
+This is a guide to converting bot scripts from version 1 of the
+Pywikipediabot framework to version 2.
+
+Most importantly, note that the version 2 framework *only* supports wikis
+using MediaWiki v.1.12 or higher software. If you need to access a wiki that
+uses older software, you should continue using version 1 for this purpose.
+
+The "root" namespace used in the project has changed from "wikipedia"
+to "pywikibot". References to wikipedia need to be changed globally to
+pywikibot. Unless noted in this document, other names have not changed; for
+example, wikipedia.Page can be replaced by pywikibot.Page throughout any
+bot.
+
+== Page objects ==
+
+The constructor syntax for Pages has been modified; existing calls in the
+format of Page(site, title) will still work, and this is still the preferred
+way of creating a Page object from data retrieved from the MediaWiki API
+(because the API will have parsed and normalized the title). However, for
+titles input by a user or scraped from wikitext, it is preferred to use the
+alternative syntax Page(Link(site, wikitext)), where "wikitext" is the
+string found between [[ and ]] delimiters. The new Link object (more on
+this below) handles link parsing and interpretation that doesn't require
+access to the wiki server.
+
+A third syntax allows easy conversion from a Page object to an ImagePage or
+Category, or vice versa: e.g., Category(pageobj) converts a Page to a
+Category, as long as the page is in the category namespace.
+
+The following methods of the Page object have been deprecated (deprecated
+methods will still work, but print a warning message in debug mode):
+
+- urlname(): replaced by Page.title(asUrl=True)
+- titleWithoutNamespace(): replaced by Page.title(withNamespace=False)
+- sectionFreeTitle(): replaced by Page.title(withSection=False)
+- aslink(): replaced by Page.title(asLink=True)
+- encoding(): replaced by Page.site().encoding()
+
+The following methods of the Page object have been obsoleted and no longer
+work (but these methods don't appear to be used anywhere in the code
+distributed with the bot framework). The functionality of the two obsolete
+methods is easily replaced by using standard search-and-replace techniques.
+If you call them, they will print a warning and do nothing else:
+
+- removeImage()
+- replaceImage()
+
+=== ImagePage objects ===
+
+For ImagePage objects, the getFileMd5Sum() method is deprecated; it is
+recommended to replace it with getFileSHA1Sum(), because MediaWiki now
+stores the SHA1 hash of images.
+
+=== Category objects ===
+
+The Category object has been moved from the catlib module to the pywikibot
+namespace. Any references to "catlib.Category" need to be replaced by
+"pywikibot.Category".
+
+For Category objects, the following methods are deprecated:
+
+- subcategoriesList: use, for example, list(self.subcategories()) instead
+- articlesList: use, for example, list(self.articles()) instead
+- supercategories: use self.categories() instead
+- supercategoriesList: use, for example, list(self.categories()) instead
+
+# MORE TO COME #