xdrlib — Кодирование и декодирование данных XDR

Исходный код: Lib/xdrlib.py

Модуль xdrlib поддерживает Стандарт внешнего представления данных, как описано в RFC 1014, написанный компанией Sun Microsystems, Inc. в июне 1987 года. Он поддерживает большинство типов данных, описанных в RFC.

Модуль xdrlib определяет два класса: один для упаковки переменных в представление XDR, а другой — для распаковки из представления XDR. Также существуют два класса исключений.

class xdrlib.Packer

Packer — класс для упаковки данных в представление XDR. Класс Packer инициализируется без аргументов.

class xdrlib.Unpacker(data)

Unpacker — дополнительный класс, который распаковывает значения данных XDR из буфера строк. Входной буфер передается как data.

1. Объекты Packer

Packer экземпляры имеют следующие методы:

Packer.get_buffer()

Возвращает текущий буфер упаковки в виде строки.

Packer.reset()

Сбрасывает буфер упаковки до пустой строки.

В общем случае, вы можете упаковать любой из наиболее распространенных типов данных XDR, вызвав соответствующий pack_type() метод. Каждый метод принимает один аргумент — значение для упаковки. Поддерживаются следующие методы упаковки простых типов данных: pack_uint(), pack_int(), pack_enum(), pack_bool(), pack_uhyper(), и pack_hyper().

Packer.pack_float(value)

Упаковывает число с плавающей запятой одинарной точности value.

Packer.pack_double(value)

Упаковывает число с плавающей запятой двойной точности value.

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

Packer.pack_fstring(n, s)

Упаковывает строку фиксированной длины s. n — длина строки, но она не упаковывается в буфер данных. Строка дополняется нулевыми байтами, если необходимо, для гарантированного выравнивания по 4 байтам.

Packer.pack_fopaque(n, data)

Упаковывает поток неструктурированных данных фиксированной длины, аналогично pack_fstring().

Packer.pack_string(s)

Упаковывает строку переменной длины s. Сначала упаковывается длина строки как целое без знака, затем данные строки упаковываются с помощью pack_fstring().

Packer.pack_opaque(data)

Упаковывает поток неструктурированных данных переменной длины, аналогично pack_string().

Packer.pack_bytes(bytes)

Упаковывает поток байтов переменной длины, аналогично pack_string().

Следующие методы поддерживают упаковку массивов и списков:

Packer.pack_list(list, pack_item)

Упаковывает список однородных элементов. Этот метод полезен для списков с неопределенным размером; т.е. размер доступен только после прохода по всему списку. Для каждого элемента списка сначала упаковывается целое без знака 1, а затем значение элемента из списка. pack_item — это функция, которая вызывается для упаковки каждого элемента. В конце списка упаковывается целое без знака 0.

Например, для упаковки списка целых чисел код может выглядеть так:

import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)

Packer.pack_farray(n, array, pack_item)

Упаковывает список фиксированной длины (массив) однородных элементов. n — длина списка; он не упаковывается в буфер, но исключение ValueError генерируется, если len(array) не равно n. Как и выше, pack_item используется для упаковки каждого элемента.

Packer.pack_array(list, pack_item)

Упаковывает список переменной длины список однородных элементов. Сначала упаковывается длина списка как целое без знака, затем каждый элемент упаковывается так же, как в pack_farray() выше.

2. Объекты Unpacker

Класс Unpacker предоставляет следующие методы:

Unpacker.reset(data)

Сбрасывает буфер строки с заданными данными.

Unpacker.get_position()

Возвращает текущую позицию распаковки в буфере данных.

Unpacker.set_position(position)

Устанавливает позицию распаковки буфера данных в position. Следует быть осторожным при использовании get_position() и set_position().

Unpacker.get_buffer()

Возвращает текущий буфер данных распаковки в виде строки.

Unpacker.done()

Указывает завершение распаковки. Генерирует исключение Error, если все данные не были распакованы.

Кроме того, каждый тип данных, который можно упаковать с помощью Packer, можно распаковать с помощью Unpacker. Методы распаковки имеют вид unpack_type(), и не принимают аргументов. Они возвращают распакованный объект.

Unpacker.unpack_float()

Распаковывает число с плавающей запятой одинарной точности.

Unpacker.unpack_double()

Распаковывает число с плавающей запятой двойной точности, аналогично unpack_float().

Кроме того, следующие методы распаковывают строки, байты и неструктурированные данные:

Unpacker.unpack_fstring(n)

Распаковывает и возвращает строку фиксированной длины. n — ожидаемое количество символов. Предполагается дополнение нулевыми байтами для гарантированного выравнивания по 4 байтам.

Unpacker.unpack_fopaque(n)

Распаковывает и возвращает поток неструктурированных данных фиксированной длины, аналогично unpack_fstring().

Unpacker.unpack_string()

Распаковывает и возвращает строку переменной длины. Сначала распаковывается длина строки как целое без знака, затем данные строки распаковываются с помощью unpack_fstring().

Unpacker.unpack_opaque()

Распаковывает и возвращает строку неструктурированных данных переменной длины, аналогично unpack_string().

Unpacker.unpack_bytes()

Распаковывает и возвращает поток байтов переменной длины, аналогично unpack_string().

Следующие методы поддерживают распаковку массивов и списков:

Unpacker.unpack_list(unpack_item)

Распаковывает и возвращает список однородных элементов. Список распаковывается по одному элементу за раз, сначала распаковывается целое без знака. Если флаг равен 1, элемент распаковывается и добавляется в список. Флаг 0 указывает на конец списка. unpack_item — это функция, которая вызывается для распаковки элементов.

Unpacker.unpack_farray(n, unpack_item)

Распаковывает и возвращает (в виде списка) массив фиксированной длины однородных элементов. n — количество элементов списка, ожидаемых в буфере. Как и выше, unpack_item — функция, используемая для распаковки каждого элемента.

Unpacker.unpack_array(unpack_item)

Распаковывает и возвращает список переменной длины однородных элементов. Сначала длина списка распаковывается как целое без знака, а затем каждый элемент распаковывается, как в unpack_farray() выше.

3. Исключение

Исключения в этом модуле закодированы как экземпляры классов:

exception xdrlib.Error

Базовый класс исключений. Error имеет единственное общедоступное свойство msg, содержащее описание ошибки.

exception xdrlib.ConversionError

Класс, производный от Error. Не содержит дополнительных переменных экземпляра.

Вот пример того, как можно перехватить одно из этих исключений:

import xdrlib
p = xdrlib.Packer()
try:
    p.pack_double(8.01)
except xdrlib.ConversionError as instance:
    print 'packing the double failed:', instance.msg