Simplify deprecation machinery: don't cache previous messages, and use warnings rather than logging.

[mdickinson]

Alternative to #196.

This PR simplifies the Traits @deprecated decorator in two ways:

1. It removes the cache: if an application using Traits doesn't want to see duplicate log message or warnings, then it should be the job of the application to configure warnings / logging appropriately. The cache was also making testing difficult (see Deprecate get and set methods on HasTraits #190 and Improvements to deprecated #196).
2. It replaces the logging call with a simple DeprecationWarning.

If there's a strong case for using logging instead of warnings, we can revert the second part.

Updated the PR to add a test, along with an assertDeprecated method to UnittestTools.

[coveralls]

Coverage decreased (-0.04%) when pulling a2f1cdc on feature/simpler-deprecations into 751603b on master.

[mdickinson]

I'd like to add tests for this. Those tests might be a bit messy, though: in Python 2, extra machinery is needed to reset the filterwarnings registry: catch_warnings by itself doesn't reset global state.

[coveralls]

Coverage increased (+0.01%) when pulling 6d0619e on feature/simpler-deprecations into 751603b on master.

[coveralls]

Coverage increased (+0.01%) when pulling c41c807 on feature/simpler-deprecations into 751603b on master.

[coveralls]

Coverage increased (+0.01%) when pulling f2d79be on feature/simpler-deprecations into 751603b on master.

[coveralls]

Coverage increased (+0.0%) when pulling f2d79be on feature/simpler-deprecations into 751603b on master.

[coveralls]

Coverage increased (+0.42%) when pulling 1213bb6 on feature/simpler-deprecations into 751603b on master.

[mdickinson]

Our coverage numbers make no sense: how does adding a 3-line comment (between commits f2d79be and 1213bb6) increase coverage?!

[mdickinson]

Ah, the coverage change is probably related to the merge of #219.

[mdickinson]

@itziakos: Would you be interested in reviewing?

[itziakos]

👍

[corranwebster]

Should probably add a test that checks the deprecated decorator works on methods.

[corranwebster]

Are we breaking compatibility with Python >= 3.4 by using this hack?

[mdickinson]

No: it should be entirely harmless on Python >= 3.4: it clears out the __warningregistry__ dict, but on Python 3.4 the __warningregistry__ entries are effectively invalidated (but not removed) every time the warnings filterlist is touched [1], so all we're doing is removing entries from the registry that wouldn't have been used anyway.

The tests pass on Python 3.4, and we have Travis CI running on 3.4 too, so we should be pretty safe.

[1] There's a clever counter mechanism for this; see the Python issue for the details.

[mdickinson]

We could add a sys.version check here, and not execute the hack for Python >= 3.4.

Looking closely, it's not quite true to say that it's unnecessary on Python >= 3.4: it's unnecessary on Python >= 3.4.2 (released in October). It's still necessary on 3.4.0 or 3.4.1, so it would be better not to execute the hack for Python >= 3.5. And Python 3.5 doesn't even exist yet.

All in all, I think I'd rather just leave this as it is. :-)

[corranwebster]

Other than the couple of comments above, looks good to me.

[mdickinson]

Agreed that there should be a test for methods. I'll add one.

[mdickinson]

Added a separate test module for deprecated that tests both functions and methods.

(Note that we now have two test modules: one contains tests for deprecated, assuming that assertDeprecated is sane, while the other contains tests for assertDeprecated that assume that deprecated is sane.)

[mdickinson]

Whoops; missing a unittest2 import for Python 2.6. Will fix.

[coveralls]

Coverage increased (+0.42%) when pulling 32c9c71 on feature/simpler-deprecations into 751603b on master.

[coveralls]

Coverage increased (+0.43%) when pulling 26188f9 on feature/simpler-deprecations into 751603b on master.

[mdickinson]

As @corranwebster pointed out, this also needs a changelog entry before it can be merged.

[corranwebster]

LGTM - assuming Travis is happy with it.

[mdickinson]

@corranwebster, @itziakos: Thanks for reviewing! Merging.

[coveralls]

Coverage increased (+0.43%) when pulling 5100da9 on feature/simpler-deprecations into 751603b on master.