codecs.StreamWriter.write() returns None

[srittau]

Bug report

Bug description:

This violates the usual write() contract of returning the number of items written (for synchronous I/O) and also affects StreamReaderWriter.write() transitively.

In this case it seems trivial to just return the result of the called self.stream.write().

CPython versions tested on:

CPython main branch

Operating systems tested on:

No response

Linked PRs

• gh-134706: Return bytes written from codecs.Stream(Reader)Writer.write() #134708

[malemburg]

Copied here from the discussion on the PR...

I have thought a bit more about this PR and "bug" report:

• First, the contract you are seeing is really just an implementation detail of the io module in Python 3. In Python 2, file.write() returned None, just like the StreamWriter does. Remember that StreamWriter was designed and added in the Python 2 days. There is no general concept of having write methods return the number of bytes written in Python. What you describe as a bug, is really not a bug, but a feature request.

• Since write methods can be had on many stream-like objects, it is not clear whether they should return number of bytes written, number of code points written, number of items written, etc. This depends a lot on context. You can see that the io module chose to return number of code points for TextIOBase, but number of bytes for everything else. In some context, having access to the number of bytes written may make sense (e.g. if buffering is applied or a retry operation is underway), but in most cases, such information is better left with the stream and you can access this via stream APIs.

• Returning the number of code points passed in to the method is not useful information, since the codec's encoder may not really have written all of them to the stream. If at all, the write methods should always return number of bytes written or None if that information is not available, to make the return value useful.

• Finally, you are proposing a change to a base class that is being subclassed by lots of codecs out there. We don't control all codecs using it (only the ones in the stdlib), so a change to a base class method will not propogate as you probably expect. Subclasses can continue to return None or return something else (e.g. number of code points, bytes or items). The return value of the StreamWriter.write() method is not defined. If we now do define a value, code will break, since other code will start assuming that such a return value is always to be expected.

• Aside: Please also recognize that StreamWriter instances can work on many different stream objects, not just the ones provided by the io module. They are using the codec encoders to write data to the stream and only rely on a minimal stream API for this purpose.

Given all this, I'm not in favor of the change and will close the PR and ticket.

[malemburg]

Update the close reason...