Skip to content

BUG,ENH: make deprecated decorator work (and more flexibly) #7651

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 22, 2016
Merged

BUG,ENH: make deprecated decorator work (and more flexibly) #7651

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 37 additions & 25 deletions lib/matplotlib/cbook.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,36 +50,41 @@ class MatplotlibDeprecationWarning(UserWarning):

def _generate_deprecation_message(since, message='', name='',
alternative='', pending=False,
obj_type='attribute'):
obj_type='attribute',
addendum=''):

if not message:
altmessage = ''

if pending:
message = (
'The %(func)s %(obj_type)s will be deprecated in a '
'The %(name)s %(obj_type)s will be deprecated in a '
'future version.')
else:
message = (
'The %(func)s %(obj_type)s was deprecated in version '
'The %(name)s %(obj_type)s was deprecated in version '
'%(since)s.')
if alternative:
altmessage = ' Use %s instead.' % alternative

message = ((message % {
'func': name,
'name': name,
'alternative': alternative,
'obj_type': obj_type,
'since': since}) +
altmessage)
altmessage = ''
if alternative:
altmessage = ' Use %s instead.' % alternative

message = ((message % {
'func': name,
'name': name,
'alternative': alternative,
'obj_type': obj_type,
'since': since}) +
altmessage)

if addendum:
message += addendum

return message


def warn_deprecated(
since, message='', name='', alternative='', pending=False,
obj_type='attribute'):
obj_type='attribute', addendum=''):
"""
Used to display deprecation warning in a standard way.

Expand All @@ -90,7 +95,7 @@ def warn_deprecated(

message : str, optional
Override the default deprecation message. The format
specifier `%(func)s` may be used for the name of the function,
specifier `%(name)s` may be used for the name of the function,
and `%(alternative)s` may be used in the deprecation message
to insert the name of an alternative to the deprecated
function. `%(obj_type)s` may be used to insert a friendly name
Expand All @@ -111,6 +116,9 @@ def warn_deprecated(
obj_type : str, optional
The object type being deprecated.

addendum : str, optional
Additional text appended directly to the final message.

Examples
--------

Expand All @@ -122,13 +130,13 @@ def warn_deprecated(

"""
message = _generate_deprecation_message(
since, message, name, alternative, pending, obj_type)
since, message, name, alternative, pending, obj_type)

warnings.warn(message, mplDeprecation, stacklevel=1)


def deprecated(since, message='', name='', alternative='', pending=False,
obj_type=None):
obj_type=None, addendum=''):
"""
Decorator to mark a function or a class as deprecated.

Expand All @@ -140,15 +148,15 @@ def deprecated(since, message='', name='', alternative='', pending=False,

message : str, optional
Override the default deprecation message. The format
specifier `%(func)s` may be used for the name of the function,
specifier `%(name)s` may be used for the name of the object,
and `%(alternative)s` may be used in the deprecation message
to insert the name of an alternative to the deprecated
function. `%(obj_type)s` may be used to insert a friendly name
object. `%(obj_type)s` may be used to insert a friendly name
for the type of object being deprecated.

name : str, optional
The name of the deprecated function; if not provided the name
is automatically determined from the passed in function,
The name of the deprecated object; if not provided the name
is automatically determined from the passed in object,
though this is useful in the case of renamed functions, where
the new function is just assigned to the name of the
deprecated function. For example::
Expand All @@ -158,14 +166,17 @@ def new_function():
oldFunction = new_function

alternative : str, optional
An alternative function that the user may use in place of the
deprecated function. The deprecation warning will tell the user
An alternative object that the user may use in place of the
deprecated object. The deprecation warning will tell the user
about this alternative if provided.

pending : bool, optional
If True, uses a PendingDeprecationWarning instead of a
DeprecationWarning.

addendum : str, optional
Additional text appended directly to the final message.

Examples
--------

Expand All @@ -177,7 +188,7 @@ def the_function_to_deprecate():

"""
def deprecate(obj, message=message, name=name, alternative=alternative,
pending=pending):
pending=pending, addendum=addendum):
import textwrap

if not name:
Expand Down Expand Up @@ -212,7 +223,8 @@ def finalize(wrapper, new_doc):
return wrapper

message = _generate_deprecation_message(
since, message, name, alternative, pending, obj_type)
since, message, name, alternative, pending,
obj_type, addendum)

def wrapper(*args, **kwargs):
warnings.warn(message, mplDeprecation, stacklevel=2)
Expand Down