[Python-checkins] [Python-Dev] cpython: Fix closes Issue11281 - smtplib.STMP gets source_address parameter, which adds

[Michael Foord]

On 31 Jul 2011, at 02:26, Senthil Kumaran wrote:
> On Sat, Jul 30, 2011 at 11:11:08PM +0300, Ezio Melotti wrote:
>>> -.. class:: SMTP(host='', port=0, local_hostname=None[, timeout])
>>> +.. class:: SMTP(host='', port=0, local_hostname=None[, timeout], source_address=None)
>> 
>> The "[, timeout]" now looks weird there, and it would be better to
>> convert it to ", timeout=..." to match the other args.
>> However I don't know what the value should be, since the real value
>> is socket._GLOBAL_DEFAULT_TIMEOUT (i.e. object()) and I don't think
>> it's a good idea to expose that.  Maybe "None" can be used instead?
> 
> I found that [, timeout] bit odd too. But is not mentioning that as
> timeout=None when it is timeout=socket._GLOBAL_DEFAULT_TIME
> technically inaccurate?
> 

It does mean that users will expect to be able to call with an explicit timeout=None and get the default behaviour. Just use the numeric value of the global timeout perhaps?

MIchael Foord

> FWIW, I see similar style (...,[,timeout], kw=val) adopted elsewhere
> in the library docs too.  urllib, httplib, nntplib etc. Though it does
> not look okay, it is better than giving inaccurate information.
> 
> While ftplib and poplib, has them as timeout=None, while they default
> to socket._GLOBAL_DEFAULT_TIMEOUT object.
> 
> If we decide upon something, it can be made consistent. So, the
> question is, when the timeout argument refers to
> socket._GLOBAL_DEFAULT_TIME, how should we write the docs.
> 
> 1. def somesocketmethod(arg1,arg2, timeout=socket._GLOBAL_DEFAULT_TIMEOUT, ...)
> 
> - I don't see anything is wrong with this.
> 
> 2. def somesocketmethod(arg1,arg2, timeout=None, ...)
> 
> - And explain that it actually points to a socket default timeout
> object, which is odd and can lead to user errors.
> 
> 3. def somesocketmethod(arg1,arg2[,timeout], kwarg=value)
> 
> - That's how it is currently explained at some places. If this style
>  is okay, we can change the places were it refers to None  to be
>  above.
> 
> Thanks for your review comments, I have address the remaining ones.




--
http://www.voidspace.org.uk/


May you do good and not evil
May you find forgiveness for yourself and forgive others
May you share freely, never taking more than you give.
-- the sqlite blessing 
http://www.sqlite.org/different.html