16.4. codecs - регистрация кодеров и работа с ними 233

register(search function)

Регистрирует search function как функцию для поиска кодеров. Функция search function вызывается с одним аргументом - именем кодировки, записанной строчными буквами, и должна возвращать кортеж объектов, поддерживающих вызов, (encoder, decoder, stream reader, stream writer) . encoder и decoder должны иметь интерфейс, аналогичный методам encode() и decode() экземпляров класса Codec, описанного ниже. stream reader и stream writer должны быть конструкторами, возвращающими объекты аналогичные экземплярам классов StreamReader и StreamWriter соответственно. Если search function не может найти объекты для данной кодировки, она должна вернуть None.

lookup( encoding)

Ищет в реестре кодеров средства работы с кодировкой encoding и возвращает кортеж объектов (encoder, decoder, stream reader, stream writer) , описанный выше. Если объекты для данной кодировки не найдены, генерируется исключение LookupError.

Для упрощения работы с файлами и другими потоками, содержащими данные в определенной кодировке, модуль определяет следующие функции:

open( filename [, mode [, encoding [, errors

[, buffering]]]])

Открывает файл с именем filename в кодировке encoding и возвращает файловый объект (экземпляр класса StreamReaderWriter, описанного ниже), обеспечивающий прозрачное кодирование/декодирование данных при записи/чтении. Аргумент mode указывает режим, в котором открывается файл (по умолчанию используется rb ). Во избежание потери данных файл всегда открывается в двоичном режиме. Аргумент errors определяет поведение при ошибках и может иметь значения strict (в случае возникновения ошибки генерируется исключение ValueError или производного от него класса; используется по умолчанию), ignore (ошибки игнорируются) или replace (используется подходящий символ замены, обычно \uFFFD). Аргумент buffering имеет такое же значение, как и для встроенной функции open() .

EncodedFile( file, input [, output , [errors]])

Возвращает файловый объект (экземпляр класса StreamRecoder, описанного ниже), обеспечивающий прозрачное перекодирование при работе с потоком file (файловый объект). Данные в файле хранятся в кодировке output , в то время как строки передаваемые методам write() и writelines() и возвращаемые методами read() , readline() и readlines() содержат данные в кодировке input . В качестве промежуточной кодировки обычно используется Unicode. Если кодировка output не задана, она считается равной input . Аргумент errors имеет такое же значение, как и для функции open() .

Модуль определяет следующие классы, которые могут быть использованы в качестве базовых:

Codec ()

Базовый класс для кодеров/декодеров. Производные от него классы должны реализовать следующие методы:

encode (input [, errors])

Должен возвращать кортеж из строки, полученной при кодировании input, и количества обработанных символов.

decode( input [, errors])

Должен возвращать кортеж из строки, полученной при раскодировании input , и количества обработанных символов.

StreamWriter (stream [, errors])

Базовый класс для файловых объектов, обеспечивающих прозрачное кодирование данных при записи его в поток stream. Этот класс является производным от класса Codec и использует для кодирования свой метод encode() , который должен быть переопределен в производном классе.

StreamReader( stream [, errors])

Базовый класс для файловых объектов, обеспечивающих прозрачное декодирование данных при чтении их из потока stream. Этот класс является производным от класса Codec и использует для декодирования свой метод decode() , который должен быть переопределен в производном классе.

Для упрощения реализации методов encode() и decode() классов, производных от Codec, могут быть полезны следующие функции:

charmap encode(input, errors, encoding map)

Кодирует строку input, используя отображение кодов символов encoding map. Возвращает результат в том виде, в котором должен возвращать метод encode() .

charmap decode( input, errors, encoding map)

Декодирует строку input, используя отображение кодов символов encoding map. Возвращает результат в том виде, в котором должен возвращать метод decode() .

Хорошими примерами использования описанных выше классов могут служить исходные тексты модулей пакета encodings.

Экземпляры приведенных ниже классов возвращаются функциями open() и EncodedFile() :

StreamReaderWriter (stream, Reader, Writer [, errors])

Создает файловый объект, обеспечивающий доступ на чтение с кодированием (через объект Reader( stream, errors) ) и запись с декодированием (через объект Writer( stream, errors) ) к потоку stream.

16.4. codecs - регистрация кодеров и работа с ними 235

StreamRecoder(stream, encode, decode, Reader, Writer [, errors])

Экземпляры этого класса обеспечивают прозрачное перекодирование при работе с потоком file (файловый объект). Данные в файле хранятся в кодировке output , в то время как строки передаваемые методам write() и writelines() и возвращаемые методами read() , readline() и readlines() содержат данные в кодировке input .

Следующие константы могут быть полезны при чтении и записи файлов, формат которых зависит от платформы:

BOM BE

BOM LE

BOM32 BE

BOM32 LE

BOM64 BE

BOM64 LE

Эти константы определяют метки, которые используются для обозначения порядка следования байтов (byte order mark, BOM). Константа BOM равна B0M BE или B0M LE и определяет "родной" порядок следования для данной платформы. Суффиксы be и le обозначают соответственно big-endian и little-endian.