[Python-ideas] Documenting Python warts

Wed Jan 2 00:49:16 CET 2013

Hi!
On Tue, Jan 01, 2013 at 10:55:05PM +0100, Antoine Pitrou <solipsis at pitrou.net> wrote:
> On 2012年12月31日 04:00:12 +0400
> Oleg Broytman <phd at phdru.name> wrote:
> > On Sun, Dec 30, 2012 at 11:20:34PM +0100, Victor Stinner <victor.stinner at gmail.com> wrote:
> > > If I understood correctly, you would like to list some specific issues
> > > like print() not flushing immediatly stdout if you ask to not write a
> > > newline (print "a", in Python 2 or print("a", end=" ") in Python 3).
> > > If I understood correctly, and if you want to improve Python, you
> > > should help the documentation project. Or if you can build a website
> > > listing such issues *and listing solutions*
> > 
> > -- things that don't exist where they should (but the core team object
> > or they are hard to implement or something);
> > -- things that exist where they shouldn't; they are hard to fix because
> > removing them would break backward compatibility;
> > -- things that are implemented in strange, inconsistent ways.
> > 
> > A few examples:
> > [snip]
>> The problem is you are listing examples which *in your opinion* are
> issues with Python. Other people would have different ideas of what is
> an issue and what is not. This can't be the right methodology if we
> want to write a piece of Python docs.

 Absolutely not. I collected the list of examples in reply to a
question "what are warts and why one cannot just document solutions?" I
hope I managed to show that warts are built (or unbuilt, so to say) so
deep in Python and the stdlib design it's impossible to fix them with
code or documentation. Fixing them require major design changes.
> Only things which are *well-known* annoyances can qualify.

 Well, some warts are quite well-known. My counter overflows when I
try to count how many times anonymous code blocks have been proposed
and rejected.
 IIRC Mr. van Rossum admitted that for/else was a design mistake.
 One wart is being worked on right now: async libs redesign.
> I also disagree that missing features are "warts"; they are just
> missing features, not something unpleasant that's difficult to get rid
> of.

 Some of those missing features are near to impossible to get rid of.
The idea of anonymous code blocks is rejected constantly so no one would
dare to create a patch.
 As for their unpleasantness -- it's in the eye of the beholder, of
course. I'm not going to fight tooth and nail for my vision.
Oleg.
-- 
 Oleg Broytman http://phdru.name/ phd at phdru.name
 Programmers don't die, they just GOSUB without RETURN.