This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: codecs.StreamWriter.reset contract not fulfilled
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jim.Jewett, berker.peksag, cheryl.sabella, docs@python, ezio.melotti, lemburg, martin.panter, miss-islington
Priority: normal Keywords: patch

Created on 2012-02-14 18:01 by Jim.Jewett, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
Issue14014.diff BreamoreBoy, 2014-07-03 13:50 patch file with Jim's suggestion. review
Pull Requests
URL Status Linked Edit
PR 13716 merged berker.peksag, 2019-06-01 04:42
PR 24136 merged miss-islington, 2021-01-06 02:14
Messages (10)
msg153354 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2012-02-14 18:01
def reset(self):

        """ Flushes and resets the codec buffers used for keeping state.

            Calling this method should ensure that the data on the
            output is put into a clean state, that allows appending
            of new fresh data without having to rescan the whole
            stream to recover state.

        """
        pass

This does not ensure that the stream is flushed, as the docstring promises.  I believe the following would work better.


    def reset(self):
        """ Flushes and resets the codec buffers used for keeping state.

            Calling this method should ensure that the data on the
            output is put into a clean state, that allows appending
            of new fresh data without having to rescan the whole
            stream to recover state.

        """
        if hasattr(self.stream, "flush"): self.stream.flush()
msg222178 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-07-03 13:50
On Windows 7 206 codecs tests passed and 4 skipped with the patch included.
msg233988 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-14 01:21
I don’t think this is appropriate. If you want to flush the underlying stream, then call its flush() method after calling reset(). The docstring only says it flushes the _codec’s_ buffers, not any buffers of the underlying stream, and it should not be the codec’s business to worry about lower level buffers.
msg233994 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2015-01-14 01:37
That sounds like a bug magnet to me; my mental model is that the codec
is my output; flushing it will push things out, and resetting it will
erase anything pending.  I don't care if some implementation detail
means that some other object technically owns the buffer.

An alternative (inferior, but better than nothing) would be to add an
explicit note warning users that reset won't really finish the job,
and they have to also get the codec's underlying stream and flush
that.  (Of course, if the stream is really an abstraction over the
real stream ... at what point does the delegation start to work on its
own?)

On Tue, Jan 13, 2015 at 8:21 PM, Martin Panter <report@bugs.python.org> wrote:
>
> Martin Panter added the comment:
>
> I don’t think this is appropriate. If you want to flush the underlying stream, then call its flush() method after calling reset(). The docstring only says it flushes the _codec’s_ buffers, not any buffers of the underlying stream, and it should not be the codec’s business to worry about lower level buffers.
>
> ----------
> nosy: +vadmium
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue14014>
> _______________________________________
msg233999 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-14 02:26
Maybe it would be better to redefine the docstring to say it flushes the codec as well as calling flush() on the underlying stream.

But if you really want to finish the job you should probably be closing the underlying stream, which would flush if necessary. See Issue 460474, for adding a close() method which invokes reset().
msg234014 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2015-01-14 08:34
On 14.01.2015 02:21, Martin Panter wrote:
> 
> Martin Panter added the comment:
> 
> I don’t think this is appropriate. If you want to flush the underlying stream, then call its flush() method after calling reset(). The docstring only says it flushes the _codec’s_ buffers, not any buffers of the underlying stream, and it should not be the codec’s business to worry about lower level buffers.

Correct. That's the reason why the method is called .reset() and
not .flush().
msg234015 - (view) Author: Marc-Andre Lemburg (lemburg) * (Python committer) Date: 2015-01-14 08:41
Adding a note to the documentation is fine.

The .reset() method doesn't have anything to do with the underlying
stream. It's only meant to work at the codec level and needed for
codecs that keep internal state.
msg359849 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2020-01-12 14:21
@lemburg, when you get a chance, please review the PR.  Thanks!
msg384464 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2021-01-06 02:14
New changeset 1a9f51ed12feb4d95ad6d0faf610a030c05b9f5e by Berker Peksag in branch 'master':
bpo-14014: Clarify StreamWriter.reset() documentation (GH-13716)
https://github.com/python/cpython/commit/1a9f51ed12feb4d95ad6d0faf610a030c05b9f5e
msg384465 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2021-01-06 02:27
New changeset a3ca6747f50efa2fe59caf516a26b0fd1912b8e8 by Miss Islington (bot) in branch '3.9':
bpo-14014: Clarify StreamWriter.reset() documentation (GH-13716)
https://github.com/python/cpython/commit/a3ca6747f50efa2fe59caf516a26b0fd1912b8e8
History
Date User Action Args
2022-04-11 14:57:26adminsetgithub: 58222
2021-01-06 02:29:17berker.peksagsetnosy: + docs@python, - vstinner
components: - Unicode
assignee: docs@python
2021-01-06 02:28:46berker.peksagsetstatus: open -> closed
assignee: lemburg -> (no value)
components: + Documentation
versions: + Python 3.10, - Python 3.8
nosy: + vstinner

resolution: fixed
stage: patch review -> resolved
2021-01-06 02:27:38berker.peksagsetmessages: + msg384465
2021-01-06 02:14:57miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request22966
2021-01-06 02:14:48berker.peksagsetnosy: + berker.peksag
messages: + msg384464
2020-01-15 21:55:07vstinnersetnosy: - vstinner
2020-01-12 14:21:05cheryl.sabellasetversions: + Python 3.8, Python 3.9, - Python 3.4, Python 3.5
nosy: + cheryl.sabella

messages: + msg359849

assignee: lemburg
2019-06-01 04:42:29berker.peksagsetstage: patch review
pull_requests: + pull_request13603
2019-04-26 17:22:45BreamoreBoysetnosy: - BreamoreBoy
2015-01-14 08:41:11lemburgsetmessages: + msg234015
2015-01-14 08:34:47lemburgsetnosy: + lemburg
messages: + msg234014
2015-01-14 02:26:56martin.pantersetmessages: + msg233999
2015-01-14 01:37:23Jim.Jewettsetmessages: + msg233994
2015-01-14 01:21:18martin.pantersetnosy: + martin.panter
messages: + msg233988
2014-07-03 13:50:55BreamoreBoysetfiles: + Issue14014.diff
versions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
nosy: + BreamoreBoy

messages: + msg222178

keywords: + patch
2012-02-15 00:13:19pitrousetnosy: + vstinner

versions: + Python 3.3
2012-02-14 18:01:53Jim.Jewettcreate