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.

Объекты 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() выше.

Объекты 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() выше.

Исключения

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

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)