match = re.match(r"^(?P<major>\d+)\.(?P<minor>\d+)(\.(?P<patch>\d+))?", version)

if match is None:

return (0,0,0)

groups = match.groupdict()

"""A warning class for deprecated methods

def __init__(self, function, deprecated_in, removed_in, details=""):

# NOTE: The docstring only works for this class if it appears up

# near the class name, not here inside __init__. I think it has

# to do with being an exception class.

self.function = function

self.deprecated_in = deprecated_in

self.removed_in = removed_in

self.details = details

super(DeprecatedWarning, self).__init__(function, deprecated_in,

removed_in, details)

def __str__(self):

# Use a defaultdict to give us the empty string

# when a part isn't included.

parts = collections.defaultdict(str)

parts["function"] = self.function

if self.deprecated_in:

parts["deprecated"] = " as of %s" % self.deprecated_in

if self.removed_in:

parts["removed"] = " and will be removed {} {}".format("on" if isinstance(self.removed_in, date) else "in",

self.removed_in)

if any([self.deprecated_in, self.removed_in, self.details]):

parts["period"] = "."

if self.details:

parts["details"] = " %s" % self.details

return ("%(function)s is deprecated%(deprecated)s%(removed)s"

"""A warning class for methods to be removed

def __str__(self):

parts = collections.defaultdict(str)

parts["function"] = self.function

parts["removed"] = self.removed_in

if self.details:

parts["details"] = " %s" % self.details

return ("%(function)s is unsupported as of %(removed)s."

details=""):

"""Decorate a function to signify its deprecation

# You can't just jump to removal. It's weird, unfair, and also makes

# building up the docstring weird.

if deprecated_in is None and removed_in is not None:

raise TypeError("Cannot set removed_in to a value "

"without also setting deprecated_in")

# Only warn when it's appropriate. There may be cases when it makes sense

# to add this decorator before a formal deprecation period begins.

# In CPython, PendingDeprecatedWarning gets used in that period,

# so perhaps mimick that at some point.

is_deprecated = False

is_unsupported = False

# StrictVersion won't take a None or a "", so make whatever goes to it

# is at least *something*. Compare versions only if removed_in is not

# of type datetime.date

if isinstance(removed_in, date):

if date.today() >= removed_in:

is_unsupported = True

else:

is_deprecated = True

elif current_version:

current_version = parse_version(current_version)

if (removed_in

and current_version >= parse_version(removed_in)):

is_unsupported = True

elif (deprecated_in

and current_version >= parse_version(deprecated_in)):

is_deprecated = True

else:

# If we can't actually calculate that we're in a period of

# deprecation...well, they used the decorator, so it's deprecated.

# This will cover the case of someone just using

# @deprecated("1.0") without the other advantages.

is_deprecated = True

should_warn = any([is_deprecated, is_unsupported])

def _function_wrapper(function):

if should_warn:

# Everything *should* have a docstring, but just in case...

existing_docstring = function.__doc__ or ""

# The various parts of this decorator being optional makes for

# a number of ways the deprecation notice could go. The following

# makes for a nicely constructed sentence with or without any

# of the parts.

# If removed_in is a date, use "removed on"

# If removed_in is a version, use "removed in"

parts = {

"deprecated_in":

" %s" % deprecated_in if deprecated_in else "<unknown>",

"removed_in":

"\n This will be removed {} {}.".format("on" if isinstance(removed_in, date) else "in",

removed_in) if removed_in else "",

"details":

" %s" % details if details else ""}

deprecation_note = (".. deprecated::{deprecated_in}"

"{removed_in}{details}".format(**parts))

# default location for insertion of deprecation note

loc = 1

# split docstring at first occurrence of newline

string_list = existing_docstring.split("\n", 1)

if len(string_list) > 1:

# With a multi-line docstring, when we modify

# existing_docstring to add our deprecation_note,

# if we're not careful we'll interfere with the

# indentation levels of the contents below the

# first line, or as PEP 257 calls it, the summary

# line. Since the summary line can start on the

# same line as the """, dedenting the whole thing

# won't help. Split the summary and contents up,

# dedent the contents independently, then join

# summary, dedent'ed contents, and our

# deprecation_note.

# in-place dedent docstring content

string_list[1] = textwrap.dedent(string_list[1])

# we need another newline

string_list.insert(loc, "\n")

# change the message_location if we add to end of docstring

# do this always if not "top"

if message_location != "top":

loc = 3

# insert deprecation note and dual newline

string_list.insert(loc, deprecation_note)

string_list.insert(loc, "\n\n")

function.__doc__ = "".join(string_list)

@functools.wraps(function)

def _inner(*args, **kwargs):

if should_warn:

if is_unsupported:

cls = UnsupportedWarning

else:

cls = DeprecatedWarning

the_warning = cls(function.__name__, deprecated_in,

removed_in, details)

warnings.warn(the_warning, category=DeprecationWarning,

stacklevel=2)

return function(*args, **kwargs)

return _inner

"""Decorate a test method to track removal of deprecated code

# NOTE(briancurtin): Unless this is named test_inner, nose won't work

# properly. See Issue #32.

@functools.wraps(method)

def test_inner(*args, **kwargs):

with warnings.catch_warnings(record=True) as caught_warnings:

warnings.simplefilter("always")

rv = method(*args, **kwargs)

for warning in caught_warnings:

if warning.category == UnsupportedWarning:

raise AssertionError(

("%s uses a function that should be removed: %s" %

(method, str(warning.message))))

return rv