[Pywikibot-commits] [Gerrit] pywikibot/core[master]: [cleanup] Move content of README-conversion.txt to Manual:Pywikibot

jenkins-bot has submitted this change and it was merged. ( https://gerrit.wikimedia.org/r/577745 ) Change subject: [cleanup] Move content of README-conversion.txt to Manual:Pywikibot ...................................................................... [cleanup] Move content of README-conversion.txt to Manual:Pywikibot https://www.mediawiki.org/wiki/Manual:Pywikibot/compat-to-core_conversion Also convert the README-conversion file to reST Bug: T247105 Change-Id: I9b0a57c8f43d883aae9bba70c68ccf87be8f6697 --- A README-conversion.rst D README-conversion.txt 2 files changed, 18 insertions(+), 165 deletions(-) Approvals: Framawiki: Looks good to me, approved jenkins-bot: Verified diff --git a/README-conversion.rst b/README-conversion.rst new file mode 100644 index 0000000..25c04a0 --- /dev/null +++ b/README-conversion.rst @@ -0,0 +1,18 @@ +Compat to Core Conversion +========================= + +There is a guide to converting bot scripts from version 1 of the +Pywikibot framework called trunk or compat to the new version 3, +so called rewrite or core. Refer `compat-to-core conversion Manual +<https://www.mediawiki.org/wiki/Manual:Pywikibot/compat-to-core_conversion>`_ +for further instructions. + +There is also a helper script which does a lot of changes automatically. +Just call it:: + + pwb.py compat2core [<script to convert>] + +and follow the instructions and hints. + +Ask at `compat to core support request <https://phabricator.wikimedia.org/T247105>`_ +for any Pywikibot compat to core migration support. \ No newline at end of file diff --git a/README-conversion.txt b/README-conversion.txt deleted file mode 100644 index f78bb09..0000000 --- a/README-conversion.txt +++ /dev/null @@ -1,165 +0,0 @@ -This is a guide to converting bot scripts from version 1 of the -Pywikibot framework to version 3. - -Most importantly, note that the version 3 framework *only* supports wikis -using MediaWiki v.1.14 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. An effort has been made to design the interface to be as backwards- -compatible as possible, so that in most cases it should be possible to convert -scripts to the new interface simply by changing import statements and doing -global search-and-replace on module names, as discussed in this document. - -With pywikibot compat branch scripts were importing "wikipedia" or -"pagegenerators" libraries; pywikibot is now written as a standard package, -and other modules are contained within it (e.g., pywikibot.site contains Site -classes). However, most commonly-used names are imported into the pywikibot -namespace, so that module names don't need to be used unless specified in the -documentation. - -Make sure that the directory that contains the "pywikibot" subdirectory (or -folder) is in sys.path. - -The following changes, at a minimum, need to be made to allow scripts to run: - - change "import wikipedia" to "import pywikibot" - change "import pagegenerators" to "from pywikibot import pagegenerators" - change "import config" to "from pywikibot import config" - change "catlib.Category" to "pywikibot.Category" - change "catlib.change_category(page, ...)" to "page.change_category(...)" - change "query.GetData(request)" to "pywikibot.data.api.request(**request).submit()" - change "userlib.User" to "pywikibot.User" - change "wikipedia." to "pywikibot." - -wikipedia.setAction() no longer works; you must revise the script to pass an -explicit edit summary message on each put() call. - -There is a helper script which does a lot of changes automatically. -Just call it: -pwb.py compat2core [<script to convert>] -and follow the instructions and hints. - -== Deprecated methods == - -A lot of object methods have been deprecated; deprecated methods still work, -but print a warning message in debug mode. You should follow the warning -message and update your script accordingly because deprecated methods might -be removed in future releases. - -To activate the debugging level just call your script with -debug option like --debug:bot or --debug:* - -Note: The -debug option does not warn when importing deprecated modules. -A better ability is to set the debugging level in your user-config.py: -debug_log = ['*'] or -debug_log = ['bot'] or -log += ['deprecation'] - -== Python libraries == - -[Note: the goal will be to package pywikibot with setuptools easy_install, -so that these dependencies will be loaded automatically when the package is -installed, and users won't need to worry about this...] - -To run pywikibot, you will need the requests package: - -It may be installed using pip or easy_install. - -== 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 a FilePage 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 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 raise an NotImplementedError exception: - -- removeImage() -- replaceImage() - -The following methods have had their outputs changed: - -- getVersionHistory(): Returns a pywikibot.Timestamp object instead of a MediaWiki one -- templates(): Returns a list of Page objects of templates. In compat we have - a list of template title strings. -- templatesWithParams(): Returns a list of tuples with two items. The first item is - a Page object of the template, the second is a list of parameters. In compat we have - a list of tuples with two items. The first item is the template title. -- linkedPages(): Returns a PageGenerator of Page objects of link targets. - In compat we have a list of link target strings. - -=== FilePage objects === - -The old ImagePage class has been renamed into FilePage. -For FilePage objects, the getFileMd5Sum() method is deprecated; it is -recommended to replace it with latest_file_info.sha1 property 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" can be replaced by -"pywikibot.Category", but the old form is retained for backwards-compatibility. - -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 - -=== User objects === - -The User object has been moved from the userlib module to the pywikibot -namespace. Any references to "userlib.User" can be replaced by -"pywikibot.User", but the old form is retained for backwards-compatibility. - -The following changes have occurred in the User object: - -- contributions(): returns a pywikibot.Timestamp object instead of a Mediawiki one - -== apispec library and Blocks objects == - -Some apispec functionality could be replaced with other methods: - - iso() -> Timestamp.isoformat() - uniso() -> Timestamp.strftime('%Y-%m-%d %H:%M:%S') - dt() -> Timestamp.totimestampformat() - duration() -> BlockEntry.duration() - - Blocks.empty() -> (* obsolete parameter cleanup *) - Blocks.query() -> site.blocks() or site.logevents('block') - Blocks.IPsortkey() -> (* sort key, not needed * ) - Blocks.allblocks() -> site.blocks() or site.logevents('block') - Blocks.user() -> site.blocks(user=user) - Blocks.IP() -> site.blocks(iprange=IP) - -=== Command-line arguments === - -Scripts that supported unnamed arguments as titles of pages on which to work, -now require that those titles be written as standard pagegenerators, e.g.: - - python script.py -page:"A title" - -while unlink.py and other scripts that required page titles as main arguments -now need only that the titles be wrapped in quotes, as: - - python unlink.py "A title" -- To view, visit https://gerrit.wikimedia.org/r/577745 To unsubscribe, or for help writing mail filters, visit https://gerrit.wikimedia.org/r/settings Gerrit-Project: pywikibot/core Gerrit-Branch: master Gerrit-MessageType: merged Gerrit-Change-Id: I9b0a57c8f43d883aae9bba70c68ccf87be8f6697 Gerrit-Change-Number: 577745 Gerrit-PatchSet: 2 Gerrit-Owner: Xqt &lt;info(a)gno.de&gt; Gerrit-Reviewer: Dvorapa &lt;dvorapa(a)seznam.cz&gt; Gerrit-Reviewer: Framawiki &lt;framawiki(a)tools.wmflabs.org&gt; Gerrit-Reviewer: Xqt &lt;info(a)gno.de&gt; Gerrit-Reviewer: jenkins-bot (75)