[docs] Behavior of ZipFile with file-like object and BufferedWriter. (issue 20699)

[vadmium+py at gmail.com]

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst
File Doc/library/io.rst (right):

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst#newcode396
Doc/library/io.rst:396: :term:`bytes-like <bytes-like object>` buffer
*b*, and return the
On 2015/02/19 22:12:27, r.david.murray wrote:
> I think 'buffer' should be 'object'.

Yes that is probably better. Maybe I originally wrote “buffer” before I
added the pre-allocated writable adjectives.

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst#newcode404
Doc/library/io.rst:404: be less than the number of bytes in *b*,
On 2015/02/19 22:39:45, storchaka wrote:
> On 2015/02/19 22:12:27, r.david.murray wrote:
> > I think len(b) is better here.  It is more precise..."number of
bytes" might
> > refer to something other than the length of the buffer.
> 
> Because len(b) is not correct. write(array('I', [1, 2, 3])) writes 12
bytes,
> while len() of the argument is 3.

Indeed. A bytes-like object does not even have to implement len(); see
the byteslike() factory I added in test_io.py.

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst#newcode504
Doc/library/io.rst:504: of bytes written (always equal to the number of
bytes in *b*, since if
On 2015/02/19 22:12:27, r.david.murray wrote:
> Do you understand the reason for the original wording?  Are there
circumstances
> where more bytes are written?

I don’t know, but I wondered if it was just to contrast with
RawIOBase.write(). RawIOBase can return less, but BufferedIOBase never
returns less. This wording seems to originate from Guido’s doc string in
2007: <https://hg.python.org/cpython/rev/f4391abe5b02#l1.480>.

In my mind it does not make sense to say you have written more bytes
than given, especially when it is impossible to have written less. Where
would those extra bytes come from?

Let me know if you think I should restore it to “never less than”.
However I think saying “always greater than or equal to” would be a step
backwards.

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst#newcode589
Doc/library/io.rst:589: optional initial :term:`bytes-like object` data.
On 2015/02/19 22:12:27, r.david.murray wrote:
> This should be "The argument *initial_bytes* is a :term:`bytes-like
object` that
> contains initial data."

Agreed.

http://bugs.python.org/review/20699/diff/13912/Doc/library/io.rst#newcode686
Doc/library/io.rst:686: Write the :term:`bytes-like object` object, *b*,
and return the
On 2015/02/19 22:12:27, r.david.murray wrote:
> Looks like there's an extra 'object' here, but I didn't generate the
docs to
> check.

Will fix this.

http://bugs.python.org/review/20699/