Survey: improving the Python std lib docs

[Gregory Ewing]

Deborah Swanson wrote:

> 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)

To someone who has some basic Python knowledge about what keyword
arguments are, that's actually pretty clear. What it's saying is
that any of the namedtuple's attribute names can be used as a
keyword argument to the _replace method.

Namedtuple is something of a special case, because it doesn't have a
fixed set of acceptable keyword args. Most things do, and there should
be something somewhere in the docs indicating what they are. Note
that you may need to consult docs for base classes to get the full
picture, since e.g. constructors often pass any keyword args they
don't understand on to their base class constructor.

> 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?

 From knowledge about keyword arguments in general, exrapolation
from the example, and following logic.

I know that's probably not a very helpful answer, but the reason
it seems so obscure to you now is because you don't have all of
the basic Python knowledge that the docs assume the reader has.
If you come back to the same docs later when you do have that
knowledge, you will see it all more clearly.

> 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.

This is all general knowlege about the Python language that you
can't expect the reference documentation to point out in relation
to every function and method.

> 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.

I strongly encourage you to do it sooner rather than later, because
you'll gain some important foundational knowledge that's vital for
understanding many things you'll see in Python code and Python docs.

-- 
Greg