[Python-ideas] Documenting Python warts

[Nick Coghlan]

On Wed, Jan 2, 2013 at 10:01 AM, Oleg Broytman <phd at phdru.name> wrote:
> On Tue, Jan 01, 2013 at 03:17:34PM -0800, alex23 <wuwei23 at gmail.com> wrote:
>> On Jan 2, 8:16 am, Chris Angelico <ros... at gmail.com> wrote:
>> > It's a little odd what you can and can't do,
>> > until you understand the underlying system fairly well. It's something
>> > that's highly unlikely to change; one of the premises would have to be
>> > sacrificed (or at least modified) to achieve it.
>>
>> By this definition, though, every feature of Python that someone
>> doesn't understand is a wart. For a new user, mutable default
>> parameters is a wart, but once you understand Python's execution &
>> object models, it's just the way the language is.
>>
>> Generally, I find "wart" means "something the user doesn't like about
>> the language even if it makes internal sense".

FWIW, I prefer the term "traps for the unwary" over "warts", since
it's less judgmental and better covers the goal of issues for people
which can cause problems with learning the language. I highlight some
of the examples related to the import system here:
http://python-notes.boredomandlaziness.org/en/latest/python_concepts/import_traps.html

>    What about warts that don't have internal sense? Mutable default
> parameters are just artifacts of the implementation. What is their
> "internal sense"?

Um, no. Mutable default arguments make perfect sense once you
understand the difference between compile time, definition time and
execution time for a function. Defaults are evaluated at definition
time, thus they are necessarily shared across all invocations of the
function. If you don't want them shared, you use a sentinel value like
None to postpone the creation to execution time. They're a trap for
the unwary, but not a wart.

Else clauses on loops are arguably closer to qualifying as a genuine
wart (see http://python-notes.boredomandlaziness.org/en/latest/python_concepts/break_else.html),
since they're not much shorter than the explicit sentinel value based
alternative, and significantly less intuitive. However, because they
exist, and people *will* encounter them in real world code, every
beginner will eventually have to learn what they mean.

The other complaint discussed in the thread, regarding "Why don't
compound statement keywords and their trailing colon count as
parentheses for purposes of ignoring line breaks?" has to do with a
mix of implementation simplicity and error quality. Pairing up
"if"/":", "with"/":", "for"/":" etc would certainly be possible, but
may result in the infamous "missing semi-colon" style of C syntax
error (or missing paren style of Lisp error), where the fault may be
reported well away from the missing character, or with an error that
is extremely hard for a beginner to translate into "you left out a
character here". Given the likely detrimental effect on error quality,
and the ability to use actual parens or backslashes for line
continuation.

The Design FAQ and Programming FAQ are intended to be the repository
for answers to this kind of question. Addition of new questions and
answers is handled like any other patch: via the tracker (and some of
the existing answers could likely do with updates as well).

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia