[Twisted-Python] How to handle arguments with undocumented types and argument deprecation

Glyph Lefkowitz glyph at twistedmatrix.com
Sun Oct 25 20:30:57 MDT 2015


> On Oct 25, 2015, at 1:34 AM, Adi Roiban <adi at roiban.ro> wrote:
> 
> Is there a way to deprecate a single argument from a method/function?


Sometimes.

The idea with a deprecation is that you can remove something, emit a warning if it's used, then eventually remove it entirely, and get an error if it's used.  The trick with deprecating parameters is what happens when you get to "remove it entirely".

One of the features I'm looking forward to in Py3 is "keyword-only parameters".  If we had those then deprecating a parameter (as long as it's not part of a formal interface) would be easier.  As it is, there's a problem where you can have a function like this:

def foo(a, broken=None, c=None):
    ...

If you want to deprecate "broken", you have to ensure that callers who call 'foo' will get a deprecation warning if they pass 'broken' at all, to ensure that callers who do, for example:

foo(a, None, "something valid")

get a deprecation warning during the deprecation period.  Further, after the deprecation period, you need to get an error if you "pass broken", which doesn't exist any more.  Of course if you've removed it from the function signature, it will give you an error to pass it by keyword, but if you pass it positionally:

foo(a, "something valid for broken")

if you've skipped the deprecation period, the spirit of the policy is that you should get an exception here.  Normally this happens as a natural effect of the removal.  But in this case, if you've changed the signature of 'foo' to be

def foo(a, c=None):
    ...

then you have a problem where code that skips the deprecation period might appear to work and break in unpredictable ways later.  So when deprecating a parameter you have to be more careful than when deprecating a whole method or class.

Except, oops: addCookie() is part of a formal interface, IRequest.  Which means that if external users of Twisted are implementing IRequest, then they may keep accepting / requiring max_age in its old format.

So specifically in the case of max_age, I think we should just retrofit the code to handle str/int/long on py3, to reduce breakage.  At some point, we know we need a new, better IRequest, and we should ensure maxAge is better-specified on that interface.

-glyph


-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20151025/b14c0ca8/attachment-0002.html>


More information about the Twisted-Python mailing list