According to the docs, and consistent with the Python 2.x behavior,
filehandle.write() should return None.  However, under 3.0a2 (and
3.0a1), it returns the number of characters written.

Either the documentation
http://docs.python.org/dev/3.0/tutorial/inputoutput.html#reading-and-writing-files
is wrong, or it is a bug.  I would *much* prefer if the behavior would
stay the same as before.

Below is a sample session illustrating the behavior.  Note that I also
get an error message when exiting the session using exit() - this is an
unrelated problem.

Python 3.0a2 (r30a2:59382, Dec 27 2007, 15:48:14) 
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> handle = open('test_file.txt.', 'w')
>>> handle.write('spam')
4
>>> r = handle.write('more spam')
>>> print(r)
9
>>> exit()
/usr/local/py3k/lib/python3.0/io.py:1210: RuntimeWarning: Trying to
close unclosable fd!
  self.buffer.close()

Guido, Mike and Mark have implemented most of the new IO library. I'm
sure they can shed some light on the design decision.

I've fixed the other bug a while ago. I don't use exit() and I didn't
noticed the problem until Joseph pointed me in the right direction.

The intention was that the lowest-level (unbuffered) stream object can
write fewer bytes than given to it, as it is a direct interface to the
underlying system call, which has this property (especially when the
file is in non-blocking mode).

I think it's fine to return None from the higher-level classes' write()
method (buffered and text).  Though this makes it a bit harder to switch
between buffered and unbuffered binary output.  Perhaps text I/O should
return None and bytes I/O should return a byte count?

After doing some more reading, I realize that the current behaviour is
totally consistent with
http://www.python.org/dev/peps/pep-3116/
which I should have consulted first.
So perhaps it should be considered to be simply a case of a
documentation error, as I alluded to when I open this issue. (sorry for
the noise)

Georg, can you whip up a bit of documentation for this?  (Of course you
may find that the docs for io.py are lacking more than just this nit...)

The docs for "io" are practically nonexistent :)

I'll leave that for a separate issue, and fixed this one by adding a
paragraph to the current file object docs (better than nothing) in r61710.