Survey: improving the Python std lib docs

[Deborah Swanson]

> -----Original Message-----
> From: Python-list 
> [mailto:python-list-bounces+python=deborahswanson.net at python.o
> rg] On Behalf Of Gregory Ewing
> Sent: Thursday, May 18, 2017 5:00 PM
> To: python-list at python.org
> Subject: Re: Survey: improving the Python std lib docs
> 
> 
> 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.

I'm getting a clearer picture, and even though it might not be as
cleanly straightforward as using recordsclass, I think it would be a
good learning experience to use "somenamedtuple._replace(kwargs)" in a
context of my own devising, rather than just copying out code given for
a different problem from someone else.

Besides, I need to compile memoryslots.c to make a usable recordsclass
module, and I haven't successfully compiled a C program outside of
Visual Studio yet(and that was a couple decades ago). So I'm going to
see if I can really understand kwargs in a namedtuple context first.  

It will be good to have a bag of tricks to tackle all my Excel
spreadsheet conversion-to-Python and new-from-scratch projects with. I'm
saying goodbye to Microsoft Excel, but I want to take all my work and
ideas with me. And who knows, maybe I'll have some templates and
tutorials to contribute for others who'd like to do the same.

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

Oh, I think I see what you mean now. But I'm sure glad I've had this
list to talk to, or I'd never have figured it out from scratch on my
own.

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

No, perhaps not. I was frustrated by not being able to see and
understand what I needed to know from the docs, but maybe more in depth
tutorials for beginners, and some kind of pointers to them, would fill
that gap more effectively.
 
> > 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

I may do that Google search when I get to it, but I've learned a lot
right here. Maybe enough, but Ill have to work with what I now know to
see that.

Thanks very much,

Deborah