[docs] [issue23738] Clarify documentation of positional-only default values

[Martin Panter]

New submission from Martin Panter:

This patch adds the PEP 457 positional-only slash “/” indicator to some function signatures in the documentation. I only looked at the the os, builtin, binascii, zlib and fcntl modules, and their functions where the documentation incorrectly suggests that they accept keyword arguments. For example, I changed

eval(expression, globals=None, locals=None)

to

eval(expression, globals=None, locals=None, /)

References:

* Issue 22832: “fcntl” module changed to look like accepting keyword arguments
* Ongoing discussion: <https://mail.python.org/pipermail/python-dev/2015-March/138847.html>

There are many more instances where square brackets are used, or the arguments are mandatory. See the PEP for examples, but I do not think it is so important to “fix” them.

I also fixed parameter name mismatches that I discovered for a quite a few functions that do take keyword arguments.

One more thing I noticed, that I do not know how to fix, is the Argument Clinic signatures list invalid default values for zlib.compressobj(zdict=None) and os.utime(ns=None):

>>> zlib.compressobj(zdict=None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'NoneType' does not support the buffer interface
>>> os.utime("dummy", ns=None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: utime: 'ns' must be a tuple of two ints

----------
assignee: docs at python
components: Documentation
files: pos-defaults.patch
keywords: patch
messages: 238890
nosy: docs at python, serhiy.storchaka, vadmium
priority: normal
severity: normal
status: open
title: Clarify documentation of positional-only default values
versions: Python 3.4, Python 3.5
Added file: http://bugs.python.org/file38632/pos-defaults.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue23738>
_______________________________________