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 <python-list-bounces+avigross=verizon.net at python.org> On
Behalf Of Ian Kelly
Sent: Monday, February 11, 2019 1:46 AM
To: Python <python-list at python.org>
Subject: Re: The slash "/" as used in the documentation

On Sun, Feb 10, 2019 at 2:18 PM Avi Gross <avigross at verizon.net> 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