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.

См.также

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)