The StreamReader class is a subclass of Codec and defines the following methods which every stream reader must define in order to be compatible to the Python codec registry.
All stream readers must provide this constructor interface. They are free to add additional keyword arguments, but only the ones defined here are used by the Python codec registry.
stream must be a file-like object open for reading (binary) data.
The StreamReader may implement different error handling schemes by providing the errors keyword argument. These parameters are defined:
'strict'Raise ValueError (or a subclass); this is the default.
'ignore'Ignore the character and continue with the next.
'replace'Replace with a suitable replacement character.
size indicates the approximate maximum number of bytes to read from the stream for decoding purposes. The decoder can modify this setting as appropriate. The default value -1 indicates to read and decode as much as possible. size is intended to prevent having to decode huge files in one step.
The method should use a greedy read strategy meaning that it should read as much data as is allowed within the definition of the encoding and the given size, e.g. if optional encoding endings or state markers are available on the stream, these should be read too.
Unlike the readlines() method, this method inherits the line breaking knowledge from the underlying stream's readline() method - there is currently no support for line breaking using the codec decoder due to lack of line buffering. Sublcasses should however, if possible, try to implement this method using their own knowledge of line breaking.
size, if given, is passed as size argument to the stream's readline() method.
Line breaks are implemented using the codec's decoder method and are included in the list entries.
sizehint, if given, is passed as size argument to the stream's read() method.
Note that no stream repositioning should take place. This method is primarily intended to be able to recover from decoding errors.
In addition to the above methods, the StreamReader must also inherit all other methods and attribute from the underlying stream.
The next two base classes are included for convenience. They are not needed by the codec registry, but may provide useful in practice.
See About this document... for information on suggesting changes.