[New-bugs-announce] [issue38595] io.BufferedRWPair doc warning may need clarification

[Ryan Govostes]

New submission from Ryan Govostes <rgovostes at gmail.com>:

The documentation for the io.BufferedRWPair class gives this warning:

> BufferedRWPair does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use BufferedRandom instead.

I have a hard time understanding what this warning is trying to tell me.

1. What does it mean to "synchronize accesses"?

2. Why can't I pass the same object as reader and writer? The docstring in _pyio.py says, "This is typically used with a socket or two-way pipe."

3. How does BufferedRandom, which adds the seek() and tell() interfaces, address the issue of "synchroniz[ing] accesses"? Is synchronization automatic? What does this do for sockets or pipes which cannot seek?

----------
assignee: docs at python
components: Documentation
messages: 355404
nosy: docs at python, rgov
priority: normal
severity: normal
status: open
title: io.BufferedRWPair doc warning may need clarification
type: behavior
versions: Python 3.7

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