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

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

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

class xdrlib.Packer

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

class xdrlib.Unpacker(data)

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

См.также

RFC 1014 — XDR: Стандарт внешнего представления данных
RFC определил кодировку данных, которая была XDR в то время, когда этот модуль был первоначально написан. По-видимому, он был устаревшим RFC 1832.
RFC 1832 — XDR: Стандарт представления внешних данных
Более новый RFC, предлагающий пересмотренное определение XDR.

Объекты-упаковщики

Для экземпляров 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)

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

Объекты распаковщика

Класс 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)

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