[New-bugs-announce] [issue37699] Explicit mention of raised ValueError's after .detach() of underlying IO buffer

[Brian Skinn]

New submission from Brian Skinn <bskinn at alum.mit.edu>:

Once the underlying buffer/stream is .detach()ed from an instance of a subclass of TextIOBase or BufferedIOBase, accession of most attributes defined on TextIOBase/BufferedIOBase or the IOBase parent, as well as calling of most methods defined on TextIOBase/BufferedIOBase/IOBase, results in raising of a ValueError.

Currently, the documentation of both .detach() methods states simply:

> After the raw stream has been detached, the buffer is in an unusable state.

I propose augmenting the above to something like the following in the docs for both .detach() methods, to make this behavior more explicit:

> After the raw stream has been detached, the buffer
> is in an unusable state. As a result, accessing/calling most
> attributes/methods of either :class:`BufferedIOBase` or its
> :class:`IOBase` parent will raise :exc:`ValueError`.

I confirm that the error raised for both `BufferedReader` and `TextIOWrapper` after `.detach()` *is* ValueError in all of 3.5.7, 3.6.8, 3.7.3, and 3.8.0b1.

----------
assignee: docs at python
components: Documentation
messages: 348594
nosy: bskinn, docs at python
priority: normal
severity: normal
status: open
title: Explicit mention of raised ValueError's after .detach() of underlying IO buffer
type: enhancement
versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

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