This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl
Date 2011-11-12.06:08:40
SpamBayes Score 3.936362e-06
Marked as misclassified No
Message-id <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
In-reply-to
Content
AFAIU the conventions for optional argument in the doc are as follow:

If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example:
  str.splitlines(keepends=False)

If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead.  This should apply only to some C functions, for example:
  str.strip([chars])

The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted.

These rules apply to both Python 2 and Python 3.

A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function.
History
Date User Action Args
2011-11-12 06:08:41ezio.melottisetrecipients: + ezio.melotti, georg.brandl, eric.araujo, eli.bendersky, docs@python
2011-11-12 06:08:41ezio.melottisetmessageid: <1321078121.18.0.541430257552.issue13386@psf.upfronthosting.co.za>
2011-11-12 06:08:40ezio.melottilinkissue13386 messages
2011-11-12 06:08:40ezio.melotticreate