[issue23738] Clarify documentation of positional-only default values

Change by Brett Cannon : -- nosy: -brett.cannon ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail

[issue23738] Clarify documentation of positional-only default values

Ezio Melotti added the comment: One thought that occurred to me is that we could make the * and / in the signature links that point to a relevant section of the documentation. I believe this is doable with Sphinx, even though I'm not sure how complex it is and if it's worth it. If we do this,

[issue23738] Clarify documentation of positional-only default values

Martin Panter added the comment: Here is a more conservative patch using square brackets, and documenting the defaults in the text. I updated all the documentation from my previous patch, and added new changes for the “io” module. One quirk was that BufferedReader.read1() does not actually sup

[issue23738] Clarify documentation of positional-only default values

Changes by Martin Panter : -- dependencies: +Python 3 documentation for eval is incorrect ___ Python tracker ___ ___ Python-bugs-list

[issue23738] Clarify documentation of positional-only default values

Changes by Martin Panter : -- dependencies: +TypeError: truncate() takes no keyword arguments ___ Python tracker ___ ___ Python-bugs-l

[issue23738] Clarify documentation of positional-only default values

Martin Panter added the comment: I have committed the obvious keyword argument name fixes from my patch. Now patch v3 contains just the PEP 457 changes to be considered. -- ___ Python tracker _

[issue23738] Clarify documentation of positional-only default values

Roundup Robot added the comment: New changeset fdb5d84f9948 by Martin Panter in branch '3.4': Issue #23738: Document and test actual keyword parameter names https://hg.python.org/cpython/rev/fdb5d84f9948 New changeset 40bf1ca3f715 by Martin Panter in branch '3.5': Issue #23738: Merge 3.4 into

[issue23738] Clarify documentation of positional-only default values

Changes by Martin Panter : -- nosy: +berker.peksag versions: +Python 3.6 Added file: http://bugs.python.org/file40417/pos-defaults.v3.patch ___ Python tracker ___ ___

[issue23738] Clarify documentation of positional-only default values

Changes by Martin Panter : -- dependencies: +io.[Text]IOBase.seek doesn't take keyword parameter ___ Python tracker ___ ___ Python-bug

[issue23738] Clarify documentation of positional-only default values

Martin Panter added the comment: Of course in a new release, the functions could actually grow support for keywords, sidestepping the problem. Issue 8706 proposes to do this. And see Issue 13386 about the conventions for optional arguments more generally. -- __

[issue23738] Clarify documentation of positional-only default values

Martin Panter added the comment: pos-defaults.v2.patch includes the results of “make clinic” to fix the doc strings. Is there a consensus to use PEP 457’s slash “/” notation? At one point I think I saw Serhiy was concerned that it might be confusing. -- Added file: http://bugs.python.

[issue23738] Clarify documentation of positional-only default values

R. David Murray added the comment: That's a good point. -- ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http

[issue23738] Clarify documentation of positional-only default values

Brett Cannon added the comment: I say switch to what Argument Clinic uses, else there's a disconnect syntactically between help() and the docs. -- ___ Python tracker ___ ___

[issue23738] Clarify documentation of positional-only default values

R. David Murray added the comment: Personally I would rather stick to the [] syntax in the docs, with the default values mentioned in the text. -- nosy: +georg.brandl, r.david.murray ___ Python tracker ___

[issue23738] Clarify documentation of positional-only default values

Changes by Brett Cannon : -- nosy: +brett.cannon ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.p

[issue23738] Clarify documentation of positional-only default values

Changes by Ezio Melotti : -- nosy: +ezio.melotti stage: -> patch review type: -> enhancement ___ Python tracker ___ ___ Python-bugs-

[issue23738] Clarify documentation of positional-only default values

Serhiy Storchaka added the comment: ./python Tools/clinic/clinic.py --make or just make clinic -- ___ Python tracker ___ ___ Pyt

[issue23738] Clarify documentation of positional-only default values

Martin Panter added the comment: Hmm it seems my change for os.utimes() in Modules/posixmodule.c does not automatically get reflected in the doc string. Is there some script I can run to regenerate it, or do I have to do it manually? -- ___ Python t

[issue23738] Clarify documentation of positional-only default values

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 the