jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/988018 )

Change subject: [doc] Update documentation ......................................................................

[doc] Update documentation

Change-Id: I115f1bdc94617513e1507de2f43c35007113be7f --- M ROADMAP.rst M pywikibot/xmlreader.py M pywikibot/_wbtypes.py 3 files changed, 41 insertions(+), 14 deletions(-)

Approvals: DannyS712: Looks good to me, but someone else must approve Xqt: Looks good to me, approved jenkins-bot: Verified

diff --git a/ROADMAP.rst b/ROADMAP.rst index 34a838d..b399e0f 100644 --- a/ROADMAP.rst +++ b/ROADMAP.rst @@ -4,9 +4,10 @@ Improvements ^^^^^^^^^^^^

+* :meth:`pywikibot.WbTime.equal_instant` was added (:phab:`T325248`) * ``revisions`` parameter of :class:`xmlreader.XmlDump` was introduced to specify parsing method (:phab:`T340804`) -* Pass global -nolog argument into bot script from wrapper (:phab:`T328900`) +* Pass global -nolog argument into bot script from wrapper (:phab:`T328900`) * Add :meth:`site.APISite.ratelimit()<pywikibot.site._apisite.APISite.ratelimit>` method and :class:`tools.collections.RateLimit` NamedTuple (:phab:`T304808`) * L10N Updates @@ -23,6 +24,7 @@ Breaking changes and code cleanups ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+* ``root`` attribute of :class:`xmlreader.XmlDump` was removed * ``tools.Version`` class was removed; use classes from ``packaging.version`` instead (:phab:`T340640`) * ``packaging`` package is mandatory; ``importlib_metadata`` package is required for Python 3.7 (:phab:`T340640`) * ``SelfCallMixin``, ``SelfCallDict`` and ``SelfCallString`` of :mod:`tools` module were removed @@ -30,7 +32,7 @@ is no longer supported * ``config.register_family_file()`` function was removed * require ``PyMySQL >= 1.0.0`` if necessary -* ``keys()`` and ``items()`` methods of :class:`data.api.Reques` gives a view instead a list (:phab:`T310953`) +* ``keys()`` and ``items()`` methods of :class:`data.api.Request` gives a view instead a list (:phab:`T310953`) * ``SequenceOutputter.format_list()`` was removed in favour of :attr:`tools.formatter.SequenceOutputter.out` property * *output* parameter of :class:`bot_choice.OutputProxyOption` (i.e. ``OutputOption`` instance) without *out* property is no longer supported * ``OutputOption.output()`` method was removed diff --git a/pywikibot/_wbtypes.py b/pywikibot/_wbtypes.py index 47322df5..1daf583 100644 --- a/pywikibot/_wbtypes.py +++ b/pywikibot/_wbtypes.py @@ -1,6 +1,6 @@ """Wikibase data type classes.""" # -# (C) Pywikibot team, 2013-2023 +# (C) Pywikibot team, 2013-2024 # # Distributed under the terms of the MIT license. # @@ -530,6 +530,8 @@ For example, a time with at 10:00 UTC-5 would return false if checked with == with a time at 15:00 UTC, but would return true with this method. + + .. versionadded:: 9.0 """ return self._getSecondsAdjusted() == other._getSecondsAdjusted()

diff --git a/pywikibot/xmlreader.py b/pywikibot/xmlreader.py index fa5f53b..bb8c4d1 100644 --- a/pywikibot/xmlreader.py +++ b/pywikibot/xmlreader.py @@ -11,7 +11,7 @@ vulnerable XML attacks. *defusedxml* 0.7.1 or higher is recommended. """ # -# (C) Pywikibot team, 2005-2023 +# (C) Pywikibot team, 2005-2024 # # Distributed under the terms of the MIT license. # @@ -58,7 +58,10 @@

class Headers(NamedTuple):

- """Represent the common info of a page.""" + """Represent the common info of a page. + + .. versionadded:: 9.0 + """

title: str ns: str @@ -70,7 +73,10 @@

class RawRev(NamedTuple):

- """Represent a raw revision.""" + """Represent a raw revision. + + .. versionadded:: 9.0 + """

headers: Headers revision: Element @@ -89,8 +95,9 @@ .. versionchanged:: 7.2 `allrevisions` parameter must be given as keyword parameter .. versionchanged:: 9.0 - `allrevisions` parameter deprecated due to :phab:`T340804` - `revisions` parameter introduced as replacement + `allrevisions` parameter is deprecated due to :phab:`T340804`, + `revisions` parameter was introduced as replacement. + `root` attribute was removed.

Usage example:

@@ -202,11 +209,9 @@ root.clear()

def _parse_only_first_found(self, elem: Element) -> Iterator[XmlEntry]: - """ - Deprecated parser that yields the first revision found. + """Parser that yields the first revision found.

- Documentation had wrongly indicated it returned the latest revision. - :phab: `T340804` + .. versionadded:: 9.0 """ raw_revs = self._fetch_revs(elem) try: @@ -223,7 +228,10 @@ yield self._create_revision(raw_rev.headers, raw_rev.revision)

def _parse_only_earliest(self, elem: Element) -> Iterator[XmlEntry]: - """Parser that yields only the earliest revision.""" + """Parser that yields only the earliest revision. + + .. versionadded:: 9.0 + """ raw_revs = self._fetch_revs(elem, with_id=True) raw_rev = min(raw_revs, default=None, key=lambda rev: rev.revid) if raw_rev is not None: @@ -236,7 +244,10 @@ yield self._create_revision(raw_rev.headers, raw_rev.revision)

def _fetch_revs(self, elem: Element, with_id=False) -> Iterator[RawRev]: - """Yield all revisions in a page.""" + """Yield all revisions in a page. + + .. versionadded:: 9.0 + """ uri = self.uri headers = self._headers(elem) for revision in elem.findall(f'{uri}revision'): @@ -253,6 +264,9 @@

Returns strings representing user groups allowed to edit and to move a page, where None means there are no restrictions. + + .. versionadded:: 9.0 + replaces deprecated ``parseRestrictions`` function. """ if not restrictions: return None, None