[Twisted-Python] Deprecating classes and writing tests

[Adi Roiban]

On 13 June 2016 at 22:46, Glyph <glyph at twistedmatrix.com> wrote:

>
> On Jun 13, 2016, at 4:26 AM, Adi Roiban <adi at roiban.ro> wrote:
>
> Hi,
>
> What is the best practice for deprecating a class in Twisted and writing
> tests for it ... and updating existing tests.
>
>
> We appear to have 'assertDeprecated' type methods scattered around the
> codebase.  These should be refactored into a single location.
>
> I think that the part in which the deprecation code is written, is well
> understood and documented here
>
>
> http://twistedmatrix.com/documents/current/core/development/policy/compatibility-policy.html#classes
>
> What is missing, is the part talking about how to test these changes and
> how to update existing tests.
>
>
> The thing that ends up being deprecated with the recommended technique
> here is the import of the class itself. So I think what's missing is the
> explanation that the import needs to be moved to test scope, not module
> scope within the tests.  The tests should also be separated out and dated
> so it's clear what to delete when the deprecation period expires, and
> removals are easy.
>
> Does that answer your question sufficiently?
>
>
I have created https://twistedmatrix.com/trac/ticket/8478 and I have pushed
a branch to document testing deprecated module attributes.

Doing test scope import will work, but I am thinking of a different method.

Instead of importing/using the deprecated code as

# Import raises the warning
from twisted.cred.credentials import UsernameHashedPassword
# Usage will not raise the warning.
UsernameHashedPassword

it can be imported and used in this way

# Import will not raise the warning
from twisted.cred import credentials
# Usage will raise the warning
credentials.UsernameHashedPassword

I feel that the second approach is easier to integrated with
self.callDeprecated

If you have time, please review https://twistedmatrix.com/trac/ticket/8478

Thanks!
-- 
Adi Roiban
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20160616/8b380419/attachment-0002.html>