[Idle-dev] Doc Commentary

[Guido van Rossum]

> In Re: Idle documentation - since Idle is now "standard"
> in Python distribution kits, can Idle documentation also
> become a "standard" part of the release?

Aargh!  There's no "official" IDLE documentation.  There's a very
useful doc package by Daryl Harms, which I put up at
http://www.python.org/idle/doc/.  Perhaps this should be converted to
LaTeX and incorporated into the Python doc tree.  Issue: Daryl has
screen shots that the current Python documentation package can't deal
with.  For Fred Drake to resolve...

> In the 0.5 Idle docs - the latest I've come across -
> there's a small section on limitations ("Shell Window" ->
> "Special Issues").
> 
> Seems to me a mention might be made that the following
> idiom also doesn't work as expected:
> 
> >>> import sys
> >>> f = open('some-output-file', 'w')
> >>> sys.stdout = f
> >>> # do some stuff
> >>> sys.stdout = sys.__stdout__
> 
> Because on entry, sys.stdout is already redirected
> (not reflected in sys.__stdout__)

Where did you get this idiom?  You should never use sys.__stdout__
this way!  The proper idiom is

  save_stdout = sys.stdout
  try:
      sys.stdout = f
      # do some stuff
  finally:
      sys.stdout = save_stdout

If you know of any places that are promoting direct use of __stdout__,
please let them know this is wrong.  If you are contemplating to use
this in code examples you intend to distribute, please don't!

--Guido van Rossum (home page: http://www.python.org/~guido/)