Re: The slash "/" as used in the documentation

[Chris Angelico]

On Wed, Feb 13, 2019 at 6:18 AM Peter J. Holzer  wrote:
>
> On 2019-02-12 07:31:54 +1100, Chris Angelico wrote:
> > Positional arguments with defaults is a concept known in MANY
> > languages,
>
> True.
>
> > including C.
>
> Nope. At least not until C99, and I can't find anything in C11 either.
> Maybe they'll add it in C2x.
>

Huh, my bad. C++ has it, but C still doesn't. Anyhow, defaults on
function arguments are supported in WAY more languages than keyword
arguments are.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Peter J. Holzer]

On 2019-02-12 07:31:54 +1100, Chris Angelico wrote:
> Positional arguments with defaults is a concept known in MANY
> languages,

True.

> including C.

Nope. At least not until C99, and I can't find anything in C11 either. 
Maybe they'll add it in C2x.

hp

-- 
   _  | Peter J. Holzer| we build much bigger, better disasters now
|_|_) || because we have much more sophisticated
| |   | h...@hjp.at | management tools.
__/   | http://www.hjp.at/ | -- Ross Anderson 


signature.asc
Description: PGP signature
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Tue, Feb 12, 2019 at 8:13 AM Avi Gross  wrote:
>
>
> Just Chris,

Can we keep things on the list please?

> I am thinking I missed the point of this discussion thus what I say makes no
> sense.

Not sure. You were fairly specific with your statements about how
things supposedly were in the past. What point of the discussion did
you miss that led you to say that?

> Yes, the equals is THE way you supply defaults for things you optionally
> want the user to be able to override. I seem to be talking top-level python
> and you guys are elsewhere so I must be in another discussion.
>
> On Tue, Feb 12, 2019 at 7:26 AM Avi Gross  wrote:
> > If you want to talk about recent or planned changes, fine. But make
> > that clear. I was talking about how in the past positional arguments
> > did not have defaults available at the def statement level. I was
> > talking about how use of the symbol "=" in the context of defining
> > function parameters had multiple meanings. It not only established
> > that the parameter accepted a keyword but also provided a default.

You state this as fact. That's what I responded to. What do you mean
by "top level Python" that might make your statement true?

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Mon, Feb 11, 2019 at 1:56 PM boB Stepp  wrote:
>
> On Mon, Feb 11, 2019 at 2:34 PM Chris Angelico  wrote:
>
> > Calling on the D'Aprano Collection of Ancient Pythons for confirmation
> > here, but I strongly suspect that positional arguments with defaults
> > go back all the way to 1.x.
>
> Has Steve's banishment ended yet?  The only postings I have recently
> seen from him have been on the Tutor list.

It should have ended some time in December. Perhaps he's decided not to return.
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[boB Stepp]

On Mon, Feb 11, 2019 at 2:34 PM Chris Angelico  wrote:

> Calling on the D'Aprano Collection of Ancient Pythons for confirmation
> here, but I strongly suspect that positional arguments with defaults
> go back all the way to 1.x.

Has Steve's banishment ended yet?  The only postings I have recently
seen from him have been on the Tutor list.



-- 
boB
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Mon, Feb 11, 2019 at 1:35 PM Chris Angelico  wrote:
>
> On Tue, Feb 12, 2019 at 7:26 AM Avi Gross  wrote:
> > If you want to talk about recent or planned changes, fine. But make that
> > clear. I was talking about how in the past positional arguments did not have
> > defaults available at the def statement level. I was talking about how use
> > of the symbol "=" in the context of defining function parameters had
> > multiple meanings. It not only established that the parameter accepted a
> > keyword but also provided a default.
>
> When was this the case? Positional arguments with defaults is a
> concept known in MANY languages, including C. The equals sign has
> nothing to do with keyword arguments.
>
> Calling on the D'Aprano Collection of Ancient Pythons for confirmation
> here, but I strongly suspect that positional arguments with defaults
> go back all the way to 1.x.

The archived documentation shows that both parameter defaults and
keyword arguments have been around since at least 1.4. I can't
directly confirm that required parameters could be passed by keyword,
but I see nothing in there that says they can't, or that appears to
conflate parameters having defaults with keyword arguments, which is
as one would expect -- whether an argument is passed positionally or
by keyword is a property of the function *call* expression, whereas
whether a parameter has a default or not is a property of the function
*definition*. They happen to both use the = symbol followed by an
expression, but in different syntactical environments, and that is the
only correlation between them.
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Tue, Feb 12, 2019 at 7:26 AM Avi Gross  wrote:
> If you want to talk about recent or planned changes, fine. But make that
> clear. I was talking about how in the past positional arguments did not have
> defaults available at the def statement level. I was talking about how use
> of the symbol "=" in the context of defining function parameters had
> multiple meanings. It not only established that the parameter accepted a
> keyword but also provided a default.

When was this the case? Positional arguments with defaults is a
concept known in MANY languages, including C. The equals sign has
nothing to do with keyword arguments.

Calling on the D'Aprano Collection of Ancient Pythons for confirmation
here, but I strongly suspect that positional arguments with defaults
go back all the way to 1.x.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

RE: The slash "/" as used in the documentation

[Avi Gross]

Ian,

Again, not having read whatever documentation we may be discussing, I may be
very wrong.

The topic is the C API. I started using C at Bell Laboratories in 1982
replacing other languages I had used before. I haven't felt a reason to use
it in the last few decades as I moved on to yet other languages but am quite
aware that many of those languages are largely interpreters written in
languages like C or C++ and then regularly patched by adding C-like code to
replace slower functionality. I assume the C API you are mentioning refers
to the process of how you write and compile and invoke library functions so
that the function called will properly place python data structures in some
kind of stack so that the C library can properly take it and perform
computations. Similarly, when the function returns, some additional mapping
may be done. The above is meant to be general and obviously the details
matter.

C as a stand-alone language used to have pretty much positional arguments
and often a fixed number of them. We often had multiple functions we could
call with slightly different names if we wanted special effects like not
requiring a third argument. Clearly some approaches were less efficient if
the two-argument version simply turned around and called the three-argument
version with a third argument set to a default. So, often you played other
games like requiring a third argument (or in some languages a dangling
comma) which the function might choose to replace with a default internally
if it is something like -1. Obviously C libraries that are external must be
used as-is while internal ones you have written might allow changes.

Some languages I have used do not so much support doing lots of command-line
level pre-processing of command-line arguments but provide helper functions
that can be called within the function call that take all the arguments and
do further processing and return a form that the function can more easily
use. This works even better when evaluation is lazy and you can access the
exact original text the programmer or user typed in before it is evaluated.
Python now allows a limited form of that if you ask for *args and **kwargs.

So is this mainly about efficiency and C libraries or more? You can easily
make a C function that expects positional arguments in a proper order and
then make a wrapper in python (or C or FORTRAN or whatever) with a slightly
different name that does preprocessing and/or postprocessing. Python is
loaded with such functionality that tends to allow more complex things to be
done less efficiently. So if the wrapper can evaluate your arguments and
figure out what to do with positional arguments, great. The wrapper function
might support an optional argument that specifies whether other argument
units are in feet, miles, meters or even parsecs and also accept keyword
arguments for those measures and rescale them and only then call the
efficient C function with all the right arguments in the right positions. If
you as a programmer find that slows things down, you can make sure you use
the right units for the function and call the underlying function directly
with everything in place according to those rules.

Ending with this. Is the reality that we are now talking about gradual
changes in documentation as individual C functions are updated but not at
this point about what normal python users are seeing in terms of the code?
If so, I repeat, I was not talking about that and my comments are not
applicable and I can go back to doing more useful things away from this
forum.

-Original Message-
From: Python-list  On
Behalf Of Ian Kelly
Sent: Monday, February 11, 2019 1:46 AM
To: Python 
Subject: Re: The slash "/" as used in the documentation

On Sun, Feb 10, 2019 at 2:18 PM Avi Gross  wrote:
> I am not sure how python implements some of the functionality it does 
> as compared to other languages with similar features. But I note that 
> there are rules, presumably some for efficiency, such as requiring all 
> keyword arguments to be placed after the last positional argument. I 
> mean I can call
> func(a,b,c,d=1,e=2) but not func(a,b,d=1, c, e=2).
>
> So if you allowed a keyword to optionally be used for any positional 
> argument other than the last, c, would it not require a change in this
rule?
> I mean func(a="invalid",b,c,d=1,e=2) would violate the rule and so 
> would making b a keyword version. In my example, and for this reason 
> only, maybe c could work.

My suggestion was not to allow keyword arguments to arbitrarily replace any
positional parameter, or to otherwise change argument-passing in any way.
The suggestion was to drop positional-only arguments from functions
implemented in C instead of just documenting them better. In the example
above, if you want to pass a by keyword, you would have to pass b and c by
keyword as well.
That would still be true for functions implemented in C if a,

RE: The slash "/" as used in the documentation

[Avi Gross]

Ian,

I now assume we are no longer talking about the past or even the present but
some planned future. In that future we are talking about how to define a
function with added or changed functionality. So nothing I wrote earlier
really applies because I was talking of how things did work in the absence
of the changes needed to make new functionality possible.

So let me make sure I understood you. We are talking about the function
prototype as in def fun(...) and perhaps the lambda equivalent. The user of
the function would only see changes in the help files or other documentation
but no special symbols would be used when they invoke a function, albeit new
error messages may also happen if done wrong.

The earlier messages talked about using a forward slash but you seem to use
an asterisk for the same purpose. You can use the very overloaded "*"
character as a delimiter between the parameters mentioned to the left and
any remaining ones to the right. The "=" symbol is thus now allowed on
either side of the divide and now ONLY means there is a default. 

I thought the discussion was about python, not the C API that arguably is
used as much of python is in C directly or indirectly. I thought we were
talking about updating everything at the top interpreted python levels.
Please make it clear if we are not.

Will the above functionality, if understood, break (or modify how it works)
existing python code? I mean code that only uses the asterisk to denote
multiplication, exponentiation, list expansion and dictionary expansion and
so on. 

Just based on what you wrote, maybe not. It depends on the new meaning of
not having a sole asterisk somewhere in the parameter list. If that means
evaluate old style, great. If it means something else, I won't speculate but
can picture problems.

I will talk about your C API question in another message.


-Original Message-
From: Python-list  On
Behalf Of Ian Kelly
Sent: Monday, February 11, 2019 1:46 AM
To: Python 
Subject: Re: The slash "/" as used in the documentation

On Sun, Feb 10, 2019 at 2:18 PM Avi Gross  wrote:
> I am not sure how python implements some of the functionality it does 
> as compared to other languages with similar features. But I note that 
> there are rules, presumably some for efficiency, such as requiring all 
> keyword arguments to be placed after the last positional argument. I 
> mean I can call
> func(a,b,c,d=1,e=2) but not func(a,b,d=1, c, e=2).
>
> So if you allowed a keyword to optionally be used for any positional 
> argument other than the last, c, would it not require a change in this
rule?
> I mean func(a="invalid",b,c,d=1,e=2) would violate the rule and so 
> would making b a keyword version. In my example, and for this reason 
> only, maybe c could work.

My suggestion was not to allow keyword arguments to arbitrarily replace any
positional parameter, or to otherwise change argument-passing in any way.
The suggestion was to drop positional-only arguments from functions
implemented in C instead of just documenting them better. In the example
above, if you want to pass a by keyword, you would have to pass b and c by
keyword as well.
That would still be true for functions implemented in C if a, b, and c are
no longer positional-only.

> The original motivation for keyword arguments included the concept of 
> specifying a default if not used. Positional arguments have no default.
> Similarly, they are required if explicitly named in the function
definition.
> So we are intermingling multiple concepts in the previous design.

Positional arguments are allowed to have defaults, and keyword-only
arguments are allowed to not have defaults. These are all valid
syntax:

# Allows a and b to be passed either positionally or by keyword def foo(a=1,
b=2): pass

# b is keyword-only
def foo(a=1, *, b=2): pass

# Allows a and b to be passed either positionally or by keyword def foo(a,
b): pass

# b is keyword-only and has no default
def foo(a, *, b): pass

Positional-ONLY arguments are not directly supported by the language, but
they exist in the C API and can also have defaults. For example, dict.get
takes two positional-only arguments. The second argument is optional, and
its default is None.

My point is that the axis of positional-only versus positional-or-keyword
versus keyword-only, and the axis of required versus optional are entirely
separate.

> I won't go on except to say it would break lots of existing code and 
> potentially complicate new code.

Can you give an example of something that would be broken by updating C API
functions to name positional-only arguments instead of just updating them to
document that they're positional-only?
--
https://mail.python.org/mailman/listinfo/python-list

-- 
https://mail.python.org/mailman/listinfo/python-list

RE: The slash "/" as used in the documentation

[Avi Gross]

Ian,

I want to make sure we are talking about the same things in the same ways. I
will thus limit my comments in this message.

If efficiency is your major consideration, then using only positional
arguments of known types you can place on the stack and optimize at compile
time may be a great way to go. It is not the way python generally goes as it
supports objects at run time that can be of any type and in many cases
allows any number of arguments to a function.

Python was designed till recently in a way that valued some more innovative
methods and that included allowing a combination of positional and keyword
arguments. The positional arguments can still be called with keyword but
only if moved beyond any other positional arguments. What evolved is NOT the
only way I have seen this done. But what I see now is not what you are
describing in some ways.

If you want to talk about recent or planned changes, fine. But make that
clear. I was talking about how in the past positional arguments did not have
defaults available at the def statement level. I was talking about how use
of the symbol "=" in the context of defining function parameters had
multiple meanings. It not only established that the parameter accepted a
keyword but also provided a default. The allowed syntax required a default,
even if it was None. I mean the following fails:

>>> def func(a,b=): pass
SyntaxError: invalid syntax

If in the future (or some other language) you want to allow some way of
assigning a default to positional arguments, fine. What I see today does
not. 

So if I understand you, there is a proposal or even plan to change some of
the current functionality. I still have not seen anyone post a reference as
requested. I am very open to seeing what people are considering or maybe
even implementing and in what ways it may not be compatible with present
functionality.



-Original Message-
From: Python-list  On
Behalf Of Ian Kelly
Sent: Monday, February 11, 2019 1:46 AM
To: Python 
Subject: Re: The slash "/" as used in the documentation

On Sun, Feb 10, 2019 at 2:18 PM Avi Gross  wrote:
> I am not sure how python implements some of the functionality it does 
> as compared to other languages with similar features. But I note that 
> there are rules, presumably some for efficiency, such as requiring all 
> keyword arguments to be placed after the last positional argument. I 
> mean I can call
> func(a,b,c,d=1,e=2) but not func(a,b,d=1, c, e=2).
>
> So if you allowed a keyword to optionally be used for any positional 
> argument other than the last, c, would it not require a change in this
rule?
> I mean func(a="invalid",b,c,d=1,e=2) would violate the rule and so 
> would making b a keyword version. In my example, and for this reason 
> only, maybe c could work.

My suggestion was not to allow keyword arguments to arbitrarily replace any
positional parameter, or to otherwise change argument-passing in any way.
The suggestion was to drop positional-only arguments from functions
implemented in C instead of just documenting them better. In the example
above, if you want to pass a by keyword, you would have to pass b and c by
keyword as well.
That would still be true for functions implemented in C if a, b, and c are
no longer positional-only.

> The original motivation for keyword arguments included the concept of 
> specifying a default if not used. Positional arguments have no default.
> Similarly, they are required if explicitly named in the function
definition.
> So we are intermingling multiple concepts in the previous design.

Positional arguments are allowed to have defaults, and keyword-only
arguments are allowed to not have defaults. These are all valid
syntax:

# Allows a and b to be passed either positionally or by keyword def foo(a=1,
b=2): pass

# b is keyword-only
def foo(a=1, *, b=2): pass

# Allows a and b to be passed either positionally or by keyword def foo(a,
b): pass

# b is keyword-only and has no default
def foo(a, *, b): pass

Positional-ONLY arguments are not directly supported by the language, but
they exist in the C API and can also have defaults. For example, dict.get
takes two positional-only arguments. The second argument is optional, and
its default is None.

My point is that the axis of positional-only versus positional-or-keyword
versus keyword-only, and the axis of required versus optional are entirely
separate.

> I won't go on except to say it would break lots of existing code and 
> potentially complicate new code.

Can you give an example of something that would be broken by updating C API
functions to name positional-only arguments instead of just updating them to
document that they're positional-only?
--
https://mail.python.org/mailman/listinfo/python-list

-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Terry Reedy]

On 2/11/2019 2:47 AM, Ian Kelly wrote:


For math.sin, sure, but what about, say, list.index?


Special-case conversion is a different issue from blanket conversion.
Some C functions have been converted to accept some or all args by 
keyword.  I don't know the status of list method conversion: discussed? 
accepted? rejected?  The people involved with conversion of documenting 
mostly don't read this list.


--
Terry Jan Reedy

--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Mon, Feb 11, 2019 at 6:51 PM Terry Reedy  wrote:
> > and not normally accessible to pure Python functions without
> > some arm twisting.
>
> In my first response on this thread I explained and demonstrated how to
> access signature strings from Python, as done by both help() and IDLE.
> Please read if you are concerned about this.  There is hardly any extra
> difficulty.  I did not discuss how to process the signature string
> returned by str(signature) nor how to access the information in
> Signature objects otherwise, but the str and Signature docs cover these.

The feature of positional-only args isn't available to pure Python
functions at the moment, other than by taking *args and then mutating
your own sig. Hence the slash is unfamiliar to people.

If we want arbitrary consistency, it might be better to work that way:
to let pure Python functions take pos-only args. I doubt it would be
of particularly great benefit, but it wouldn't hurt.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Mon, Feb 11, 2019 at 6:49 PM Ian Kelly  wrote:
>
> On Mon, Feb 11, 2019 at 12:19 AM Terry Reedy  wrote:
> > The pass-by-position limitation is not in CPython, it is the behavior of
> > C functions, which is the behavior of function calls in probably every
> > assembly and machine language.  Allowing the flexibility of Python
> > function calls take extra code and slows function calls.
> >
> > math.sin, for instance, is a fast-as-possible wrapper around the C math
> > library sin function.  It extracts the C double from the Python float,
> > calls C sin, and returns the returned C double wrapped as a Python
> > float.  Coredevs decided that being able to call math.sin(x=.3) is
> > not worth the resulting slowdown.  I am rather sure that heavy users of
> > the math module would agree.
>
> For math.sin, sure, but what about, say, list.index? Here's the start
> of the implementation:
>
> static PyObject *
> listindex(PyListObject *self, PyObject *args)
> {
> Py_ssize_t i, start=0, stop=Py_SIZE(self);
> PyObject *v;
>
> if (!PyArg_ParseTuple(args, "O|O&:index", ,
> _PyEval_SliceIndex, ,
> _PyEval_SliceIndex, ))
>
>
> This is already paying the cost of not using C-style positional
> function arguments, but then it only takes an argument tuple, so it
> can't take keyword arguments anyway. Why?

How much of a performance penalty are you willing to accept for this?
It would apply to every C-implemented function, including tiny and
common ones like 1+2, just in case someone wanted to write
int.__add__(self=1, value=2). Try to pitch this to sysadmins and app
authors: "CPython 3.8 will be 3% slower, but you can pass keyword args
to dunders now!"

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Terry Reedy]

On 2/10/2019 11:32 PM, Ian Kelly wrote:

On Sun, Feb 10, 2019 at 9:34 AM Chris Angelico  wrote:



Do you ACTUALLY want to call math.sin(x=1.234) or is it purely for the
sake of consistency? Aside from questions about the help format, what
is actually lost by the inability to pass those arguments by name?


No, but I wouldn't object to d.get(key='foo', default=12).


I don't see what dict acccess has to do with function calls.  But moving on.


It's partly
about consistency, but mostly I was reacting to Terry's comments in
that a) positional-only arguments are a "limitation"


If one thinks of Python's flexible signatures as 'normal', which they 
aren't, than positional-only seems like a limitation.  (Some other 
languages have somewhat similar flexibility.)  From a 
C/assembler/machine perspective, positional is normal.



and there is no
desire for the rest of Python to match CPython's behavior in this
instance,


For reasons of complexity and speed, without a countervailing argument, 
there is no desire to add to C-coded functions a flexibility that will 
mostly not be used.



and b) it sounds like a great deal of effort is being spent
on updating all the C function signatures one at a time


It tends to be done a module per PR.  I don't know what effort is needed 
since I have never done it.



so that the
help string can be updated to a form that is unfamiliar and not
intuitive


'*' is not 'intuitive either.  As I said elsewhere, multiple options 
were considered.  '/' was the favorite because it is 'connected' to '*' 
and more intuitive for dividing a list into two sublists.


Any, IDLE, but not help(), adds a comment to explain.
"['/' marks preceding arguments as positional only]"
The downside is that this and a following blank line add 2 lines to a 
calltip that is usually 2 lines, making it more obtrusive.  And once '/' 
is understood, the comment is extra noise.  So I am thinking of 
condensing it somehow.



and not normally accessible to pure Python functions without
some arm twisting.


In my first response on this thread I explained and demonstrated how to 
access signature strings from Python, as done by both help() and IDLE. 
Please read if you are concerned about this.  There is hardly any extra 
difficulty.  I did not discuss how to process the signature string 
returned by str(signature) nor how to access the information in 
Signature objects otherwise, but the str and Signature docs cover these.


It is possible the a sentence about '/' should be added somewhere.


If every function has to be updated anyway, why not
update them by fixing their signatures?


I proposed this once and the answer was that it would be too costly.

--
Terry Jan Reedy

--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Mon, Feb 11, 2019 at 12:19 AM Terry Reedy  wrote:
> The pass-by-position limitation is not in CPython, it is the behavior of
> C functions, which is the behavior of function calls in probably every
> assembly and machine language.  Allowing the flexibility of Python
> function calls take extra code and slows function calls.
>
> math.sin, for instance, is a fast-as-possible wrapper around the C math
> library sin function.  It extracts the C double from the Python float,
> calls C sin, and returns the returned C double wrapped as a Python
> float.  Coredevs decided that being able to call math.sin(x=.3) is
> not worth the resulting slowdown.  I am rather sure that heavy users of
> the math module would agree.

For math.sin, sure, but what about, say, list.index? Here's the start
of the implementation:

static PyObject *
listindex(PyListObject *self, PyObject *args)
{
Py_ssize_t i, start=0, stop=Py_SIZE(self);
PyObject *v;

if (!PyArg_ParseTuple(args, "O|O&:index", ,
_PyEval_SliceIndex, ,
_PyEval_SliceIndex, ))


This is already paying the cost of not using C-style positional
function arguments, but then it only takes an argument tuple, so it
can't take keyword arguments anyway. Why? Wouldn't it be nice to be
able to write:

mylist.index(42, start=10, stop=99)

instead of:

mylist.index(42, 10, 99)

This would also allow stop to be passed alone:

mylist.index(42, stop=99)

rather than having to pass the default value for start explicitly just
so we can pass stop:

mylist.index(42, 0, 99)
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Terry Reedy]

On 2/10/2019 10:47 AM, Ian Kelly wrote:

On Sat, Feb 9, 2019 at 1:19 PM Terry Reedy  wrote:


This is the result of Python being a project of mostly unpaid volunteers.

See my response in this thread explaining how '/' appears in help output
and IDLE calltips.  '/' only appears for CPython C-coded functions that
have been modified to use Argument Clinic.  A.C. was added, I believe,
in 3.5.  Simple builtins like len would have been the first to be
converted.  The math module was converted for 3.7.  There are some new
conversions for 3.8 and likely some will be left for future versions.


I'm sure there are good reasons for it like most things Python does, but I
can't help but wonder if working on removing the positional limitation from
CPython would be a better use of time.


The pass-by-position limitation is not in CPython, it is the behavior of 
C functions, which is the behavior of function calls in probably every 
assembly and machine language.  Allowing the flexibility of Python 
function calls take extra code and slows function calls.


math.sin, for instance, is a fast-as-possible wrapper around the C math 
library sin function.  It extracts the C double from the Python float, 
calls C sin, and returns the returned C double wrapped as a Python 
float.  Coredevs decided that being able to call math.sin(x=.3) is 
not worth the resulting slowdown.  I am rather sure that heavy users of 
the math module would agree.


--
Terry Jan Reedy

--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Sun, Feb 10, 2019 at 2:18 PM Avi Gross  wrote:
> I am not sure how python implements some of the functionality it does as
> compared to other languages with similar features. But I note that there are
> rules, presumably some for efficiency, such as requiring all keyword
> arguments to be placed after the last positional argument. I mean I can call
> func(a,b,c,d=1,e=2) but not func(a,b,d=1, c, e=2).
>
> So if you allowed a keyword to optionally be used for any positional
> argument other than the last, c, would it not require a change in this rule?
> I mean func(a="invalid",b,c,d=1,e=2) would violate the rule and so would
> making b a keyword version. In my example, and for this reason only, maybe c
> could work.

My suggestion was not to allow keyword arguments to arbitrarily
replace any positional parameter, or to otherwise change
argument-passing in any way. The suggestion was to drop
positional-only arguments from functions implemented in C instead of
just documenting them better. In the example above, if you want to
pass a by keyword, you would have to pass b and c by keyword as well.
That would still be true for functions implemented in C if a, b, and c
are no longer positional-only.

> The original motivation for keyword arguments included the concept of
> specifying a default if not used. Positional arguments have no default.
> Similarly, they are required if explicitly named in the function definition.
> So we are intermingling multiple concepts in the previous design.

Positional arguments are allowed to have defaults, and keyword-only
arguments are allowed to not have defaults. These are all valid
syntax:

# Allows a and b to be passed either positionally or by keyword
def foo(a=1, b=2): pass

# b is keyword-only
def foo(a=1, *, b=2): pass

# Allows a and b to be passed either positionally or by keyword
def foo(a, b): pass

# b is keyword-only and has no default
def foo(a, *, b): pass

Positional-ONLY arguments are not directly supported by the language,
but they exist in the C API and can also have defaults. For example,
dict.get takes two positional-only arguments. The second argument is
optional, and its default is None.

My point is that the axis of positional-only versus
positional-or-keyword versus keyword-only, and the axis of required
versus optional are entirely separate.

> I won't go on except to say it would break lots of existing code and
> potentially complicate new code.

Can you give an example of something that would be broken by updating
C API functions to name positional-only arguments instead of just
updating them to document that they're positional-only?
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Sun, Feb 10, 2019 at 9:34 AM Chris Angelico  wrote:
>
> On Mon, Feb 11, 2019 at 2:49 AM Ian Kelly  wrote:
> >
> > On Sat, Feb 9, 2019 at 1:19 PM Terry Reedy  wrote:
> > >
> > > This is the result of Python being a project of mostly unpaid volunteers.
> > >
> > > See my response in this thread explaining how '/' appears in help output
> > > and IDLE calltips.  '/' only appears for CPython C-coded functions that
> > > have been modified to use Argument Clinic.  A.C. was added, I believe,
> > > in 3.5.  Simple builtins like len would have been the first to be
> > > converted.  The math module was converted for 3.7.  There are some new
> > > conversions for 3.8 and likely some will be left for future versions.
> >
> > I'm sure there are good reasons for it like most things Python does, but I
> > can't help but wonder if working on removing the positional limitation from
> > CPython would be a better use of time.
>
> Do you ACTUALLY want to call math.sin(x=1.234) or is it purely for the
> sake of consistency? Aside from questions about the help format, what
> is actually lost by the inability to pass those arguments by name?

No, but I wouldn't object to d.get(key='foo', default=12). It's partly
about consistency, but mostly I was reacting to Terry's comments in
that a) positional-only arguments are a "limitation" and there is no
desire for the rest of Python to match CPython's behavior in this
instance, and b) it sounds like a great deal of effort is being spent
on updating all the C function signatures one at a time so that the
help string can be updated to a form that is unfamiliar and not
intuitive and not normally accessible to pure Python functions without
some arm twisting. If every function has to be updated anyway, why not
update them by fixing their signatures?
-- 
https://mail.python.org/mailman/listinfo/python-list

RE: The slash "/" as used in the documentation

[Avi Gross]

Chris,

I would appreciate another pointer to the documentation explaining what was
done and why as I deleted the earlier discussion.

You ask:

> Aside from questions about the help format, what is actually lost by the
inability 
> to pass those arguments by name?

I am not sure how python implements some of the functionality it does as
compared to other languages with similar features. But I note that there are
rules, presumably some for efficiency, such as requiring all keyword
arguments to be placed after the last positional argument. I mean I can call
func(a,b,c,d=1,e=2) but not func(a,b,d=1, c, e=2).

So if you allowed a keyword to optionally be used for any positional
argument other than the last, c, would it not require a change in this rule?
I mean func(a="invalid",b,c,d=1,e=2) would violate the rule and so would
making b a keyword version. In my example, and for this reason only, maybe c
could work.

And note the impact IF ALLOWED on the existing and new programs that allow a
variable number of arguments of the form func(*args, **kwargs) when they
evaluate. The previous model was that args would be a sequence of the
arguments you could index so args[0] would be the first, or that you can pop
off the front and use. If any of the previously un-named arguments can now
entered with a keyword, are they now placed in args or in the dictionary
kwargs? If in kwargs, the program now needs to know to look there in
addition to the command line. If it was the first argument and is no longer
in args, the second and further arguments would either be shifted over and
be used wrong or you need a placeholder.

The original motivation for keyword arguments included the concept of
specifying a default if not used. Positional arguments have no default.
Similarly, they are required if explicitly named in the function definition.
So we are intermingling multiple concepts in the previous design.

I won't go on except to say it would break lots of existing code and
potentially complicate new code.

Let me add a dumb suggestion. Anyone who desperately wants to name the
parameters has a rather strange option they can do now. Very imperfect but
consider the function prototype I have been using for illustration:

func(a,b,c,d=1,e=2)

It requires three positional arguments. What if you implement your code so
some special values mean that you are going to pass along "a" as "key_a"
instead. You can use something like None or the ellipsis(...) to signal this
as in:

def func(a, b, c, d=1, e=2, key_a=None):
if a == ... :
a = key_a
print(a)

The above does nothing but illustrates a WAY to allow a keyword
implementation by using one or more placeholders as you can do the same
gimmick for b and c.

Here is how it runs if you use the positional arg, or an ellipsis and then a
keyword or an ellipsis and accept the default for the keyword:

>>> func(1,2,3)
1
>>> func(...,2,3,key_a="keyed up")
keyed up
>>> func(...,2,3)
None

So could you re-implement processing in a NEW language to allow different
handling. I am guessing you could. Again, other languages currently do
things their own way. But for compatibility, I can see why they may be
patching and documenting what IS.

And note you could create an amazingly annoying language where each
parameter is specified as having umpteen attributes like it has to be the
second un-named argument and of a restricted number of types and if it has a
keyword it can be abbreviated as short as some string and then should it be
placed in position 2 and does it have a default and who knows what more.

Avi

-Original Message-
From: Python-list  On
Behalf Of Chris Angelico
Sent: Sunday, February 10, 2019 11:32 AM
To: Python 
Subject: Re: The slash "/" as used in the documentation

On Mon, Feb 11, 2019 at 2:49 AM Ian Kelly  wrote:
>
> On Sat, Feb 9, 2019 at 1:19 PM Terry Reedy  wrote:
> >
> > This is the result of Python being a project of mostly unpaid
volunteers.
> >
> > See my response in this thread explaining how '/' appears in help 
> > output and IDLE calltips.  '/' only appears for CPython C-coded 
> > functions that have been modified to use Argument Clinic.  A.C. was 
> > added, I believe, in 3.5.  Simple builtins like len would have been 
> > the first to be converted.  The math module was converted for 3.7.  
> > There are some new conversions for 3.8 and likely some will be left for
future versions.
>
> I'm sure there are good reasons for it like most things Python does, 
> but I can't help but wonder if working on removing the positional 
> limitation from CPython would be a better use of time.

Do you ACTUALLY want to call math.sin(x=1.234) or is it purely for the sake
of consistency? Aside from questions about the help format, what is actually
lost by the inability to pass those arguments by name?

ChrisA
--
https://mail.python.org/mailman/listinfo/python-list

-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Mon, Feb 11, 2019 at 2:49 AM Ian Kelly  wrote:
>
> On Sat, Feb 9, 2019 at 1:19 PM Terry Reedy  wrote:
> >
> > This is the result of Python being a project of mostly unpaid volunteers.
> >
> > See my response in this thread explaining how '/' appears in help output
> > and IDLE calltips.  '/' only appears for CPython C-coded functions that
> > have been modified to use Argument Clinic.  A.C. was added, I believe,
> > in 3.5.  Simple builtins like len would have been the first to be
> > converted.  The math module was converted for 3.7.  There are some new
> > conversions for 3.8 and likely some will be left for future versions.
>
> I'm sure there are good reasons for it like most things Python does, but I
> can't help but wonder if working on removing the positional limitation from
> CPython would be a better use of time.

Do you ACTUALLY want to call math.sin(x=1.234) or is it purely for the
sake of consistency? Aside from questions about the help format, what
is actually lost by the inability to pass those arguments by name?

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Jon Ribbens]

On 2019-02-10, Chris Angelico  wrote:
> On Mon, Feb 11, 2019 at 2:21 AM Jon Ribbens  wrote:
>> On 2019-02-09, Terry Reedy  wrote:
>> > '/' is no uglier than, and directly analogous to, and as easy to produce
>> > and comprehend, as '*'.  It was selected after considerable discussion
>> > of how to indicate that certain parameters are, at least in CPython,
>> > positional only.  The discussion of options included at least some of
>> > those given above.  It is very unlikely to go away or be changed.
>>
>> Ok, but what does it *mean*?
>
> It means "everything prior to this point is positional-only".
>
>> As an aside, how is 'math.sin' actually implemented? mathmodule.c
>> refers to the function 'math_sin' but that name is not defined
>> anywhere in the Python source code. I'm a bit mystified as to how
>> CPython manages to compile!
>
> A lot of those sorts of functions are hyperthin wrappers around the C
> math library. A bit of digging takes me to line 1176 of mathmodule.c
> (in my source tree; exact line number may vary), which uses the
> #define of FUNC1 from line 1032, and the actual code is up at line
> 876, with a good block comment.

Ah, it's using C preprocessor string concatenation to build the
function name, which is why grepping for 'math_sin' didn't find it.

Many thanks for your helpful answers.
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Ian Kelly]

On Sat, Feb 9, 2019 at 1:19 PM Terry Reedy  wrote:
>
> This is the result of Python being a project of mostly unpaid volunteers.
>
> See my response in this thread explaining how '/' appears in help output
> and IDLE calltips.  '/' only appears for CPython C-coded functions that
> have been modified to use Argument Clinic.  A.C. was added, I believe,
> in 3.5.  Simple builtins like len would have been the first to be
> converted.  The math module was converted for 3.7.  There are some new
> conversions for 3.8 and likely some will be left for future versions.

I'm sure there are good reasons for it like most things Python does, but I
can't help but wonder if working on removing the positional limitation from
CPython would be a better use of time.
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Chris Angelico]

On Mon, Feb 11, 2019 at 2:21 AM Jon Ribbens  wrote:
>
> On 2019-02-09, Terry Reedy  wrote:
> > '/' is no uglier than, and directly analogous to, and as easy to produce
> > and comprehend, as '*'.  It was selected after considerable discussion
> > of how to indicate that certain parameters are, at least in CPython,
> > positional only.  The discussion of options included at least some of
> > those given above.  It is very unlikely to go away or be changed.
>
> Ok, but what does it *mean*?

It means "everything prior to this point is positional-only".

> As an aside, how is 'math.sin' actually implemented? mathmodule.c
> refers to the function 'math_sin' but that name is not defined
> anywhere in the Python source code. I'm a bit mystified as to how
> CPython manages to compile!

A lot of those sorts of functions are hyperthin wrappers around the C
math library. A bit of digging takes me to line 1176 of mathmodule.c
(in my source tree; exact line number may vary), which uses the
#define of FUNC1 from line 1032, and the actual code is up at line
876, with a good block comment.

ChrisA
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Jon Ribbens]

On 2019-02-09, Terry Reedy  wrote:
> '/' is no uglier than, and directly analogous to, and as easy to produce 
> and comprehend, as '*'.  It was selected after considerable discussion 
> of how to indicate that certain parameters are, at least in CPython, 
> positional only.  The discussion of options included at least some of 
> those given above.  It is very unlikely to go away or be changed.

Ok, but what does it *mean*?

As an aside, how is 'math.sin' actually implemented? mathmodule.c
refers to the function 'math_sin' but that name is not defined
anywhere in the Python source code. I'm a bit mystified as to how
CPython manages to compile!
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Terry Reedy]

On 2/9/2019 2:10 PM, Piet van Oostrum wrote:

Christian Gollwitzer  writes:


__import__( 'sys' ).version

'3.6.1 |Anaconda 4.4.0 (x86_64)| (default, May 11 2017, 13:04:09) \n[GCC
4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]'

help( __import__( 'math' ).sin )



Help on built-in function sin in module math:

sin(...)
 sin(x)

 Return the sine of x (measured in radians).


The help is actually not written out to the terminal but, displayed in
the pager (less), and the first sin(...) is typeset in boldface.

Christian


Even simpler:


help(len)

help(len)
Help on built-in function len in module builtins:

len(obj, /)
 Return the number of items in a container.

both in python 3.6 and 3.7.

This is weird.


This is the result of Python being a project of mostly unpaid volunteers.

See my response in this thread explaining how '/' appears in help output 
and IDLE calltips.  '/' only appears for CPython C-coded functions that 
have been modified to use Argument Clinic.  A.C. was added, I believe, 
in 3.5.  Simple builtins like len would have been the first to be 
converted.  The math module was converted for 3.7.  There are some new 
conversions for 3.8 and likely some will be left for future versions.


--
Terry Jan Reedy

--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Piet van Oostrum]

Christian Gollwitzer  writes:

 __import__( 'sys' ).version
> '3.6.1 |Anaconda 4.4.0 (x86_64)| (default, May 11 2017, 13:04:09) \n[GCC
> 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]'
 help( __import__( 'math' ).sin )
>
>
> Help on built-in function sin in module math:
>
> sin(...)
> sin(x)
>
> Return the sine of x (measured in radians).
>
>
> The help is actually not written out to the terminal but, displayed in
> the pager (less), and the first sin(...) is typeset in boldface.
>
>   Christian

Even simpler:

>>> help(len)
help(len)
Help on built-in function len in module builtins:

len(obj, /)
Return the number of items in a container.

both in python 3.6 and 3.7.

This is weird.
-- 
Piet van Oostrum 
WWW: http://piet.vanoostrum.org/
PGP key: [8DAE142BE17999C4]
-- 
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Terry Reedy]

On 2/9/2019 8:29 AM, Piet van Oostrum wrote:

r...@zedat.fu-berlin.de (Stefan Ram) writes:



   The slash »/« as used in the documentation

f( x, /, y )

   is so ugly, it will disappear. Especially since it consumes
   a comma as it it was a parameter itself.

   Possible alternatives include:

   A newline:

f( x,
y )

   A separate specification of the first non-positional parameter:

f( x, y )
# y

   (use "(" or ")" when all parameters are non-positional or
   positional, respectively).

   A semicolon:

f( x; y )

   (the actual call still would use a comma there).


'/' is no uglier than, and directly analogous to, and as easy to produce 
and comprehend, as '*'.  It was selected after considerable discussion 
of how to indicate that certain parameters are, at least in CPython, 
positional only.  The discussion of options included at least some of 
those given above.  It is very unlikely to go away or be changed.



What are you talking about? What documentation?


CPython has an internal 'Argument Clinic' function that is gradually 
being applied to more and more builtin C-coded functions.  (It requires 
a slight rewrite of the function code.)  It adds a __text_signature__ 
attribute to the function object.  The text signature includes '/' when 
appropriate.  For instance


>>> dict.fromkeys.__text_signature__
'($type, iterable, value=None, /)'

inspect.signature creates an inspect.Signature object from this 
attribute.  The __str__ method turns it back to the text needed for 
display of the signature.


>>> s = inspect.signature(dict.fromkeys)
>>> type(s)

>>> str(s)
'(iterable, value=None, /)'

The interactive help function uses this text.

>>> help(dict.fromkeys)
...
fromkeys(iterable, value=None, /) method ...

IDLE tool tips present the same signature string.

AFAIK, '/' is not yet used in the reference docs.  Perhaps the reason is 
that limiting arg passing to position is a CPython limitation rather 
than a language requirement.  (AFAIK, pypy could allow iterable and 
value to be passed by keyword.)  The help function is not part of the 
language definition, so I think the CPython version can document the 
CPython builtins.


The dict doc in the library reference has

classmethod fromkeys(iterable[, value])

The default value for 'value' is buried in the entry because 
'value=None' in the signature, without a following '/', would falsely 
imply that 'value=0' in a call should work.  There is no indication of 
the limitation.



It seems to me you are talking about a completely different programming 
language, not python.


Documentation is not the language.  Whether to allow '/' in def 
statements signatures has been discussed.  The conclusion so far is that 
the C limitation is not needed in Python itself.


--
Terry Jan Reedy


--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Christian Gollwitzer]

Am 09.02.19 um 14:40 schrieb Stefan Ram:

Piet van Oostrum  writes:

r...@zedat.fu-berlin.de (Stefan Ram) writes:

The slash »/« as used in the documentation
f( x, /, y )

What are you talking about? What documentation? It seems to
me you are talking about a completely different programming
language, not python.


|>>> __import__( 'sys' ).version
|'3.7.0 ~~~'
|>>> help( __import__( 'math' ).sin )
|Help on built-in function sin in module math:
|
|sin(x, /)
|Return the sine of x (measured in radians).

   ~~~ = a part of the transcript that was omitted by me


Is this a new thing in 3.7? Because here I get:

Apfelkiste:Tcl2018 chris$ python3
Python 3.6.1 |Anaconda 4.4.0 (x86_64)| (default, May 11 2017, 13:04:09)
[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> __import__( 'sys' ).version
'3.6.1 |Anaconda 4.4.0 (x86_64)| (default, May 11 2017, 13:04:09) \n[GCC 
4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.57)]'

>>> help( __import__( 'math' ).sin )


Help on built-in function sin in module math:

sin(...)
sin(x)

Return the sine of x (measured in radians).


The help is actually not written out to the terminal but, displayed in 
the pager (less), and the first sin(...) is typeset in boldface.


Christian
--
https://mail.python.org/mailman/listinfo/python-list

Re: The slash "/" as used in the documentation

[Piet van Oostrum]

r...@zedat.fu-berlin.de (Stefan Ram) writes:

>   The slash »/« as used in the documentation
>
> f( x, /, y )
>
>   is so ugly, it will disappear. Especially since it consumes
>   a comma as it it was a parameter itself.
>
>   Possible alternatives include: 
>
>   A newline:
>
> f( x,
> y )
>
>   A separate specification of the first non-positional parameter:
>
> f( x, y )
> # y
>
>   (use "(" or ")" when all parameters are non-positional or
>   positional, respectively).
>
>   A semicolon:
>
> f( x; y )
>
>   (the actual call still would use a comma there).
>
What are you talking about? What documentation? It seems to me you are talking 
about a completely different programming language, not python.
-- 
Piet van Oostrum 
WWW: http://piet.vanoostrum.org/
PGP key: [8DAE142BE17999C4]
-- 
https://mail.python.org/mailman/listinfo/python-list