D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
local
/
lib64
/
python3.6
/
site-packages
/
matplotlib
/
cbook
/
Filename :
deprecation.py
back
Copy
import contextlib import functools import inspect import warnings class MatplotlibDeprecationWarning(UserWarning): """ A class for issuing deprecation warnings for Matplotlib users. In light of the fact that Python builtin DeprecationWarnings are ignored by default as of Python 2.7 (see link below), this class was put in to allow for the signaling of deprecation, but via UserWarnings which are not ignored by default. https://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x """ # mplDeprecation is deprecated. Use MatplotlibDeprecationWarning instead. mplDeprecation = MatplotlibDeprecationWarning def _generate_deprecation_warning( since, message='', name='', alternative='', pending=False, obj_type='', addendum='', *, removal=''): if pending: if removal: raise ValueError( "A pending deprecation cannot have a scheduled removal") else: if removal: removal = "in {}".format(removal) else: removal = {"2.2": "in 3.1", "3.0": "in 3.2", "3.1": "in 3.3"}.get( since, "two minor releases later") if not message: message = ( "\nThe %(name)s %(obj_type)s" + (" will be deprecated in a future version" if pending else (" was deprecated in Matplotlib %(since)s" + (" and will be removed %(removal)s" if removal else ""))) + "." + (" Use %(alternative)s instead." if alternative else "") + (" %(addendum)s" if addendum else "")) warning_cls = (PendingDeprecationWarning if pending else MatplotlibDeprecationWarning) return warning_cls(message % dict( func=name, name=name, obj_type=obj_type, since=since, removal=removal, alternative=alternative, addendum=addendum)) def warn_deprecated( since, *, message='', name='', alternative='', pending=False, obj_type='', addendum='', removal=''): """ Display a standardized deprecation. Parameters ---------- since : str The release at which this API became deprecated. message : str, optional Override the default deprecation message. The ``%(since)s``, ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``, and ``%(removal)s`` format specifiers will be replaced by the values of the respective arguments passed to this function. name : str, optional The name of the deprecated object. alternative : str, optional An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. obj_type : str, optional The object type being deprecated. addendum : str, optional Additional text appended directly to the final message. removal : str, optional The expected removal version. With the default (an empty string), a removal version is automatically computed from *since*. Set to other Falsy values to not schedule a removal date. Cannot be used together with *pending*. Examples -------- Basic example:: # To warn of the deprecation of "matplotlib.name_of_module" warn_deprecated('1.4.0', name='matplotlib.name_of_module', obj_type='module') """ warning = _generate_deprecation_warning( since, message, name, alternative, pending, obj_type, addendum, removal=removal) from . import _warn_external _warn_external(warning, category=MatplotlibDeprecationWarning) def deprecated(since, *, message='', name='', alternative='', pending=False, obj_type=None, addendum='', removal=''): """ Decorator to mark a function, a class, or a property as deprecated. When deprecating a classmethod, a staticmethod, or a property, the ``@deprecated`` decorator should go *under* ``@classmethod`` and ``@staticmethod`` (i.e., `deprecated` should directly decorate the underlying callable), but *over* ``@property``. Parameters ---------- since : str The release at which this API became deprecated. message : str, optional Override the default deprecation message. The ``%(since)s``, ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``, and ``%(removal)s`` format specifiers will be replaced by the values of the respective arguments passed to this function. name : str, optional The name used in the deprecation message; if not provided, the name is automatically determined from the deprecated object. alternative : str, optional An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. obj_type : str, optional The object type being deprecated; by default, 'class' if decorating a class, 'attribute' if decorating a property, 'function' otherwise. addendum : str, optional Additional text appended directly to the final message. removal : str, optional The expected removal version. With the default (an empty string), a removal version is automatically computed from *since*. Set to other Falsy values to not schedule a removal date. Cannot be used together with *pending*. Examples -------- Basic example:: @deprecated('1.4.0') def the_function_to_deprecate(): pass """ def deprecate(obj, message=message, name=name, alternative=alternative, pending=pending, obj_type=obj_type, addendum=addendum): if isinstance(obj, type): if obj_type is None: obj_type = "class" func = obj.__init__ name = name or obj.__name__ old_doc = obj.__doc__ def finalize(wrapper, new_doc): try: obj.__doc__ = new_doc except AttributeError: # Can't set on some extension objects. pass obj.__init__ = functools.wraps(obj.__init__)(wrapper) return obj elif isinstance(obj, property): obj_type = "attribute" func = None name = name or obj.fget.__name__ old_doc = obj.__doc__ class _deprecated_property(property): def __get__(self, instance, owner): if instance is not None: from . import _warn_external _warn_external(warning) return super().__get__(instance, owner) def __set__(self, instance, value): if instance is not None: from . import _warn_external _warn_external(warning) return super().__set__(instance, value) def __delete__(self, instance): if instance is not None: from . import _warn_external _warn_external(warning) return super().__delete__(instance) def finalize(_, new_doc): return _deprecated_property( fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc) else: if obj_type is None: obj_type = "function" func = obj name = name or obj.__name__ old_doc = func.__doc__ def finalize(wrapper, new_doc): wrapper = functools.wraps(func)(wrapper) wrapper.__doc__ = new_doc return wrapper warning = _generate_deprecation_warning( since, message, name, alternative, pending, obj_type, addendum, removal=removal) def wrapper(*args, **kwargs): from . import _warn_external _warn_external(warning) return func(*args, **kwargs) old_doc = inspect.cleandoc(old_doc or '').strip('\n') notes_header = '\nNotes\n-----' new_doc = (f"[*Deprecated*] {old_doc}\n" f"{notes_header if notes_header not in old_doc else ''}\n" f".. deprecated:: {since}\n" f" {message.strip()}") if not old_doc: # This is to prevent a spurious 'unexpected unindent' warning from # docutils when the original docstring was blank. new_doc += r'\ ' return finalize(wrapper, new_doc) return deprecate class _deprecate_privatize_attribute: """ Helper to deprecate public access to an attribute. This helper should only be used at class scope, as follows:: class Foo: attr = _deprecate_privatize_attribute(*args, **kwargs) where *all* parameters are forwarded to `deprecated`. This form makes ``attr`` a property which forwards access to ``self._attr`` (same name but with a leading underscore), with a deprecation warning. Note that the attribute name is derived from *the name this helper is assigned to*. """ def __init__(self, *args, **kwargs): self.deprecator = deprecated(*args, **kwargs) def __set_name__(self, owner, name): setattr(owner, name, self.deprecator( property(lambda self: getattr(self, f"_{name}")), name=name)) def _rename_parameter(since, old, new, func=None): """ Decorator indicating that parameter *old* of *func* is renamed to *new*. The actual implementation of *func* should use *new*, not *old*. If *old* is passed to *func*, a DeprecationWarning is emitted, and its value is used, even if *new* is also passed by keyword (this is to simplify pyplot wrapper functions, which always pass *new* explicitly to the Axes method). If *new* is also passed but positionally, a TypeError will be raised by the underlying function during argument binding. Examples -------- :: @_rename_parameter("3.1", "bad_name", "good_name") def func(good_name): ... """ if func is None: return functools.partial(_rename_parameter, since, old, new) signature = inspect.signature(func) assert old not in signature.parameters, ( f"Matplotlib internal error: {old!r} cannot be a parameter for " f"{func.__name__}()") assert new in signature.parameters, ( f"Matplotlib internal error: {new!r} must be a parameter for " f"{func.__name__}()") @functools.wraps(func) def wrapper(*args, **kwargs): if old in kwargs: warn_deprecated( since, message=f"The {old!r} parameter of {func.__name__}() " f"has been renamed {new!r} since Matplotlib {since}; support " f"for the old name will be dropped %(removal)s.") kwargs[new] = kwargs.pop(old) return func(*args, **kwargs) # wrapper() must keep the same documented signature as func(): if we # instead made both *old* and *new* appear in wrapper()'s signature, they # would both show up in the pyplot function for an Axes method as well and # pyplot would explicitly pass both arguments to the Axes method. return wrapper class _deprecated_parameter_class: def __repr__(self): return "<deprecated parameter>" _deprecated_parameter = _deprecated_parameter_class() def _delete_parameter(since, name, func=None, **kwargs): """ Decorator indicating that parameter *name* of *func* is being deprecated. The actual implementation of *func* should keep the *name* parameter in its signature, or accept a ``**kwargs`` argument (through which *name* would be passed). Parameters that come after the deprecated parameter effectively become keyword-only (as they cannot be passed positionally without triggering the DeprecationWarning on the deprecated parameter), and should be marked as such after the deprecation period has passed and the deprecated parameter is removed. Parameters other than *since*, *name*, and *func* are keyword-only and forwarded to `.warn_deprecated`. Examples -------- :: @_delete_parameter("3.1", "unused") def func(used_arg, other_arg, unused, more_args): ... """ if func is None: return functools.partial(_delete_parameter, since, name, **kwargs) signature = inspect.signature(func) # Name of `**kwargs` parameter of the decorated function, typically # "kwargs" if such a parameter exists, or None if the decorated function # doesn't accept `**kwargs`. kwargs_name = next((param.name for param in signature.parameters.values() if param.kind == inspect.Parameter.VAR_KEYWORD), None) if name in signature.parameters: kind = signature.parameters[name].kind is_varargs = kind is inspect.Parameter.VAR_POSITIONAL is_varkwargs = kind is inspect.Parameter.VAR_KEYWORD if not is_varargs and not is_varkwargs: func.__signature__ = signature = signature.replace(parameters=[ param.replace(default=_deprecated_parameter) if param.name == name else param for param in signature.parameters.values()]) else: is_varargs = is_varkwargs = False assert kwargs_name, ( f"Matplotlib internal error: {name!r} must be a parameter for " f"{func.__name__}()") addendum = kwargs.pop('addendum', None) @functools.wraps(func) def wrapper(*inner_args, **inner_kwargs): arguments = signature.bind(*inner_args, **inner_kwargs).arguments if is_varargs and arguments.get(name): warn_deprecated( since, message=f"Additional positional arguments to " f"{func.__name__}() are deprecated since %(since)s and " f"support for them will be removed %(removal)s.") elif is_varkwargs and arguments.get(name): warn_deprecated( since, message=f"Additional keyword arguments to " f"{func.__name__}() are deprecated since %(since)s and " f"support for them will be removed %(removal)s.") # We cannot just check `name not in arguments` because the pyplot # wrappers always pass all arguments explicitly. elif any(name in d and d[name] != _deprecated_parameter for d in [arguments, arguments.get(kwargs_name, {})]): deprecation_addendum = ( f"If any parameter follows {name!r}, they should be passed as " f"keyword, not positionally.") warn_deprecated( since, name=repr(name), obj_type=f"parameter of {func.__name__}()", addendum=(addendum + " " + deprecation_addendum) if addendum else deprecation_addendum, **kwargs) return func(*inner_args, **inner_kwargs) return wrapper def _make_keyword_only(since, name, func=None): """ Decorator indicating that passing parameter *name* (or any of the following ones) positionally to *func* is being deprecated. """ if func is None: return functools.partial(_make_keyword_only, since, name) signature = inspect.signature(func) POK = inspect.Parameter.POSITIONAL_OR_KEYWORD KWO = inspect.Parameter.KEYWORD_ONLY assert (name in signature.parameters and signature.parameters[name].kind == POK), ( f"Matplotlib internal error: {name!r} must be a positional-or-keyword " f"parameter for {func.__name__}()") names = [*signature.parameters] kwonly = [name for name in names[names.index(name):] if signature.parameters[name].kind == POK] func.__signature__ = signature.replace(parameters=[ param.replace(kind=KWO) if param.name in kwonly else param for param in signature.parameters.values()]) @functools.wraps(func) def wrapper(*args, **kwargs): # Don't use signature.bind here, as it would fail when stacked with # _rename_parameter and an "old" argument name is passed in # (signature.bind would fail, but the actual call would succeed). idx = [*func.__signature__.parameters].index(name) if len(args) > idx: warn_deprecated( since, message="Passing the %(name)s %(obj_type)s " "positionally is deprecated since Matplotlib %(since)s; the " "parameter will become keyword-only %(removal)s.", name=name, obj_type=f"parameter of {func.__name__}()") return func(*args, **kwargs) return wrapper def _deprecate_method_override(method, obj, *, allow_empty=False, **kwargs): """ Return ``obj.method`` with a deprecation if it was overridden, else None. Parameters ---------- method An unbound method, i.e. an expression of the form ``Class.method_name``. Remember that within the body of a method, one can always use ``__class__`` to refer to the class that is currently being defined. obj An object of the class where *method* is defined. allow_empty : bool, default: False Whether to allow overrides by "empty" methods without emitting a warning. **kwargs Additional parameters passed to `warn_deprecated` to generate the deprecation warning; must at least include the "since" key. """ def empty(): pass def empty_with_docstring(): """doc""" name = method.__name__ bound_method = getattr(obj, name) if (bound_method != method.__get__(obj) and (not allow_empty or (getattr(getattr(bound_method, "__code__", None), "co_code", None) not in [empty.__code__.co_code, empty_with_docstring.__code__.co_code]))): warn_deprecated(**{"name": name, "obj_type": "method", **kwargs}) return bound_method return None @contextlib.contextmanager def _suppress_matplotlib_deprecation_warning(): with warnings.catch_warnings(): warnings.simplefilter("ignore", MatplotlibDeprecationWarning) yield