The change was announced in http://docs.python.org/dev/whatsnew/2.7.html, but indeed it wasn't advertised in py3k changes - my apologies, I didn't check it was.

I agree that the doc should be clarified on several aspects.

* The returned value is the new file SIZE indeed (I guess we can still use "file" here, since imo other streams can't be truncated anyway).

* Truncate() simply changes the current end-of-file (the word is historical, resize() would have been better - as this has been discussed on mailing lists).

* Extending the file size with truncate() or with a write() after end-of-file (that's your sample's case) does, or does not (depending on the platform), fill the empty space with zeroes.


Proposal for doc update :

Resizes the file to the given size (or the current position), without moving the file pointer. This resizing can extend or reduce the current file size. In case of extension, the content of the new file area depends on the platform (on most systems, additional bytes are zero-filled, on win32 they're undetermined). Returns the new file size.

Would it be ok thus ?