Cleanup guarantees?

[Gabriel Genellina]

En Fri, 09 Apr 2010 01:13:37 -0300, Alf P. Steinbach <alfps at start.no>  
escribió:

  > <code language="Py3">
  > import urllib.request   # urlopen
  > import codecs           # getreader
  > import sys              # stderr
  >
  > def text_stream_from( url, encoding ):
  >      text_reader = codecs.getreader( encoding )
  >      connection = urllib.request.urlopen( url )
  >      return text_reader( connection )
  >
  > def list_text( url, encoding ):
  >      lines = text_stream_from( url, encoding )
  >      for line in lines:
  >          print( line, end = "" )
  >      lines.close()       # Undocumented?
  >
  > url = "http://www.rfc-editor.org/rfc/rfc1149.txt"
  > list_text( url, "ascii" )
  > </code>
  >
  > First, I'm unable to find documentation that there /is/ a close method  
in the
  > text_reader object, and I'm unable to find documentation that there is  
a close
  > method in the file like connection object; is there such documentation?

codecs.getreader returns a StreamReader instance (see [1])
StreamReader is documented here [2] and it says "In addition to the above  
methods, the StreamReader must also inherit all other methods and  
attributes from the underlying stream." -- the stream being 'connection',  
 from urllib.request.urlopen.
The 3.x version of the documentation in [3] doesn't provide any details  
except being "a file-like object". The 2.x version [4] is much more clear:  
"a file-like object is returned. This supports the following methods:  
read(), readline(), readlines(), fileno(), close(), info(), getcode() and  
geturl(). It also has proper support for the iterator protocol."

[1] http://docs.python.org/py3k/library/codecs.html#codecs.getreader
[2] http://docs.python.org/py3k/library/codecs.html#codecs.StreamReader
[3]  
http://docs.python.org/py3k/library/urllib.request.html#urllib.request.urlopen
[4] http://docs.python.org/library/urllib.html#urllib.urlopen


  > Second, I'm unable to find documentation of when they're called and  
what they
  > do. It seems that (A) when the connection object's st
  method is called automatically, and (B) that when the
  > text_reader object's close method is called it calls the close method  
of the
  > wrapped stream (i.e. on the connection object). But where is this  
documented?

Nowhere, AFAIK.
I bet documentation patches are welcome.

-- 
Gabriel Genellina