7.2. codecs — 编解码器注册和基类 ¶

7.2.1.3.1. IncrementalEncoder 对象 ¶

IncrementalEncoder class is used for encoding an input in multiple steps. It defines the following methods which every incremental encoder must define in order to be compatible with the Python codec registry.

class codecs. IncrementalEncoder ( errors='strict' ) ¶

构造函数为 IncrementalEncoder 实例。

All incremental encoders 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.

IncrementalEncoder may implement different error handling schemes by providing the errors keyword argument. See 错误处理程序 了解可能值。

errors argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error handling strategies during the lifetime of the IncrementalEncoder 对象。

encode ( object [ , final ] ) ¶

编码 object (taking the current state of the encoder into account) and returns the resulting encoded object. If this is the last call to encode() final must be true (the default is false).

reset ( ) ¶

Reset the encoder to the initial state. The output is discarded: call .encode(object, final=True) , passing an empty byte or text string if necessary, to reset the encoder and to get the output.

getstate ( ) ¶

Return the current state of the encoder which must be an integer. The implementation should make sure that 0 is the most common state. (States that are more complicated than integers can be converted into an integer by marshaling/pickling the state and encoding the bytes of the resulting string into an integer).

setstate ( state ) ¶

Set the state of the encoder to state . state must be an encoder state returned by getstate() .

7.2.1.3.2. IncrementalDecoder 对象 ¶

IncrementalDecoder class is used for decoding an input in multiple steps. It defines the following methods which every incremental decoder must define in order to be compatible with the Python codec registry.

class codecs. IncrementalDecoder ( errors='strict' ) ¶

构造函数为 IncrementalDecoder 实例。

All incremental decoders 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.

IncrementalDecoder may implement different error handling schemes by providing the errors keyword argument. See 错误处理程序 了解可能值。

errors argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error handling strategies during the lifetime of the IncrementalDecoder 对象。

decode ( object [ , final ] ) ¶

解码 object (taking the current state of the decoder into account) and returns the resulting decoded object. If this is the last call to decode() final must be true (the default is false). If final is true the decoder must decode the input completely and must flush all buffers. If this isn’t possible (e.g. because of incomplete byte sequences at the end of the input) it must initiate error handling just like in the stateless case (which might raise an exception).

reset ( ) ¶

将解码器重置到初始状态。

getstate ( ) ¶

Return the current state of the decoder. This must be a tuple with two items, the first must be the buffer containing the still undecoded input. The second must be an integer and can be additional state info. (The implementation should make sure that 0 is the most common additional state info.) If this additional state info is 0 it must be possible to set the decoder to the state which has no input buffered and 0 as the additional state info, so that feeding the previously buffered input to the decoder returns it to the previous state without producing any output. (Additional state info that is more complicated than integers can be converted into an integer by marshaling/pickling the info and encoding the bytes of the resulting string into an integer.)

setstate ( state ) ¶

Set the state of the encoder to state . state must be a decoder state returned by getstate() .

7.2.1.4.1. StreamWriter 对象 ¶

StreamWriter 类是子类化的 Codec and defines the following methods which every stream writer must define in order to be compatible with the Python codec registry.

class codecs. StreamWriter ( stream , errors='strict' ) ¶

构造函数为 StreamWriter 实例。

All stream writers 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 argument must be a file-like object open for writing text or binary data, as appropriate for the specific codec.

StreamWriter may implement different error handling schemes by providing the errors keyword argument. See 错误处理程序 for the standard error handlers the underlying stream codec may support.

errors argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error handling strategies during the lifetime of the StreamWriter 对象。

write ( object ) ¶

Writes the object’s contents encoded to the stream.

writelines ( list ) ¶

Writes the concatenated list of strings to the stream (possibly by reusing the write() method). The standard bytes-to-bytes codecs do not support this method.

reset ( ) ¶

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.

In addition to the above methods, the StreamWriter must also inherit all other methods and attributes from the underlying stream.

7.2.1.4.2. StreamReader 对象 ¶

StreamReader 类是子类化的 Codec and defines the following methods which every stream reader must define in order to be compatible with the Python codec registry.

class codecs. StreamReader ( stream , errors='strict' ) ¶

构造函数为 StreamReader 实例。

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 argument must be a file-like object open for reading text or binary data, as appropriate for the specific codec.

StreamReader may implement different error handling schemes by providing the errors keyword argument. See 错误处理程序 for the standard error handlers the underlying stream codec may support.

errors argument will be assigned to an attribute of the same name. Assigning to this attribute makes it possible to switch between different error handling strategies during the lifetime of the StreamReader 对象。

The set of allowed values for the errors argument can be extended with register_error() .

read ( [ size [ , chars [ , firstline ] ] ] ) ¶

Decodes data from the stream and returns the resulting object.

chars argument indicates the number of decoded code points or bytes to return. The read() method will never return more data than requested, but it might return less, if there is not enough available.

size argument indicates the approximate maximum number of encoded bytes or code points to read for decoding. The decoder can modify this setting as appropriate. The default value -1 indicates to read and decode as much as possible. This parameter is intended to prevent having to decode huge files in one step.

firstline flag indicates that it would be sufficient to only return the first line, if there are decoding errors on later lines.

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.

readline ( [ size [ , keepends ] ] ) ¶

Read one line from the input stream and return the decoded data.

size , if given, is passed as size argument to the stream’s read() 方法。

若 keepends is false line-endings will be stripped from the lines returned.

readlines ( [ sizehint [ , keepends ] ] ) ¶

Read all lines available on the input stream and return them as a list of lines.

Line-endings are implemented using the codec’s decoder method and are included in the list entries if keepends 为 true。

sizehint , if given, is passed as the size argument to the stream’s read() 方法。

reset ( ) ¶

Resets the codec buffers used for keeping state.

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 attributes from the underlying stream.

7.2.1.4.3. StreamReaderWriter 对象 ¶

StreamReaderWriter is a convenience class that allows wrapping streams which work in both read and write modes.

The design is such that one can use the factory functions returned by the lookup() function to construct the instance.

class codecs. StreamReaderWriter ( stream , Reader , Writer , errors='strict' ) ¶

创建 StreamReaderWriter 实例。 stream must be a file-like object. Reader and Writer must be factory functions or classes providing the StreamReader and StreamWriter interface resp. Error handling is done in the same way as defined for the stream readers and writers.

StreamReaderWriter instances define the combined interfaces of StreamReader and StreamWriter classes. They inherit all other methods and attributes from the underlying stream.

7.2.1.4.4. StreamRecoder 对象 ¶

StreamRecoder translates data from one encoding to another, which is sometimes useful when dealing with different encoding environments.

The design is such that one can use the factory functions returned by the lookup() function to construct the instance.

class codecs. StreamRecoder ( stream , encode , decode , Reader , Writer , errors='strict' ) ¶

创建 StreamRecoder instance which implements a two-way conversion: encode and decode work on the frontend — the data visible to code calling read() and write() ，而 Reader and Writer work on the backend — the data in stream .

You can use these objects to do transparent transcodings from e.g. Latin-1 to UTF-8 and back.

stream 自变量必须是像文件对象。

encode and decode arguments must adhere to the Codec 接口。 Reader and Writer must be factory functions or classes providing objects of the StreamReader and StreamWriter interface respectively.

Error handling is done in the same way as defined for the stream readers and writers.

StreamRecoder instances define the combined interfaces of StreamReader and StreamWriter classes. They inherit all other methods and attributes from the underlying stream.