jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/845870?usp=email )

Change subject: [IMPR] Improvements for Page.save, Page.put and Page.touch ......................................................................

[IMPR] Improvements for Page.save, Page.put and Page.touch

- rename botflag parameter to bot to be in sync with Site.editpage and API.Editpage - update documentation

Change-Id: I7833edeb2167edc039a0d87303d14bb47956c8fd --- M pywikibot/page/_basepage.py M pywikibot/page/_wikibase.py M scripts/touch.py M tests/deletionbot_tests.py M tests/page_tests.py 5 files changed, 80 insertions(+), 58 deletions(-)

Approvals: jenkins-bot: Verified Xqt: Looks good to me, approved

diff --git a/pywikibot/page/_basepage.py b/pywikibot/page/_basepage.py index 9890e8d..596bacc 100644 --- a/pywikibot/page/_basepage.py +++ b/pywikibot/page/_basepage.py @@ -39,6 +39,7 @@ ComparableMixin, cached, deprecated, + deprecated_args, deprecate_positionals, first_upper, issue_deprecation_warning, @@ -1267,11 +1268,12 @@ # no restricting template found return True

+ @deprecated_args(botflag='bot') # since 9.3.0 def save(self, summary: str | None = None, watch: str | None = None, minor: bool = True, - botflag: bool | None = None, + bot: bool | None = None, force: bool = False, asynchronous: bool = False, callback=None, @@ -1282,35 +1284,41 @@ Save the current contents of page's text to the wiki.

.. versionchanged:: 7.0 - boolean watch parameter is deprecated + boolean *watch* parameter is deprecated + .. versionchanged:: 9.3 + *botflag* parameter was renamed to *bot*.

- :param summary: The edit summary for the modification (optional, but - most wikis strongly encourage its use) - :param watch: Specify how the watchlist is affected by this edit, set - to one of "watch", "unwatch", "preferences", "nochange": - * watch: add the page to the watchlist - * unwatch: remove the page from the watchlist - * preferences: use the preference settings (Default) - * nochange: don't change the watchlist + .. seealso:: :meth:`APISite.editpage + <pywikibot.site._apisite.APISite.editpage>` + + :param summary: The edit summary for the modification (optional, + but most wikis strongly encourage its use) + :param watch: Specify how the watchlist is affected by this edit, + set to one of ``watch``, ``unwatch``, ``preferences``, + ``nochange``: + + * watch --- add the page to the watchlist + * unwatch --- remove the page from the watchlist + * preferences --- use the preference settings (Default) + * nochange --- don't change the watchlist If None (default), follow bot account's default settings :param minor: if True, mark this edit as minor - :param botflag: if True, mark this edit as made by a bot (default: + :param bot: if True, mark this edit as made by a bot (default: True if user has bot status, False if not) :param force: if True, ignore botMayEdit() setting :param asynchronous: if True, launch a separate thread to save asynchronously :param callback: a callable object that will be called after the - page put operation. This object must take two arguments: (1) a - Page object, and (2) an exception instance, which will be None - if the page was saved successfully. The callback is intended for - use by bots that need to keep track of which saves were - successful. + page put operation. This object must take two arguments: (1) + a Page object, and (2) an exception instance, which will be + None if the page was saved successfully. The callback is + intended for use by bots that need to keep track of which + saves were successful. :param apply_cosmetic_changes: Overwrites the cosmetic_changes configuration value to this value unless it's None. :param quiet: enable/disable successful save operation message; - defaults to False. - In asynchronous mode, if True, it is up to the calling bot to - manage the output e.g. via callback. + defaults to False. In asynchronous mode, if True, it is up + to the calling bot to manage the output e.g. via callback. """ if not summary: summary = config.default_edit_summary @@ -1326,12 +1334,12 @@ raise OtherPageSaveError( self, 'Editing restricted by {{bots}}, {{nobots}} ' "or site's equivalent of {{in use}} template") - self._save(summary=summary, watch=watch, minor=minor, botflag=botflag, + self._save(summary=summary, watch=watch, minor=minor, bot=bot, asynchronous=asynchronous, callback=callback, cc=apply_cosmetic_changes, quiet=quiet, **kwargs)

@allow_asynchronous - def _save(self, summary=None, watch=None, minor: bool = True, botflag=None, + def _save(self, summary=None, watch=None, minor: bool = True, bot=None, cc=None, quiet: bool = False, **kwargs): """Helper function for save().""" link = self.title(as_link=True) @@ -1339,7 +1347,7 @@ summary = self._cosmetic_changes_hook(summary)

done = self.site.editpage(self, summary=summary, minor=minor, - watch=watch, bot=botflag, **kwargs) + watch=watch, bot=bot, **kwargs) if not done: if not quiet: pywikibot.warning(f'Page {link} not saved') @@ -1389,11 +1397,12 @@ 'pywikibot-cosmetic-changes') return summary

+ @deprecated_args(botflag='bot') # since 9.3.0 def put(self, newtext: str, summary: str | None = None, watch: str | None = None, minor: bool = True, - botflag: bool | None = None, + bot: bool | None = None, force: bool = False, asynchronous: bool = False, callback=None, @@ -1403,11 +1412,15 @@ Save the page with the contents of the first argument as the text.

This method is maintained primarily for backwards-compatibility. - For new code, using Page.save() is preferred. See save() method - docs for all parameters not listed here. + For new code, using :meth:`save` is preferred; also ee that + method docs for all parameters not listed here.

.. versionadded:: 7.0 The `show_diff` parameter + .. versionchanged:: 9.3 + *botflag* parameter was renamed to *bot*. + + .. seealso:: :meth:`save`

:param newtext: The complete text of the revised page. :param show_diff: show changes between oldtext and newtext @@ -1416,7 +1429,7 @@ if show_diff: pywikibot.showDiff(self.text, newtext) self.text = newtext - self.save(summary=summary, watch=watch, minor=minor, botflag=botflag, + self.save(summary=summary, watch=watch, minor=minor, bot=bot, force=force, asynchronous=asynchronous, callback=callback, **kwargs)

@@ -1455,32 +1468,34 @@ self.clear_cache() return self.site.purgepages([self], **kwargs)

- def touch(self, callback=None, botflag: bool = False, **kwargs): - """ - Make a touch edit for this page. + @deprecated_args(botflag='bot') # since 9.3.0 + def touch(self, callback=None, bot: bool = False, **kwargs): + """Make a touch edit for this page.

- See save() method docs for all parameters. - The following parameters will be overridden by this method: - - summary, watch, minor, force, asynchronous + See Meth:`save` method docs for all parameters. The following + parameters will be overridden by this method: *summary*, *watch*, + *minor*, *force*, *asynchronous*

- Parameter botflag is False by default. + Parameter *bot* is False by default.

- minor and botflag parameters are set to False which prevents hiding - the edit when it becomes a real edit due to a bug. + *minor* and *bot* parameters are set to ``False`` which prevents + hiding the edit when it becomes a real edit due to a bug.

.. note:: This discards content saved to self.text. + + .. versionchanged:: 9.2 + *botflag* parameter was renamed to *bot*. """ - if self.exists(): - # ensure always get the page text and not to change it. - del self.text - summary = i18n.twtranslate(self.site, 'pywikibot-touch') - self.save(summary=summary, watch='nochange', - minor=False, botflag=botflag, force=True, - asynchronous=False, callback=callback, - apply_cosmetic_changes=False, nocreate=True, **kwargs) - else: + if not self.exists(): raise NoPageError(self)

+ # ensure always get the page text and not to change it. + del self.text + summary = i18n.twtranslate(self.site, 'pywikibot-touch') + self.save(summary=summary, watch='nochange', minor=False, bot=bot, + force=True, asynchronous=False, callback=callback, + apply_cosmetic_changes=False, nocreate=True, **kwargs) + def linkedPages( self, *args, **kwargs ) -> Generator[pywikibot.page.BasePage, None, None]: diff --git a/pywikibot/page/_wikibase.py b/pywikibot/page/_wikibase.py index 8f3bd66..ce827ab 100644 --- a/pywikibot/page/_wikibase.py +++ b/pywikibot/page/_wikibase.py @@ -48,7 +48,7 @@ from pywikibot.page._filepage import FilePage from pywikibot.page._page import BasePage from pywikibot.site import DataSite, Namespace -from pywikibot.tools import cached, first_upper +from pywikibot.tools import cached, deprecated_args, first_upper

__all__ = ( @@ -1288,22 +1288,26 @@ self._isredir = True self._redirtarget = item

+ @deprecated_args(botflag='bot') # since 9.3.0 def set_redirect_target( self, - target_page, + target_page: 'ItemPage' | str, create: bool = False, force: bool = False, keep_section: bool = False, save: bool = True, **kwargs - ): - """ - Make the item redirect to another item. + ) -> None: + """Make the item redirect to another item.

- You need to define an extra argument to make this work, like save=True + You need to define an extra argument to make this work, like + :code:`save=True`.

- :param target_page: target of the redirect, this argument is required. - :type target_page: pywikibot.page.ItemPage or string + .. versionchanged:: 9.3 + *botflag* keyword parameter was renamed to *bot*. + + :param target_page: target of the redirect, this argument is + required. :param force: if true, it sets the redirect target even the page is not redirect. """ @@ -1311,13 +1315,16 @@ target_page = pywikibot.ItemPage(self.repo, target_page) elif self.repo != target_page.repo: raise InterwikiRedirectPageError(self, target_page) + if self.exists() and not self.isRedirectPage() and not force: raise IsNotRedirectPageError(self) + if not save or keep_section or create: raise NotImplementedError + data = self.repo.set_redirect_target( from_item=self, to_item=target_page, - bot=kwargs.get('botflag', True)) + bot=kwargs.get('bot', True)) if data.get('success', 0): del self.latest_revision_id self._isredir = True diff --git a/scripts/touch.py b/scripts/touch.py index e0ca6c2..736edc9 100755 --- a/scripts/touch.py +++ b/scripts/touch.py @@ -23,7 +23,7 @@ &params; """ # -# (C) Pywikibot team, 2009-2023 +# (C) Pywikibot team, 2009-2024 # # Distributed under the terms of the MIT license. # @@ -57,7 +57,7 @@ def treat(self, page) -> None: """Touch the given page.""" try: - page.touch(botflag=self.opt.botflag) + page.touch(bot=self.opt.botflag) except (NoCreateError, NoPageError): pywikibot.error(f'Page {page.title(as_link=True)} does not exist.') except LockedPageError: diff --git a/tests/deletionbot_tests.py b/tests/deletionbot_tests.py index e548ace..eeec90e 100755 --- a/tests/deletionbot_tests.py +++ b/tests/deletionbot_tests.py @@ -44,7 +44,7 @@ p1 = pywikibot.Page(site, 'User:Unicodesnowman/ExistingPage') if not p1.exists(): p1.text = 'pywikibot unit test page' - p1.save('unit test', botflag=True) + p1.save('unit test', bot=True) delete.main('-page:User:Unicodesnowman/ExistingPage', '-always', '-undelete', '-summary:pywikibot unit tests')

@@ -76,7 +76,7 @@ def save_page(cls): """Reset the test page content.""" cls.page.text = 'Pywikibot deletion test.' - cls.page.save('Pywikibot unit test', botflag=True) + cls.page.save('Pywikibot unit test', bot=True)

@unittest.expectedFailure # T367299 def test_delete_mark(self): diff --git a/tests/page_tests.py b/tests/page_tests.py index f840f85..6b56914 100755 --- a/tests/page_tests.py +++ b/tests/page_tests.py @@ -1073,7 +1073,7 @@ p = pywikibot.Page(site, 'User:Unicodesnowman/DeleteTest') # Ensure the page exists p.text = 'pywikibot unit test page' - p.save('Pywikibot unit test', botflag=True) + p.save('Pywikibot unit test', bot=True)

# Test deletion res = p.delete(reason='Pywikibot unit test', prompt=False, mark=False)