14.4. xdrlib – кодирование и декодирование данных XDR¶xdrlib – Encode and decode XDR data

14.4.1. Объекты Packer¶Packer Objects

Экземпляры 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)¶

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

Packer.pack_array(list, pack_item)¶

Упаковывает список переменной длины list однородных элементов. Сначала длина списка упаковывается как беззнаковое целое, затем каждый элемент упаковывается, как в pack_farray() выше.

14.4.2. Объекты Unpacker¶Unpacker Objects

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

Распаковывает и возвращает список list переменной длины из однородных элементов. Сначала длина списка распаковывается как беззнаковое целое, затем каждый элемент распаковывается, как в unpack_farray() выше.

14.4.3. Исключения¶Exceptions

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

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)