jenkins-bot submitted this change.
[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(-)
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 @@
¶ms;
"""
#
-# (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)
To view, visit change 845870. To unsubscribe, or for help writing mail filters, visit settings.