[issue36129] io documentation unclear about flush() and close() semantics for wrapped streams

[Gregory Szorc]

New submission from Gregory Szorc <gregory.szorc at gmail.com>:

As part of implementing io.RawIOBase/io.BufferedIOBase compatible stream types for python-zstandard, I became confused about the expected behavior of flush() and close() when a stream is wrapping another stream.

The documentation doesn't lay out explicitly when flush() and close() on the outer stream should be proxied to the inner stream, if ever.

Here are some specific questions (it would be great to have answers to these in the docs):

1. When flush() is called on the outer stream, should flush() be called on the inner stream as well? Or should we simply write() to the inner stream and not perform a flush() on that inner stream?

2. When close() is called on the outer stream, should close() be called on the inner stream as well?

3. If close() is not automatically called on the inner stream during an outer stream's close(), should the outer stream trigger a flush() or any other special behavior on the inner stream? Or should it just write() any lingering data and then go away?

4. Are any of the answers from 1-3 impacted by whether the stream is a reader or writer? (Obviously reader streams don't have a meaningful flush() implementation.)

5. Are any of the answers from 1-3 impacted by whether the stream is in blocking/non-blocking mode?

6. Do any of the answers from 1-3 vary depending on whether behavior is incurred by the outer stream's __exit__?

(This issue was inspired by https://github.com/indygreg/python-zstandard/issues/76.)

----------
components: Interpreter Core
messages: 336715
nosy: indygreg
priority: normal
severity: normal
status: open
title: io documentation unclear about flush() and close() semantics for wrapped streams
type: enhancement
versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue36129>
_______________________________________