Opened 6 years ago

Last modified 6 years ago

#7147 enhancement new

It isn't clear how to deprecate a class.

Reported by: Tom Prince Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Branch:
Author:

Description

#6044 used warnings.warn by hand to deprecate twisted.internet.defer.waitForDefered by reporting a warning in __init__. twisted.python.deprecate.deprecated doesn't work, since that would include __init__ in the name being deprecated.

Change History (2)

comment:1 Changed 6 years ago by Jean-Paul Calderone

Summary: It isn't clear how to deprecate test.It isn't clear how to deprecate a class.

I think the words in the ticket summary are wrong and the ticket description doesn't *quite* make it clear what the issue is here.

My guess is that this is about deprecating a whole class and that the issue is that:

class Foo:
    @deprecated(...)
    def __init__(self):
        pass

does not produce wholly desirable results.

If this is the case, then I suggest the answer is:

class Foo:
    ...

deprecatedModuleAttribute(version, "replacement recommendation", __name__, "Foo")

Very likely deprecatedModuleAttribute is preferable to deprecated in most other cases as well since it will trigger a deprecation warning if the name is even accessed rather than requiring it actually be called. This is likely to produce the warning more reliably (though still not 100%) in a code base with less than perfect test coverage.

So presumably some documentation about the deprecation process should be updated to include this information.

Editing the ticket summary to reflect this interpretation, if it is incorrect please make some further edits.

comment:2 Changed 6 years ago by Jean-Paul Calderone

Keywords: documentation added
Note: See TracTickets for help on using tickets.