[IMPR] use some keyword-only parameters  in _deprecate functions

- use some keyword-only parameters only with issue_deprecation_warning
  and redirect_func
- add some type hints

Patch detached from I3f24af286

Change-Id: I8039d6d0fcb3a28fed8cb974ddf572a5a8d6fe5c
---
M pywikibot/tools/_deprecate.py
1 file changed, 37 insertions(+), 12 deletions(-)

diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py
index 1cb2fd9..ca6f1eb 100644
--- a/pywikibot/tools/_deprecate.py
+++ b/pywikibot/tools/_deprecate.py
@@ -28,10 +28,11 @@
 import re
 import sys
 import types
+
 from contextlib import suppress
 from importlib import import_module
 from inspect import getfullargspec
-from typing import Any, Optional
+from typing import Any, Optional, Union
 from warnings import warn
 
 
@@ -162,7 +163,7 @@
     return outer_wrapper
 
 
-def _build_msg_string(instead: str, since: str) -> str:
+def _build_msg_string(instead: Optional[str], since: Optional[str]) -> str:
     """Build a deprecation warning message format string.
 
     .. versionadded:: 3.0
@@ -183,19 +184,24 @@
     return msg.format(since=' since release ' + since if since else '')
 
 
-def issue_deprecation_warning(name: str, instead: str = '', depth: int = 2,
-                              warning_class=None, since: str = '') -> None:
+def issue_deprecation_warning(name: str,
+                              instead: Optional[str] = None,
+                              depth: int = 2, *,
+                              warning_class: Optional[type] = None,
+                              since: Optional[str] = None):
     """Issue a deprecation warning.
 
     .. versionchanged:: 7.0
-       `since` parameter must be a release number, not a timestamp.
+       *since* parameter must be a release number, not a timestamp.
+
+    .. versionchanged:: 8.2
+       *warning_class* and *since* are keyword-only parameters.
 
     :param name: the name of the deprecated object
     :param instead: suggested replacement for the deprecated object
     :param depth: depth + 1 will be used as stacklevel for the warnings
-    :param warning_class: a warning class (category) to be used, defaults to
-        FutureWarning
-    :type warning_class: type
+    :param warning_class: a warning class (category) to be used,
+        defaults to FutureWarning
     :param since: a version string string when the method was deprecated
     """
     msg = _build_msg_string(instead, since)
@@ -298,7 +304,7 @@
     return decorator
 
 
-def deprecate_arg(old_arg: str, new_arg):
+def deprecate_arg(old_arg: str, new_arg: Union[str, None, bool]):
     """Decorator to declare old_arg deprecated and replace it with new_arg.
 
     Usage:
@@ -317,7 +323,6 @@
 
     :param old_arg: old keyword
     :param new_arg: new keyword
-    :type new_arg: str or None or bool
     """
     return deprecated_args(**{old_arg: new_arg})
 
@@ -484,7 +489,8 @@
     return decorator
 
 
-def redirect_func(target, source_module: Optional[str] = None,
+def redirect_func(target, *,
+                  source_module: Optional[str] = None,
                   target_module: Optional[str] = None,
                   old_name: Optional[str] = None,
                   class_name: Optional[str] = None,
@@ -497,7 +503,10 @@
     parameters.
 
     .. versionchanged:: 7.0
-       ``since`` parameter must be a release number, not a timestamp.
+       *since* parameter must be a release number, not a timestamp.
+
+    .. versionchanged:: 8.2
+       All parameters except *target* are keyword-only parameters.
 
     :param target: The targeted function which is to be executed.
     :type target: callable
@@ -522,6 +531,7 @@
             old_name, new_name, since=since,
             warning_class=None if future_warning else DeprecationWarning)
         return target(*a, **kw)
+
     if target_module is None:
         target_module = target.__module__
     if target_module and target_module[-1] != '.':

