jenkins-bot submitted this change.
[doc] Add version hints to tools
Change-Id: I7f7924cfeec646e2684e5719ed162b7c22a57554
---
M pywikibot/tools/__init__.py
M pywikibot/tools/_deprecate.py
2 files changed, 108 insertions(+), 21 deletions(-)
diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py
index 96bd494..a988b10 100644
--- a/pywikibot/tools/__init__.py
+++ b/pywikibot/tools/__init__.py
@@ -71,6 +71,9 @@
def is_ip_address(value: str) -> bool:
"""Check if a value is a valid IPv4 or IPv6 address.
+ .. versionadded:: 6.1
+ Was renamed from ``is_IP()``.
+
:param value: value to check
"""
with suppress(ValueError):
@@ -83,7 +86,11 @@
def has_module(module, version=None):
"""Check if a module can be imported.
- *New in version 3.0.*
+ .. versionadded:: 3.0
+
+ .. versionchanged:: 6.1
+ Dependency of distutils was dropped because the package will be
+ removed with Python 3.12.
"""
try:
m = import_module(module)
@@ -120,6 +127,8 @@
return cls._bar
Foo.bar gives 'baz'.
+
+ .. versionadded:: 3.0
"""
def __init__(self, cls_method):
@@ -139,7 +148,7 @@
Those suppressed warnings that do not match the parameters will be raised
shown upon exit.
- *New in vesion 3.0.*
+ .. versionadded:: 3.0
"""
def __init__(self, message='', category=Warning, filename=''):
@@ -193,7 +202,10 @@
# From http://python3porting.com/preparing.html
class ComparableMixin:
- """Mixin class to allow comparing to other objects which are comparable."""
+ """Mixin class to allow comparing to other objects which are comparable.
+
+ .. versionadded:: 3.0
+ """
def __lt__(self, other):
"""Compare if self is less than other."""
@@ -255,7 +267,7 @@
>>> list(data)
[]
- *New in version 6.1.*
+ .. versionadded:: 6.1
"""
def __init__(self, keyattr: str):
@@ -336,6 +348,8 @@
Return a string with the first character uncapitalized.
Empty strings are supported. The original string is not changed.
+
+ .. versionadded:: 3.0
"""
return string[:1].lower() + string[1:]
@@ -346,6 +360,8 @@
Empty strings are supported. The original string is not changed.
+ .. versionadded:: 3.0
+
:note: MediaWiki doesn't capitalize some characters the same way as Python.
This function tries to be close to MediaWiki's capitalize function in
title.php. See T179115 and T200357.
@@ -355,7 +371,10 @@
def normalize_username(username) -> Optional[str]:
- """Normalize the username."""
+ """Normalize the username.
+
+ .. versionadded:: 3.0
+ """
if not username:
return None
username = re.sub('[_ ]+', ' ', username).strip()
@@ -368,11 +387,9 @@
This Version provides propreties of vendor package 20.4 shipped with
setuptools 49.4.0.
- """
- def __init__(self, version):
- """Add additional properties of not provided by base class."""
- super().__init__(version)
+ .. versionadded:: 6.4
+ """
def __getattr__(self, name):
"""Provides propreties of vendor package 20.4."""
@@ -415,6 +432,12 @@
< 1.35-rc-1 < 1.35-rc.2 < 1.35
Any other suffixes are considered invalid.
+
+ .. versionadded:: 3.0
+
+ .. versionchanged:: 6.1
+ Dependency of distutils was dropped because the package will be
+ removed with Python 3.12.
"""
MEDIAWIKI_VERSION = re.compile(
@@ -521,7 +544,7 @@
>>> lock.locked()
False
- *New in version 6.2*
+ .. versionadded:: 6.2
"""
def __init__(self, *args, **kwargs):
@@ -584,6 +607,7 @@
>>> data
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
+ ..versionadded:: 3.0
"""
def __init__(self, group=None, target=None, name='GeneratorThread',
@@ -796,6 +820,20 @@
>>> list(intersect_generators(*iterables, allow_duplicates=True))
['m', 'i', 's', 's', 'i']
+
+ .. versionadded:: 3.0
+
+ .. versionchanged:: 5.0
+ Avoid duplicates (T263947).
+
+ .. versionchanged:: 6.4
+ ``genlist`` was renamed to ``iterables``; consecutive iterables
+ are to be used as iterables parameters or '*' to unpack a list
+
+ .. deprecated:: 6.4
+ ``allow_duplicates`` as positional argument,
+ ``iterables`` as list type
+
:param iterables: page generators
:param allow_duplicates: optional keyword argument to allow duplicates
if present in all generators
@@ -901,7 +939,10 @@
>>> tuple(roundrobin_generators('ABC', range(5)))
('A', 0, 'B', 1, 'C', 2, 3, 4)
- *New in version 3.0.*
+ .. versionadded:: 3.0
+ .. versionchanged:: 6.4
+ A sentinel variable is used to determine the end of an iterable
+ instead of None.
:param iterables: any iterable to combine in roundrobin way
:type iterables: iterable
@@ -942,6 +983,8 @@
Note: This is not thread safe.
+ .. versionadded: 3.0
+
:param iterable: the source iterable
:type iterable: collections.abc.Iterable
:param container: storage of seen items
@@ -978,7 +1021,10 @@
class CombinedError(KeyError, IndexError):
- """An error that gets caught by both KeyError and IndexError."""
+ """An error that gets caught by both KeyError and IndexError.
+
+ .. versionadded:: 3.0
+ """
class EmptyDefault(str, Mapping):
@@ -992,6 +1038,10 @@
Accessing a value via __getitem__ will result in a combined KeyError and
IndexError.
+
+ .. versionadded:: 3.0
+ .. versionchanged:: 6.2
+ ``empty_iterator()`` was removed in favour of ``iter()``.
"""
def __init__(self):
@@ -1017,29 +1067,45 @@
When '_own_desc' is defined it'll also issue a deprecation warning using
issue_deprecation_warning('Calling ' + _own_desc, 'it directly').
+
+ .. versionadded:: 3.0
+ .. deprecated:: 6.2
"""
def __call__(self):
"""Do nothing and just return itself."""
issue_deprecation_warning('Referencing this attribute like a function',
- 'it directly', since='20210420')
+ 'it directly', since='6.2')
return self
class SelfCallDict(SelfCallMixin, dict):
- """Dict with SelfCallMixin."""
+ """Dict with SelfCallMixin.
+
+ .. versionadded:: 3.0
+ .. deprecated:: 6.2
+ """
class SelfCallString(SelfCallMixin, str):
- """String with SelfCallMixin."""
+ """String with SelfCallMixin.
+
+ .. versionadded:: 3.0
+ .. deprecated:: 6.2
+ """
class DequeGenerator(Iterator, collections.deque):
- """A generator that allows items to be added during generating."""
+ """A generator that allows items to be added during generating.
+
+ .. versionadded:: 3.0
+ .. versionchanged:: 6.1
+ Provide a representation string.
+ """
def __next__(self):
"""Iterator method."""
@@ -1067,6 +1133,8 @@
The compression is either selected via the magic number or file ending.
+ .. versionadded:: 3.0
+
:param filename: The filename.
:type filename: str
:param use_extension: Use the file extension instead of the magic number
@@ -1168,6 +1236,8 @@
The positional arguments are the dictionaries to be merged. It is also
possible to define an additional dict using the keyword arguments.
+
+ .. versionadded: 3.0
"""
args = list(args) + [dict(kwargs)]
conflicts = set()
@@ -1185,6 +1255,8 @@
def file_mode_checker(filename: str, mode=0o600, quiet=False, create=False):
"""Check file mode and update it, if needed.
+ .. versionadded: 3.0
+
:param filename: filename path
:param mode: requested file mode
:type mode: int
@@ -1215,6 +1287,8 @@
Result is expressed as hexdigest().
+ .. versionadded: 3.0
+
:param filename: filename path
:param sha: hashing function among the following in hashlib:
md5(), sha1(), sha224(), sha256(), sha384(), and sha512()
diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py
index 829b24c..a043e5d 100644
--- a/pywikibot/tools/_deprecate.py
+++ b/pywikibot/tools/_deprecate.py
@@ -15,7 +15,8 @@
only one arg, and that arg be a callable, as it will be detected as
a deprecator without any arguments.
-*Changed in version 6.4:* deprecation decorators moved to _deprecate module
+.. versionchanged 6.4:
+ deprecation decorators moved to _deprecate module
"""
#
# (C) Pywikibot team, 2008-2021
@@ -37,7 +38,10 @@
class _NotImplementedWarning(RuntimeWarning):
- """Feature that is no longer implemented."""
+ """Feature that is no longer implemented.
+
+ .. versionadded:: 3.0
+ """
def add_decorated_full_name(obj, stacklevel=1):
@@ -66,7 +70,10 @@
def manage_wrapping(wrapper, obj):
- """Add attributes to wrapper and wrapped functions."""
+ """Add attributes to wrapper and wrapped functions.
+
+ .. versionadded:: 3.0
+ """
wrapper.__doc__ = obj.__doc__
wrapper.__name__ = obj.__name__
wrapper.__module__ = obj.__module__
@@ -91,7 +98,10 @@
def get_wrapper_depth(wrapper):
- """Return depth of wrapper function."""
+ """Return depth of wrapper function.
+
+ .. versionadded:: 3.0
+ """
return wrapper.__wrapped__.__wrappers__ + (1 - wrapper.__depth__)
@@ -155,7 +165,10 @@
def _build_msg_string(instead, since):
- """Build a deprecation warning message format string."""
+ """Build a deprecation warning message format string.
+
+ .. versionadded:: 3.0
+ """
if not since:
since = ''
elif '.' in since:
To view, visit change 729490. To unsubscribe, or for help writing mail filters, visit settings.