As per the blog entry http://www.logilab.org/blogentry/17873 I think the tempfile.mkstemp() documentation could be more helpful by suggesting the use of os.close() appropriately. If some native english speaker could give a review of the language I used in the additional text, I'd be grateful.
I don't think it would be beneficial to just talk about closing the file descriptor, or to talk about os open file limits. Closing open files when they are no longer needed is just good programming practice and IMO a discussion of it doesn't belong in the library docs unless it is at a more generic level (like os.open or open). I don't think the code shown in your blog post is using the library the way it is designed. If the programmer wants an open file object, they should use TemporaryFile or NamedTemporaryFile. If there really is a reason to get an os file handle and turn it into a file object, then os.openfd should be used. Perhaps the appropriate change to the documentation would be to mention os.openfd, and to mention that os.close is the correct function to use to close the file handle when it is no longer needed (unless, of course, openfd has been called). As for your markup, your ``os.close`` should instead be :func:`os.close`, which results in the automatic creation of a link to the os.close documentation.
Because if you want the Python file object, you should use TemporaryFile or NamedTemporaryFile. mkstemp is a lower level (closer to the os) interface, and is provided because Python has a philosophy of providing those low level interfaces when possible. Note that the TemporaryFile classes use mkstemp in their implementation.
That one has to close open files should be common knowledge. And it's already documented that the filehandle returned is to be treated as if coming from `os.open`, so the "isn't a file object" is documented as well. Insofar, I'm in agreement with David.
