jenkins-bot has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/729490 )
Change subject: [doc] Add version hints to tools ......................................................................
[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(-)
Approvals: Xqt: Looks good to me, approved jenkins-bot: Verified
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: