Make TextIOWrapper's seek/tell work properly with stateful decoders;
document and rename things to make seek/tell workings a little clearer.
Add a weird decoder for testing TextIOWrapper's seek/tell methods.
Document the getstate/setstate protocol conventions for IncrementalDecoders.
diff --git a/Lib/codecs.py b/Lib/codecs.py
index 6d8d554..f05c4f7 100644
--- a/Lib/codecs.py
+++ b/Lib/codecs.py
@@ -237,7 +237,7 @@
"""
def __init__(self, errors='strict'):
"""
- Creates a IncrementalDecoder instance.
+ Create a IncrementalDecoder instance.
The IncrementalDecoder may use different error handling schemes by
providing the errors keyword argument. See the module docstring
@@ -247,28 +247,35 @@
def decode(self, input, final=False):
"""
- Decodes input and returns the resulting object.
+ Decode input and returns the resulting object.
"""
raise NotImplementedError
def reset(self):
"""
- Resets the decoder to the initial state.
+ Reset the decoder to the initial state.
"""
def getstate(self):
"""
- Return the current state of the decoder. This must be a
- (buffered_input, additional_state_info) tuple. By convention,
- additional_state_info should represent the state of the decoder
- WITHOUT yet having processed the contents of buffered_input.
+ Return the current state of the decoder.
+
+ This must be a (buffered_input, additional_state_info) tuple.
+ buffered_input must be a bytes object containing bytes that
+ were passed to decode() that have not yet been converted.
+ additional_state_info must be a non-negative integer
+ representing the state of the decoder WITHOUT yet having
+ processed the contents of buffered_input. In the initial state
+ and after reset(), getstate() must return (b"", 0).
"""
return (b"", 0)
def setstate(self, state):
"""
- Set the current state of the decoder. state must have been
- returned by getstate().
+ Set the current state of the decoder.
+
+ state must have been returned by getstate(). The effect of
+ setstate((b"", 0)) must be equivalent to reset().
"""
class BufferedIncrementalDecoder(IncrementalDecoder):