Martin Panter added the comment:
When a parameter is optional but does not have a simple default value, I
suggest using some obviously invalid pseudocode, such as
function(arg1, arg2=automatic, see text)
See Issue 8706 about adding more support for keyword arguments. See also Issue
23738 for
Raymond Hettinger added the comment:
Please don't add a new notation that makes the docs less readable than they are
now. For the most part, the existing docs have done a great job communicating
how to use our functions. Please don't undo 20 years of tradition because it
bugs you.
Changes by Ezio Melotti ezio.melo...@gmail.com:
--
nosy: +chris.jerdonek
type: - enhancement
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
___
Changes by Eli Bendersky eli...@gmail.com:
--
nosy: -eli.bendersky
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
___
___
Python-bugs-list
Ezio Melotti ezio.melo...@gmail.com added the comment:
From Ezio's original post: '''
If a function has optional arguments but it doesn't accept keyword
arguments, the func([arg1]) notation is used instead. ... The
notation func([arg=default]) should never be used, and func([arg])
should
Eric V. Smith e...@trueblade.com added the comment:
I just ran across the other reason that having the actual default values
documented is important. Sometimes I want to do this:
some_func(param if some_condition else use the default value)
If some_condition is False, I want the default
Eli Bendersky eli...@gmail.com added the comment:
Eric,
Spot on :-)
This is *exactly* the reason that led me to open issue 12875, which eventually
led to this one.
--
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
Terry J. Reedy tjre...@udel.edu added the comment:
From Ezio's original post: '''
If a function has optional arguments but it doesn't accept keyword arguments,
the func([arg1]) notation is used instead. ... The notation
func([arg=default]) should never be used, and func([arg]) should be used
Baptiste Carvello de...@baptiste-carvello.net added the comment:
Le 18/11/2011 05:29, Terry J. Reedy a écrit :
In the following, I give objections to this PO (position only) rule and
suggest an alternative ND (no default) rule: use 'name=default' when there is
a default and '[name]' when
Baptiste Carvello de...@baptiste-carvello.net added the comment:
Le 14/11/2011 20:51, Eric Snow a écrit :
So would it be worth the effort to identify each such place in the
built-ins/stdlib and eventually change them all? I've seen support for doing
so in other tracker issues and think
Éric Araujo mer...@netwok.org added the comment:
C functions that have optional arguments but don't accept keyword arguments
are a bit unusual,
and IIUC in most of the cases that's an implementation detail that could be
removed.
So would it be worth the effort to identify each such place
Ezio Melotti ezio.melo...@gmail.com added the comment:
Me too. (Can you give the #ids of these other issues?)
See for example #13012.
I think we should fix C functions to accept kwargs for the sake of
Python programmers, not merely to ease documentation (that would just
be a nice
Éric Araujo mer...@netwok.org added the comment:
I think we should fix C functions to accept kwargs for the sake of Python
programmers
And also for compatibility for other implementations like PyPy.
Good point.
I'm still not sure that is a good idea to do a mass conversion of all the
Eric Snow ericsnowcurren...@gmail.com added the comment:
Me too. (Can you give the #ids of these other issues?)
#13012 is the one that I was thinking of (msg144328 specifically). However,
I'm sure there was one more recently (which I can't find now).
--
Eric Snow ericsnowcurren...@gmail.com added the comment:
@msg147671
+1
--
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
___
___
Changes by Petri Lehtinen pe...@digip.org:
--
nosy: +petri.lehtinen
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
___
___
Python-bugs-list
Changes by Terry J. Reedy tjre...@udel.edu:
--
nosy: +terry.reedy
___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue13386
___
___
Python-bugs-list
Baptiste Carvello de...@baptiste-carvello.net added the comment:
Hi all, here is a relevant user story. I'm afraid it won't help you much, but
it highlights the importance of consistent conventions in doc.
My girlfriend is learning Python with no prior programing experience. She quite
Ezio Melotti ezio.melo...@gmail.com added the comment:
Thanks for the feedback!
1) she naturally understood the meaning of the [opt] notation
I guess this depends on her background, I've seen people trying to use [] in
function calls because they saw them in the doc or confusing them for
Éric Araujo mer...@netwok.org added the comment:
Do we need an introductory page aimed to the readers that explains
the conventions used in the doc?
Explaining notational conventions at the start of a technical reference sounds
like a best practice to me.
--
Baptiste Carvello de...@baptiste-carvello.net added the comment:
Le 14/11/2011 13:40, Ezio Melotti a écrit :
1) she naturally understood the meaning of the [opt] notation
I guess this depends on her background, I've seen people trying to use [] in
function calls because they saw them in
Eric Snow ericsnowcurren...@gmail.com added the comment:
4) she got annoyed that two completely different notations where used
for two very close concepts
This is a good point, and we are trying to move to the arg=default
notation. Unfortunately there are still places that use the old
Eli Bendersky eli...@gmail.com added the comment:
So would it be worth the effort to identify each such place in the
built-ins/stdlib and eventually change them all? I've seen support for doing
so in other tracker issues and think it's a good idea personally.
Probably, if this will bring
Eli Bendersky eli...@gmail.com added the comment:
Ezio, regarding your latest message:
The problem is when the default placeholder is some unique object() or some
_internal value (we had something similar with a socket timeout once).
I hope this should be rare enough not to present a
Ezio Melotti ezio.melo...@gmail.com added the comment:
You should also explicitly specify what happens in several optional but
not keyword args are needed. AFAIU the convention is:
func(arg1, arg2[, opt1, opt2])
IIUC that would mean that either you pass only arg1 and arg2, or you also
Eli Bendersky eli...@gmail.com added the comment:
What you say makes sense, now I just have to dig up where I saw instances of [,
opt1, opt2]
If anything, this is another proof that such conventions must be agreed upon
and meticulously documented.
--
Eric V. Smith e...@trueblade.com added the comment:
To your last point, I think it's important to specify the default value
placeholder (basically a sentinel) in the documentation. For example, if a
function takes -1 to mean all occurrences, then the caller needs to know how
what value to
Ezio Melotti ezio.melo...@gmail.com added the comment:
The problem is when the default placeholder is some unique object() or some
_internal value (we had something similar with a socket timeout once).
Also for something like str.strip(), would you document chars=None or chars=
\n\r\t\v\f?
Eli Bendersky eli...@gmail.com added the comment:
You should also explicitly specify what happens in several optional but not
keyword args are needed. AFAIU the convention is:
func(arg1, arg2[, opt1, opt2])
--
___
Python tracker
New submission from Ezio Melotti ezio.melo...@gmail.com:
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
30 matches
Mail list logo
