This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author rhettinger
Recipients docs@python, esegall, rhettinger
Date 2016-04-25.08:24:49
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1461572690.17.0.444168828407.issue26842@psf.upfronthosting.co.za>
In-reply-to
Content
> I hope this is useful. I realize it is much longer than the original.

There lies the difficultly.  The purpose of the tutorial is to quickly introduce the language, not to take someone deeply down a rabbit hole.  The docs tend to be worded in an affirmative manner showing cases of the language being used properly, giving a brief warning where necessary.  Further explorations should be left as FAQs.  

I think we could add a FAQ link or somesuch to the existing warning but the main flow shouldn't be interrupted (many on the topics in the tutorial could warrant entire blog posts and scores of StackOverflow entries, but the tutorial itself aspires to be a "short and sweet" quick tour around the language.  

The utility and approachability of the tutorial would be undermined by overexpanding each new topic.  This is especially important in the early sections of the tutorial (i.e. section 4).  

Also, I don't really like the provided explanation, "there are two cases ...".  The actual execution model has one case (default arguments are evaluated once when the function is defined) and there are many ways to use it.

Lastly, this is only one facet of parameter specification and parameter passing.  Other facets include, variable length argument lists, keyword-only arguments, annotations, etc.   Any expanded coverage should occur later in the tutorial and cover all the facets collectively.
History
Date User Action Args
2016-04-25 08:24:50rhettingersetrecipients: + rhettinger, docs@python, esegall
2016-04-25 08:24:50rhettingersetmessageid: <1461572690.17.0.444168828407.issue26842@psf.upfronthosting.co.za>
2016-04-25 08:24:50rhettingerlinkissue26842 messages
2016-04-25 08:24:49rhettingercreate