Pablo Galindo Salgado <pablog...@gmail.com> added the comment:
Thank you, Raymond, for sharing your concerns regarding this. I am sorry you
disagree with this change.
I would want to expose the reasons I think this is important and justified, but
please, don't read this
as a way of dismissing your concerns; I really respect your opinion and
judgment (as an example, I am waiting
until you are happy with the API in issue17005 even if that meant waiting 2
years until the next release).
1) The docstrings for these functions already show the "/". As Matthias
Bussonnier from IPython and Jupyter has expressed
multiple times, there are a ton of users that do not read html documentation
and rely solely on the output from help (either
in Jupyter, IPython or CPython). These users find very strange that the
signatures of the docstrings differ when they actually
check the html docs. Some examples of the docstrings:
>>> help(zlib.decompress)
decompress(data, /, wbits=15, bufsize=16384)
Returns a bytes object containing the uncompressed data.
>> help(codecs.register)
register(search_function, /)
Register a codec search function.
2) This communicates the users more explicitly how to call the function and
what to expect when this happens,
which is the purpose of documenting signatures in the documentation. We are
already documenting keyword-only
parameters for the same reasons.
3) This PR is not changing any of the signatures, is just documenting and
informing users what the signature is
and how it will behave. Is just expressing information. The documentation must
be user-friendly, but also needs to
be technical.
4) We are already documenting positional-only arguments in multiple other
functions in the documentation. This PR just
continues doing that. Some examples of the many cases:
https://docs.python.org/3.8/library/functools.html#functools.partialmethod
https://docs.python.org/3.8/library/threading.html#threading.excepthook
https://docs.python.org/3.8/library/inspect.html#inspect.getcallargs
...
5) I give training sessions to different levels (people that are starting to
program, Juniors and Seniors) and they are always
confused when the signature of the function in the documentation does not match
the docstring or the actual way of calling the function.
This also includes when we use constructs like f(x, ...), f(x, [y=None,]), f(K)
-> V or similar because they are not valid Python
signatures and they do not appear elsewhere. In general, my experience is that
people want the signature documented as close as possible
to the real signature in the technical documentation.
I wished we could have iterate over this together having a good discussion
before involving the steering council, and I am sorry
if you were afraid that your concerns would have not been listened to. Sadly, I
have not answered before because it was 1:26 in the morning
here when you posted your message. I have left the PR open and opened an issue
because is the normal workflow and because this allows people
to express here their opinion.
I think this change is important, but I also think of working together and
respecting and understanding everyone's point of view
is much more important. If you think me pushing for this change will impact
somehow our ability to work together I will close the PR
and the issue.
For now, I won't do anything before the steering council decides what to do.
I apologize to everyone or the wall of text.
----------
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
