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.

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.

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

Packer.pack_fstring(n, s)

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

Packer.pack_fopaque(n, data)

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

Packer.pack_string(s)

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

Packer.pack_opaque(data)

Упаковывает поток данных переменной длины opaque, аналогично 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)

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

Packer.pack_array(list, pack_item)

Упаковывает список переменной длины list однородных элементов. Сначала упаковывается длина списка как целое без знака, затем каждый элемент упаковывается так же, как в 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().

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

Unpacker.unpack_fstring(n)

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

Unpacker.unpack_fopaque(n)

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

Unpacker.unpack_string()

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

Unpacker.unpack_opaque()

Распаковывает и возвращает строку 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)