jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/684280 )
Change subject: [doc] Additional version hints to doc strings ......................................................................
[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(-)
Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified
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%7D
+ *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()
pywikibot-commits@lists.wikimedia.org