jenkins-bot submitted this change.
[doc] Additional version hints to doc strings
Change-Id: I236af66aa35dd8587fc3c88bb8f90d611daf9e9a
---
M pywikibot/__init__.py
M pywikibot/__metadata__.py
M pywikibot/backports.py
M pywikibot/bot.py
M pywikibot/bot_choice.py
M pywikibot/comms/eventstreams.py
M pywikibot/families/foundation_family.py
M pywikibot/families/wikihow_family.py
M pywikibot/families/wikimania_family.py
M pywikibot/families/wikispore_family.py
M pywikibot/family.py
M pywikibot/page/__init__.py
M pywikibot/plural.py
M pywikibot/site/_apisite.py
M pywikibot/site_detect.py
M pywikibot/textlib.py
M pywikibot/tools/__init__.py
M pywikibot/version.py
18 files changed, 138 insertions(+), 32 deletions(-)
diff --git a/pywikibot/__init__.py b/pywikibot/__init__.py
index 57d147c..4e1204e 100644
--- a/pywikibot/__init__.py
+++ b/pywikibot/__init__.py
@@ -1022,6 +1022,8 @@
is introduced.
This data type is just a json container
+
+ *New in version 3.0.*
"""
_items = ('json',)
diff --git a/pywikibot/__metadata__.py b/pywikibot/__metadata__.py
index 2c135db..f136648 100644
--- a/pywikibot/__metadata__.py
+++ b/pywikibot/__metadata__.py
@@ -1,4 +1,7 @@
-"""Pywikibot metadata file."""
+"""Pywikibot metadata file.
+
+*New in version 4.0.*
+"""
#
# (C) Pywikibot team, 2020-2021
#
diff --git a/pywikibot/backports.py b/pywikibot/backports.py
index 219a231..69e4057 100644
--- a/pywikibot/backports.py
+++ b/pywikibot/backports.py
@@ -1,6 +1,6 @@
"""This module contains backports to support older Python versions."""
#
-# (C) Pywikibot team, 2020-2021
+# (C) Pywikibot team, 2014-2021
#
# Distributed under the terms of the MIT license.
#
@@ -68,13 +68,19 @@
removesuffix = str.removesuffix
else:
def removeprefix(string: str, prefix: str) -> str:
- """Remove prefix from a string or return a copy otherwise."""
+ """Remove prefix from a string or return a copy otherwise.
+
+ *New in version 5.4.*
+ """
if string.startswith(prefix):
return string[len(prefix):]
return string[:]
def removesuffix(string: str, suffix: str) -> str:
- """Remove prefix from a string or return a copy otherwise."""
+ """Remove prefix from a string or return a copy otherwise.
+
+ *New in version 5.4.*
+ """
if string.endswith(suffix):
return string[:-len(suffix)]
return string[:]
diff --git a/pywikibot/bot.py b/pywikibot/bot.py
index 3d6a7e2..08fbdc3 100644
--- a/pywikibot/bot.py
+++ b/pywikibot/bot.py
@@ -887,7 +887,10 @@
def show_help(module_name=None, show_global=False):
- """Show help for the Bot."""
+ """Show help for the Bot.
+
+ *Renamed in version 4.0.*
+ """
if not module_name:
module_name = calledModuleName()
if not module_name:
@@ -1008,7 +1011,10 @@
class _OptionDict(dict):
- """The option dict which holds the options of OptionHandler."""
+ """The option dict which holds the options of OptionHandler.
+
+ *New in version 4.1.*
+ """
def __init__(self, classname, options):
self._classname = classname
@@ -1378,7 +1384,7 @@
@deprecated('generator.close()', since='20200804')
def stop(self): # pragma: no cover
- """Stop iterating."""
+ """DEPRECATED. Stop iterating."""
pywikibot.output('Generator has been stopped.')
self.generator.close()
@@ -1454,6 +1460,8 @@
def skip_page(self, page):
"""Return whether treat should be skipped for the page.
+ *New in version 3.0.*
+
@param page: Page object to be processed
@type page: pywikibot.Page
"""
@@ -1474,10 +1482,15 @@
This can be used for reading huge parts from life wiki or file
operation which is more than just initialize the instance.
Invoked by run() before running through generator loop.
+
+ *New in version 3.0.*
"""
def teardown(self):
- """Some cleanups after run operation. Invoked by exit()."""
+ """Some cleanups after run operation. Invoked by exit().
+
+ *New in version 3.0.*
+ """
def run(self):
"""Process all pages in generator.
@@ -1743,6 +1756,8 @@
- available_options default setting
- script.ini options settings
- command line arguments
+
+ *New in version 3.0.*
"""
INI = 'scripts.ini'
diff --git a/pywikibot/bot_choice.py b/pywikibot/bot_choice.py
index b043c1d..433acc1 100755
--- a/pywikibot/bot_choice.py
+++ b/pywikibot/bot_choice.py
@@ -424,7 +424,10 @@
class ShowingListOption(ListOption, OutputOption):
- """An option to show a list and select an item."""
+ """An option to show a list and select an item.
+
+ *New in version 3.0.*
+ """
before_question = True
@@ -457,7 +460,10 @@
class MultipleChoiceList(ListOption):
- """An option to select multiple items from a list."""
+ """An option to select multiple items from a list.
+
+ *New in version 3.0.*
+ """
def test(self, value) -> bool:
"""Return whether the values are int and in the specified range."""
@@ -485,7 +491,10 @@
class ShowingMultipleChoiceList(ShowingListOption, MultipleChoiceList):
- """An option to show a list and select multiple items."""
+ """An option to show a list and select multiple items.
+
+ *New in version 3.0.*
+ """
class HighlightContextOption(ContextOption):
diff --git a/pywikibot/comms/eventstreams.py b/pywikibot/comms/eventstreams.py
index ec36b79..053ce0e 100644
--- a/pywikibot/comms/eventstreams.py
+++ b/pywikibot/comms/eventstreams.py
@@ -6,6 +6,8 @@
This module requires sseclient to be installed::
pip install sseclient
+
+*New in version 3.0.*
"""
#
# (C) Pywikibot team, 2017-2020
diff --git a/pywikibot/families/foundation_family.py b/pywikibot/families/foundation_family.py
index 2311f6a..cc9d7b2 100644
--- a/pywikibot/families/foundation_family.py
+++ b/pywikibot/families/foundation_family.py
@@ -1,4 +1,7 @@
-"""Family module for Foundation wiki."""
+"""Family module for Foundation wiki.
+
+*New in version 3.0.*
+"""
#
# (C) Pywikibot team, 2019-2020
#
diff --git a/pywikibot/families/wikihow_family.py b/pywikibot/families/wikihow_family.py
index 957beec..afe6f85 100644
--- a/pywikibot/families/wikihow_family.py
+++ b/pywikibot/families/wikihow_family.py
@@ -1,4 +1,7 @@
-"""Family module for Wikihow Wiki."""
+"""Family module for Wikihow Wiki.
+
+*New in version 3.0.*
+"""
#
# (C) Pywikibot team, 2020
#
diff --git a/pywikibot/families/wikimania_family.py b/pywikibot/families/wikimania_family.py
index 99e69cc..3ba5ba1 100644
--- a/pywikibot/families/wikimania_family.py
+++ b/pywikibot/families/wikimania_family.py
@@ -1,4 +1,7 @@
-"""Family module for Wikimania wikis."""
+"""Family module for Wikimania wikis.
+
+*New in version 3.0.*
+"""
#
# (C) Pywikibot team, 2017-2020
#
diff --git a/pywikibot/families/wikispore_family.py b/pywikibot/families/wikispore_family.py
index 3d9c60c..1dd3037 100644
--- a/pywikibot/families/wikispore_family.py
+++ b/pywikibot/families/wikispore_family.py
@@ -1,4 +1,7 @@
-"""Family module for Wikispore."""
+"""Family module for Wikispore.
+
+*New in version 4.1.*
+"""
#
# (C) Pywikibot team, 2020
#
diff --git a/pywikibot/family.py b/pywikibot/family.py
index aba6289..ec3a41e 100644
--- a/pywikibot/family.py
+++ b/pywikibot/family.py
@@ -656,11 +656,17 @@
self._get_cr_templates(code, fallback)
def get_edit_restricted_templates(self, code):
- """Return tuple of edit restricted templates."""
+ """Return tuple of edit restricted templates.
+
+ *New in version 3.0.*
+ """
return self.edit_restricted_templates.get(code, ())
def get_archived_page_templates(self, code):
- """Return tuple of archived page templates."""
+ """Return tuple of archived page templates.
+
+ *New in version 3.0.*
+ """
return self.archived_page_templates.get(code, ())
def disambig(self, code, fallback='_default'):
@@ -691,6 +697,8 @@
"""
Return whether a HTTPS certificate should be verified.
+ *Renamed in version 5.3.*
+
@param code: language code
@return: flag to verify the SSL certificate;
set it to False to allow access if certificate has an error.
@@ -701,7 +709,7 @@
future_warning=True)
def ignore_certificate_error(self, code: str) -> bool:
"""
- Return whether a HTTPS certificate error should be ignored.
+ DEPRECATED. Return whether a HTTPS certificate error should be ignored.
@param code: language code
@return: flag to allow access if certificate has an error.
@@ -776,11 +784,17 @@
return '{}/api.php'.format(self.scriptpath(code))
def eventstreams_host(self, code):
- """Hostname for EventStreams."""
+ """Hostname for EventStreams.
+
+ *New in version 3.0.*
+ """
raise NotImplementedError('This family does not support EventStreams')
def eventstreams_path(self, code):
- """Return path for EventStreams."""
+ """Return path for EventStreams.
+
+ *New in version 3.0.*
+ """
raise NotImplementedError('This family does not support EventStreams')
@deprecated_args(name='title')
@@ -1056,7 +1070,10 @@
class FandomFamily(Family):
- """Common features of Fandom families."""
+ """Common features of Fandom families.
+
+ *Renamed in version 3.0.*
+ """
@classproperty
def langs(cls):
diff --git a/pywikibot/page/__init__.py b/pywikibot/page/__init__.py
index a0cda40..a92c111 100644
--- a/pywikibot/page/__init__.py
+++ b/pywikibot/page/__init__.py
@@ -1781,7 +1781,10 @@
self.save(summary=reason)
def has_deleted_revisions(self) -> bool:
- """Return True if the page has deleted revisions."""
+ """Return True if the page has deleted revisions.
+
+ *New in version 4.2.*
+ """
if not hasattr(self, '_has_deleted_revisions'):
gen = self.site.deletedrevs(self, total=1, prop=['ids'])
self._has_deleted_revisions = bool(list(gen))
@@ -2196,6 +2199,8 @@
Return the first 'preferred' ranked Claim specified by Wikibase
property or the first 'normal' one otherwise.
+ *New in version 3.0.*
+
@param prop: property id, "P###"
@return: Claim object given by Wikibase property number
for this page object.
@@ -3147,6 +3152,8 @@
) -> Iterable[Tuple[Page, Revision]]:
"""Yield tuples describing this user's deleted edits.
+ *New in version 5.5.*
+
@param total: Limit results to this number of pages
@keyword start: Iterate contributions starting at this Timestamp
@keyword end: Iterate contributions ending at this Timestamp
@@ -5566,6 +5573,8 @@
Extends BaseLink by the following attribute:
- badges: Any badges associated with the sitelink
+
+ *New in version 3.0.*
"""
# Components used for __repr__
diff --git a/pywikibot/plural.py b/pywikibot/plural.py
index a53f469..6cef87a 100644
--- a/pywikibot/plural.py
+++ b/pywikibot/plural.py
@@ -108,5 +108,8 @@
def plural_rule(lang: str) -> PluralRule:
- """Return the plural rule for a given lang."""
+ """Return the plural rule for a given lang.
+
+ *New in version 4.3.*
+ """
return plural_rules.get(lang, plural_rules['_default'])
diff --git a/pywikibot/site/_apisite.py b/pywikibot/site/_apisite.py
index ed6e281..b10743b 100644
--- a/pywikibot/site/_apisite.py
+++ b/pywikibot/site/_apisite.py
@@ -1438,6 +1438,8 @@
If more than one target id is provided, the same action is taken for
all of them.
+ *New in version 6.0.*
+
@param targettype: Type of target. One of "archive", "filearchive",
"logging", "oldimage", "revision".
@param ids: Identifiers for the revision, log, file version or archive.
@@ -2061,6 +2063,9 @@
To delete a specific version of an image the oldimage identifier
must be provided.
+ *Renamed in version 6.1.*
+
+ *New in version 6.1:* keyword only parameter *oldimage* was added.
@param page: Page to be deleted or its pageid.
@type page: L{pywikibot.page.BasePage} or, for pageid, int or str
@@ -2150,6 +2155,12 @@
@see: U{https://www.mediawiki.org/wiki/API:Undelete}
+ *Renamed in version 6.1.*
+
+ *New in version 6.1:* *fileids* parameter was added.
+
+ *Changed in verson 6.1:* keyword argument required for *revisions*.
+
@param page: Page to be deleted.
@type page: pywikibot.BasePage
@param reason: Undeletion reason.
@@ -2545,6 +2556,9 @@
Either source_filename or source_url, but not both, must be provided.
+ *Changed in version 6.0:* keyword arguments required for all
+ parameters except *filepage*.
+
@param filepage: a FilePage object from which the wiki-name of the
file will be obtained.
@param source_filename: path to the file to be uploaded
diff --git a/pywikibot/site_detect.py b/pywikibot/site_detect.py
index bb6dd98..9f92a37 100644
--- a/pywikibot/site_detect.py
+++ b/pywikibot/site_detect.py
@@ -273,7 +273,10 @@
def check_response(response):
- """Raise ServerError if the response indicates a server error."""
+ """Raise ServerError if the response indicates a server error.
+
+ *New in version 3.0.*
+ """
if response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR:
raise ServerError(HTTPStatus(response.status_code).phrase)
diff --git a/pywikibot/textlib.py b/pywikibot/textlib.py
index 1bb1b71..4721c0e 100644
--- a/pywikibot/textlib.py
+++ b/pywikibot/textlib.py
@@ -897,6 +897,7 @@
('== Usage of A ==', 'Some usage...')]
result.footer = '[[Category:Things starting with A]]'
+ *New in version 3.0.*
"""
headings = _extract_headings(text, site)
sections = _extract_sections(text, headings)
diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py
index dd5df46..aa419b5 100644
--- a/pywikibot/tools/__init__.py
+++ b/pywikibot/tools/__init__.py
@@ -77,7 +77,10 @@
def has_module(module, version=None):
- """Check if a module can be imported."""
+ """Check if a module can be imported.
+
+ *New in version 3.0.*
+ """
try:
m = import_module(module)
except ImportError:
@@ -100,7 +103,7 @@
def empty_iterator():
# http://stackoverflow.com/a/13243870/473890
- """An iterator which does nothing."""
+ """DEPRECATED. An iterator which does nothing."""
return
yield
@@ -139,6 +142,8 @@
Those suppressed warnings that do not match the parameters will be raised
shown upon exit.
+
+ *New in vesion 3.0.*
"""
def __init__(self, message='', category=Warning, filename=''):
@@ -221,7 +226,7 @@
class DotReadableDict:
- """Parent class of Revision() and FileInfo().
+ """DEPRECATED. Lecacy class of Revision() and FileInfo().
Provide: __getitem__() and __repr__().
"""
@@ -244,7 +249,7 @@
class frozenmap(Mapping): # noqa: N801
- """Frozen mapping, preventing write after initialisation."""
+ """DEPRECATED. Frozen mapping, preventing write after initialisation."""
def __init__(self, data=(), **kwargs):
"""Initialize data in same ways like a dict."""
@@ -308,6 +313,8 @@
>>> data.clear()
>>> list(data)
[]
+
+ *New in version 6.1.*
"""
def __init__(self, keyattr: str):
@@ -384,7 +391,7 @@
class LazyRegex:
"""
- Regex object that obtains and compiles the regex on usage.
+ DEPRECATED. Regex object that obtains and compiles the regex on usage.
Instances behave like the object created using L{re.compile}.
"""
@@ -447,7 +454,7 @@
def __init__(self, pattern, flags=0, name=None, instead=None, since=None):
"""
- Initializer.
+ DEPRECATED. Deprecate a give regex.
If name is None, the regex pattern will be used as part of
the deprecation warning.
@@ -919,6 +926,8 @@
>>> tuple(roundrobin_generators('ABC', range(5)))
('A', 0, 'B', 1, 'C', 2, 3, 4)
+ *New in version 3.0.*
+
@param iterables: any iterable to combine in roundrobin way
@type iterables: iterable
@return: the combined generator of iterables
diff --git a/pywikibot/version.py b/pywikibot/version.py
index dfedd51..21f3d75 100644
--- a/pywikibot/version.py
+++ b/pywikibot/version.py
@@ -37,12 +37,13 @@
return _program_dir
-def get_toolforge_hostname():
+def get_toolforge_hostname() -> Optional[str]:
"""Get hostname of the current Toolforge host.
+ *New in version 3.0.*
+
@return: The hostname of the currently running host,
if it is in Wikimedia Toolforge; otherwise return None.
- @rtype: str or None
"""
if socket.getfqdn().endswith('.tools.eqiad.wmflabs'):
return socket.gethostname()
To view, visit change 684280. To unsubscribe, or for help writing mail filters, visit settings.