codekingpro/portable-devtools

1"""
2This is a module for defining private helpers which do not depend on the
3rest of NumPy.
4
5Everything in here must be self-contained so that it can be
6imported anywhere else without creating circular imports.
7If a utility requires the import of NumPy, it probably belongs
8in ``numpy._core``.
9"""
10
11import functools
12import warnings
13
14from ._convertions import asbytes, asunicode
15
16
17def set_module(module):
18    """Private decorator for overriding __module__ on a function or class.
19
20    Example usage::
21
22        @set_module('numpy')
23        def example():
24            pass
25
26        assert example.__module__ == 'numpy'
27    """
28    def decorator(func):
29        if module is not None:
30            if isinstance(func, type):
31                try:
32                    func._module_source = func.__module__
33                except (AttributeError):
34                    pass
35
36            func.__module__ = module
37        return func
38    return decorator
39
40
41def _rename_parameter(old_names, new_names, dep_version=None):
42    """
43    Generate decorator for backward-compatible keyword renaming.
44
45    Apply the decorator generated by `_rename_parameter` to functions with a
46    renamed parameter to maintain backward-compatibility.
47
48    After decoration, the function behaves as follows:
49    If only the new parameter is passed into the function, behave as usual.
50    If only the old parameter is passed into the function (as a keyword), raise
51    a DeprecationWarning if `dep_version` is provided, and behave as usual
52    otherwise.
53    If both old and new parameters are passed into the function, raise a
54    DeprecationWarning if `dep_version` is provided, and raise the appropriate
55    TypeError (function got multiple values for argument).
56
57    Parameters
58    ----------
59    old_names : list of str
60        Old names of parameters
61    new_name : list of str
62        New names of parameters
63    dep_version : str, optional
64        Version of NumPy in which old parameter was deprecated in the format
65        'X.Y.Z'. If supplied, the deprecation message will indicate that
66        support for the old parameter will be removed in version 'X.Y+2.Z'
67
68    Notes
69    -----
70    Untested with functions that accept *args. Probably won't work as written.
71
72    """
73    def decorator(fun):
74        @functools.wraps(fun)
75        def wrapper(*args, **kwargs):
76            __tracebackhide__ = True  # Hide traceback for py.test
77            for old_name, new_name in zip(old_names, new_names):
78                if old_name in kwargs:
79                    if dep_version:
80                        end_version = dep_version.split('.')
81                        end_version[1] = str(int(end_version[1]) + 2)
82                        end_version = '.'.join(end_version)
83                        msg = (f"Use of keyword argument `{old_name}` is "
84                               f"deprecated and replaced by `{new_name}`. "
85                               f"Support for `{old_name}` will be removed "
86                               f"in NumPy {end_version}.")
87                        warnings.warn(msg, DeprecationWarning, stacklevel=2)
88                    if new_name in kwargs:
89                        msg = (f"{fun.__name__}() got multiple values for "
90                               f"argument now known as `{new_name}`")
91                        raise TypeError(msg)
92                    kwargs[new_name] = kwargs.pop(old_name)
93            return fun(*args, **kwargs)
94        return wrapper
95    return decorator
96