[Python-ideas] Boolean parameters guidelines

[Chris Angelico]

On Thu, May 12, 2016 at 7:57 AM, Ethan Furman <ethan at stoneleaf.us> wrote:
> On 05/11/2016 02:40 PM, Zachary Ware wrote:
>>
>> On Wed, May 11, 2016 at 3:36 PM, Ian Kelly wrote:
>>>
>>> On Wed, May 11, 2016 at 12:51 PM, Mark Dickinson wrote:
>>>>
>>>> On Wed, May 11, 2016 at 5:10 PM, Sven R. Kunze  wrote:
>
>
>>>>> Additionally, it seems like this could be said for other primitive
>>>>> datatypes
>>>>> as well:
>>>>>
>>>>> --> sleep(100)  # minutes?
>>>>
>>>>
>>>> Don't be silly. Why on earth would that argument represent minutes?
>>>>
>>>> It's days, for consistency with `timedelta(100)`.
>>>
>>>
>>> Still best to be explicit:
>>>
>>> --> sleep(timedelta(100))
>>>
>>> It would be awesome if that actually worked.
>>
>>
>> You just weren't explicit enough:
>>
>>     --> sleep(timedelta(100).total_seconds())
>>
>> This is drifting pretty far from the topic at hand, though.
>
>
> There was a topic at hand?
>
> Oh, yeah, keyword arguments!
>
> Actually, it's very apropos:  each of those examples would have been either
> obviously correct or obviously wrong if the parameter names had been used.

Unfortunately it isn't always possible.

rosuav at sikorsky:~$ PAGER=cat python3
Python 3.6.0a0 (default:98678738b7e9, May  2 2016, 13:37:04)
[GCC 5.3.1 20160409] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from time import sleep
>>> help(sleep)
Help on built-in function sleep in module time:

sleep(...)
    sleep(seconds)

    Delay execution for a given number of seconds.  The argument may be
    a floating point number for subsecond precision.

>>> sleep(seconds=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: sleep() takes no keyword arguments


So style guides can't really recommend "always use keyword arguments",
as there are too many functions implemented in C that don't take any
keyword args. They're effectively implemented as:

def sleep(*args):
    [seconds] = args

This particular example might be worth using a keyword arg with,
except that the confusion isn't within Python, it's across languages.
And then there's the parallel question of whether or not fractional
seconds are valid. A quick survey of sleep functions shows up:

* C on POSIX: integer seconds (usleep and nanosleep for integer
micro/nanoseconds)
* C on Windows: integer milliseconds
* Pike and Python: int or float seconds
* REXX on OS/2: integer seconds [syssleep], milliseconds [rxsleep], or
decimal seconds

So if you're doing cross-language work, you'll need to check your docs
anyway, and if you're not, it shouldn't be too hard to remember that
sleep() in Python takes a number of seconds. (It's easy if you give it
a non-integer value. You might see sleep(1000) and interpret that as
milliseconds, but you would never see sleep(0.5) and mistake it for
anything other than half a second.)

ChrisA