Survey: improving the Python std lib docs

[Deborah Swanson]

Michael Torrie wrote, on Wednesday, May 17, 2017 3:11 PM
> 
> On 05/17/2017 02:31 PM, Ned Batchelder wrote:
> > Can you give an example of such a method? Often, that signature is 
> > used because there is no pre-conception of what the arguments might 
> > be.
> 
> I'm not sure if this afflicts the standard library, but in my 
> own code, since Python doesn't support constructors with 
> different signatures, you pretty much have to rely on kwargs 
> with __init__() to handle different permutations of 
> construction arguments.  Not that we don't know what the 
> arguments might be, we just don't know which of them we'll 
> have to deal with.  Maybe the standard library is better 
> designed than my own code, but I find I have to implement 
> __init__(self, **kwargs) all the time.


While I can respect and appreciate your specialized interest in specific
kwargs, and I read in other's posts that help()'s display of kwargs is
conditional on several things, I really want to reiterate and clarify my
beginner's request.

I know of several functions I've used without any *args or **kwargs
because I had no clue from the docs what they might be. And, I know of
one function now, from posts in this list, which takes kwargs, but I
only know one application of one possible kwarg in this function because
one member of this list, Peter Otten, used it in a suggestion he gave
me.

This is all there is in the docs for that function:


somenamedtuple._replace(kwargs)

    Return a new instance of the named tuple replacing specified fields
with new values:
(Examples
box)---------------------------------------------------------------|
|    >>>
|
|
|
|    >>> p = Point(x=11, y=22)
|
|    >>> p._replace(x=33)
|
|    Point(x=33, y=22)
|
|
|
|    >>> for partnum, record in inventory.items():
|
|    ...     inventory[partnum] =
record._replace(price=newprices[partnum], |
|  timestamp=time.now())
|
|-----------------------------------------------------------------------
----|

>From this doc entry's example, I (sort of) get that x is a keyword arg
that is to be equal to 33 for any use of p._replace() in the code
following, until 
p._replace(kwarg) is respecified, or the code ends. So the response from
Python shows me that p has transformed to the Point(x=33, y=22). A
trivial example that doesn't begin to hint at the poential powers of
this kwarg.

The inventory[partnum] example is also quite trivial compared to the
kwarg use that Peter showed me.

When I asked him for an explanation, this is what I and he he said:

Deborah Swanson wrote:

> I know it's your "ugly" answer, but can I ask what the '**' in
> 
> fix = {label: max(values, key=len)}
> group[:] = [record._replace(**fix) for record in group]
> 
> means?

(Peter wrote)
d = {"a": 1, "b": 2}
f(**d)

is equivalent to

f(a=1, b=2)

so ** is a means to call a function with keyword arguments when you want
to 
decide about the *names* at runtime. Example:

>>> def f(a=1, b=2):
...     print("a =", a)
...     print("b =", b)
...     print()
... 
>>> for d in [{"a": 10}, {"b": 42}, {"a": 100, "b": 200}]:
...     f(**d)
... 
a = 10
b = 2

a = 1
b = 42

a = 100
b = 200

Starting from a namedtuple `record`

record._replace(Location="elswhere")

creates a new namedtuple with the Location attribute changed to
"elsewhere", 
and the slice [:] on the left causes all items in the `groups` list to
be 
replaced with new namedtuples,

group[:] = [record._replace(Location="elsewhere") for record in group]

is basically the same as

tmp = group.copy()
group.clear()
for record in tmp:
    group.append(record_replace(Location="elsewhere"))

To support not just Location, but also Kind and Notes we need the double

asterisk.



Now, I understood what he meant from the context of the problem he was
helping me with, but, how in the world would I have gotten that possible
use of somenamedtuple._replace(kwargs) from the blurb and examples in
the docs? Or any other possible kwarg and how they're used, including
special operators like "**" ?

If there's a tutorial somewhere on kwargs in general, what specific
types of kwargs there are, what special operators can be specifed for
them and how the kwargs are used, it would be very helpful to have that
tutorial referenced in a footnote-link next to kwargs whenever kwargs is
part of a function specification.

Or, if no such tutorial exists, the footnote-link could point to any
more detailed information that might explain what this creature "kwargs"
might be.

I have an item on my todo list to google "python kwargs", but it keeps
getting pushed deeper and deeper down my list because I have so little
hope that it will turn up anything useful.

Deborah