jenkins-bot submitted this change.
[cleanup] Deprecate total argument in -logevents; use -limit instead
Bug: T128981
Change-Id: Idc205c90f7ecdcc68ec0b81f0347509919d82d9d
---
M pywikibot/pagegenerators/__init__.py
M pywikibot/pagegenerators/_factory.py
2 files changed, 82 insertions(+), 59 deletions(-)
diff --git a/pywikibot/pagegenerators/__init__.py b/pywikibot/pagegenerators/__init__.py
index 477c3fa..b9f02d7 100644
--- a/pywikibot/pagegenerators/__init__.py
+++ b/pywikibot/pagegenerators/__init__.py
@@ -1,5 +1,4 @@
-"""
-This module offers a wide variety of page generators.
+"""This module offers a wide variety of page generators.
A page generator is an object that is iterable (see :pep:`255`) and
that yields page objects on which other scripts can then work.
@@ -8,12 +7,12 @@
generator. For testing purposes listpages.py can be used, to print page
titles to standard output.
-These parameters are supported to specify which pages titles to print:
+These parameters are supported to specify which pages titles to be used:
¶ms;
"""
#
-# (C) Pywikibot team, 2008-2023
+# (C) Pywikibot team, 2008-2024
#
# Distributed under the terms of the MIT license.
#
@@ -214,44 +213,47 @@
logevent,username,start,end
- or for backward compatibility::
+ .. deprecated:: 9.2
+ backward compatible *total* argument like
+ ``logevent,username,total``; use ``-limit`` filter
+ option instead (see below).
- logevent,username,total
+ To use the default value, use an empty string.
.. note:: 'start' is the most recent date and log
events are iterated from present to past. If
'start' is not provided, it means 'now'; if 'end'
is not provided, it means 'since the beginning'.
- To use the default value, use an empty string.
- You have options for every type of logs given by the
- log event parameter which could be one of the following::
+ .. seealso::
+ *letype* of :api:`Logevents` for the supported
+ types of log events.
- spamblacklist, titleblacklist, gblblock, renameuser,
- globalauth, gblrights, gblrename, abusefilter,
- massmessage, thanks, usermerge, block, protect, rights,
- delete, upload, move, import, patrol, merge, suppress,
- tag, managetags, contentmodel, review, stable,
- timedmediahandler, newusers
+ **Examples:**
- It uses the default number of pages 10.
-
- Examples:
-
- -logevents:move gives pages from move log (usually
+ ``-logevents:move`` gives pages from move log (usually
redirects)
- -logevents:delete,,20 gives 20 pages from deletion log
- -logevents:protect,Usr gives pages from protect log by user
- Usr
- -logevents:patrol,Usr,20 gives 20 patrolled pages by Usr
- -logevents:upload,,20121231,20100101 gives upload pages
- in the 2010s, 2011s, and 2012s
- -logevents:review,,20121231 gives review pages since the
- beginning till the 31 Dec 2012
- -logevents:review,Usr,20121231 gives review pages by user
- Usr since the beginning till the 31 Dec 2012
- In some cases it must be given as -logevents:"move,Usr,20"
+ ``-logevents:delete -limit20`` gives 20 pages from deletion
+ log
+
+ ``-logevents:protect,Usr`` gives pages from protect log by
+ user Usr
+
+ ``-logevents:patrol,Usr -limit:20`` gives 20 patrolled
+ pages by Usr
+
+ ``-logevents:upload,,20121231,20100101`` gives upload pages
+ in the 2010s, 2011s, and 2012s
+
+ ``-logevents:review,,20121231`` gives review pages since
+ the beginning till the 31 Dec 2012
+
+ ``-logevents:review,Usr,20121231`` gives review pages by
+ user Usr since the beginning till the 31 Dec 2012
+
+ In some cases it must be given as
+ ``-logevents:"move,Usr,20"``
-interwiki Work on the given page and all equivalent pages in other
languages. This can, for example, be used to fight
@@ -282,14 +284,18 @@
'duration' minutes of timespan. rctags are supported too.
The rctag must be the very first parameter part.
- Examples:
+ **Examples:**
- -recentchanges:20 gives the 20 most recently changed pages
- -recentchanges:120,70 will give pages with 120 offset
+ ``-recentchanges:20`` gives the 20 most recently changed
+ pages
+
+ ``-recentchanges:120,70`` will give pages with 120 offset
minutes and 70 minutes of timespan
- -recentchanges:visualeditor,10 gives the 10 most recently
- changed pages marked with 'visualeditor'
- -recentchanges:"mobile edit,60,35" will retrieve pages
+
+ ``-recentchanges:visualeditor,10`` gives the 10 most
+ recently changed pages marked with 'visualeditor'
+
+ ``-recentchanges:"mobile edit,60,35"`` will retrieve pages
marked with 'mobile edit' for the given offset and timespan
-unconnectedpages Work on the most recent unconnected pages to the Wikibase
@@ -328,8 +334,10 @@
Argument can be given as "-unwatched:n" where
n is the maximum number of articles to work on.
--property:name Work on all pages with a given property name from
- Special:PagesWithProp.
+-property Work on all pages with a given property name from
+ Special:PagesWithProp. Usage:
+
+ -property:name
-usercontribs Work on all articles that were edited by a certain user.
(Example : -usercontribs:DumZiBoT)
@@ -414,17 +422,23 @@
-linter:show just shows available categories.
--querypage:name Work on pages provided by a QueryPage-based special page,
- see :api:`Querypage`.
- (tip: use -limit:n to fetch only n pages).
+-querypage Work on pages provided by a QueryPage-based special
+ page. Usage:
- -querypage shows special pages available.
+ -querypage:name
+
+ ``-querypage`` without argument shows special pages
+ available.
+
+ .. seealso:: :api:`Querypage`
-url Read a list of pages to treat from the provided URL.
The URL must return text in the same format as expected for
the -file argument, e.g. page titles separated by newlines
or enclosed in brackets.
+.. tip::
+ use ``-limit:n`` filter option to fetch only n pages.
FILTER OPTIONS
==============
diff --git a/pywikibot/pagegenerators/_factory.py b/pywikibot/pagegenerators/_factory.py
index 2616ee0..adb10cd 100644
--- a/pywikibot/pagegenerators/_factory.py
+++ b/pywikibot/pagegenerators/_factory.py
@@ -19,7 +19,10 @@
from pywikibot.backports import Callable, Iterable, Sequence, removeprefix
from pywikibot.bot import ShowingListOption
from pywikibot.data import api
-from pywikibot.exceptions import UnknownExtensionError
+from pywikibot.exceptions import (
+ ArgumentDeprecationWarning,
+ UnknownExtensionError,
+)
from pywikibot.pagegenerators._filters import (
CategoryFilterPageGenerator,
ItemClaimFilterPageGenerator,
@@ -48,7 +51,7 @@
WikibaseSearchItemPageGenerator,
WikidataSPARQLPageGenerator,
)
-from pywikibot.tools import strtobool
+from pywikibot.tools import issue_deprecation_warning, strtobool
from pywikibot.tools.collections import DequeGenerator
from pywikibot.tools.itertools import (
filter_unique,
@@ -371,43 +374,49 @@
start: str | None = None,
end: str | None = None,
) -> Iterable[pywikibot.page.BasePage] | None:
- """
- Parse the -logevent argument information.
+ """Parse the -logevent argument information.
+
+ .. deprecated:: 9.2
+ the *start* parameter as total amount of pages.
:param logtype: A valid logtype
:param user: A username associated to the log events. Ignored if
empty string or None.
:param start: Timestamp to start listing from. This must be
convertible into Timestamp matching '%Y%m%d%H%M%S'.
- For backward compatibility if the value does not have 8
- digits, this can also be a str (castable to int), used as
- the total amount of pages that should be returned.
:param end: Timestamp to end listing at. This must be
convertible into a Timestamp matching '%Y%m%d%H%M%S'.
- :return: The generator or None if invalid 'start/total' or 'end' value.
+ :return: The generator or None if invalid 'start/total' or 'end'
+ value.
"""
- def parse_start(start: str | None
- ) -> tuple[pywikibot.Timestamp | None, int | None]:
+ def parse_start(
+ start: str | None
+ ) -> tuple[pywikibot.Timestamp | None, int | None]:
"""Parse start and return (start, total)."""
- if start is None:
+ if not start:
return None, None
if len(start) >= 8:
return pywikibot.Timestamp.fromtimestampformat(start), None
+ instead = (f'-limit option like "-logevents:{logtype}'
+ f'{"," if user else ""}{user} -limit:{start}"')
+ issue_deprecation_warning('-logevents with total argument',
+ instead,
+ warning_class=ArgumentDeprecationWarning,
+ since='9.2.0')
return None, int(start)
- start = start or None # because start might be an empty string
try:
start_, total = parse_start(start)
- assert total is None or total > 0
except ValueError as err:
pywikibot.error(
f'{err}. Start parameter has wrong format!')
return None
- except AssertionError:
- pywikibot.error('Total number of log ({}) events must be a '
- 'positive int.'.format(start))
+
+ if total is not None and total < 0:
+ pywikibot.error(f'Total number of log ({start}) events must be a'
+ ' positive int.')
return None
if end is None:
To view, visit change 1028613. To unsubscribe, or for help writing mail filters, visit settings.