[docs] [issue21910] File protocol should document if writelines must handle generators sensibly

Jan Kanis report at bugs.python.org
Thu Jul 3 11:38:29 CEST 2014


New submission from Jan Kanis:

The resolution of issue 5445 should be documented somewhere properly, so people can depend on it or not.

IOBase.writelines handles generator arguments without problems, i.e. without first draining the entire generator and then writing the result in one go. That would require large amounts of memory if the generator is large, and fail entirely if the generator is infinite. 

codecs.StreamWriter.writelines uses self.write(''.join(argument)) as implementation, which fails on very large or infinite arguments.

According to issue 5445 it is not part of the file protocol that .writelines must handle (large/infinite) generators, only list-like iterables. However as far as I know this is not documented anywhere, and sometimes people assume that writelines is meant for this case. E.g. jinja (https://github.com/mitsuhiko/jinja2/blob/master/jinja2/environment.py#L1153, the dump method is explicitly documented to stream). The guarantees that .writelines makes or does not make in this regard should be documented somewhere, so that either .writeline implementations that don't handle large generators can be pointed out as bugs, or code that makes assumptions on .writeline handling large generators can be.

I personally think .writelines should handle large generators, since in the python 3 world a lot of apis were iterator-ified and it is wat a lot of people would probably expect. But having a clear and documented decision on this is more important. 

(note: I've copied most of the nosy list from #5445)

----------
assignee: docs at python
components: Documentation, IO
messages: 222165
nosy: JanKanis, benjamin.peterson, dlesco, docs at python, hynek, lemburg, pitrou, stutzbach, terry.reedy
priority: normal
severity: normal
status: open
title: File protocol should document if writelines must handle generators sensibly
versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue21910>
_______________________________________


More information about the docs mailing list