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

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

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

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

class xdrlib.Packer

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

class xdrlib.Unpacker(data)

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

14.4.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() выше.

14.4.2. Объекты Unpacker

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

Unpacker.reset(data)

Сбрасывает буфер строки с заданными 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() выше.

14.4.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)