xdrlib — Кодування та декодування даних XDR

Вихідний код: Lib/xdrlib.py

Застаріло з версії 3.11, буде видалено у версії 3.13: Модуль xdrlib є застарілим (докладніше див. PEP 594).

Модуль xdrlib підтримує стандарт представлення зовнішніх даних, як описано в RFC 1014, написаному Sun Microsystems, Inc. червень 1987 року. Він підтримує більшість типів даних, описаних у RFC.

Модуль xdrlib визначає два класи: один для пакування змінних у представлення XDR, а інший для розпакування з представлення XDR. Є також два класи винятків.

class xdrlib.Packer

Packer — це клас для упаковки даних у представлення XDR. Клас Packer створюється без аргументів.

class xdrlib.Unpacker(data)

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

Дивись також

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)

Пакує значення числа з плаваючою комою одинарної точності.

Packer.pack_double(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.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)