"xdrlib" --- Codificar y decodificar datos XDR
**********************************************

**Código fuente:** Lib/xdrlib.py

Obsoleto desde la versión 3.11, se eliminará en la versión 3.13: El
"xdrlib" modulo se descontinuó (ver **PEP 594** para más información).

======================================================================

El módulo "xdrlib" soporta el estándar de representación externa de
datos (*External Data Representation Standard*) como se describe en
**RFC 1014**, escrito por Sun Microsystems, Inc. en junio de 1987.
Soporta la mayoría de los tipos de datos descritos en el RFC.

El módulo "xdrlib" define dos clases, una para empaquetar variables en
la representación XDR, y otra para desempaquetar valores de la
representación XDR. También hay dos clases de excepciones.

class xdrlib.Packer

   "Packer" es la clase para empaquetar datos en la representación
   XDR. La clase "Packer" es instanciada sin argumentos.

class xdrlib.Unpacker(data)

   "Unpacker" es la clase complementaria que desempaqueta los valores
   de datos XDR de un búfer de cadena.  El búfer de entrada se
   proporciona como *data*.

Ver también:

  **RFC 1014** - XDR: estándar de representación externa de datos
     Este RFC definió la codificación de datos que era XDR en el
     momento en que este módulo fue escrito originalmente.
     Aparentemente ha quedado obsoleto, siendo reemplazado por **RFC
     1832**.

  **RFC 1832** - XDR: estándar de representación externa de datos
     El RFC más reciente que proporciona una definición revisada de
     XDR.


Instancias de la clase *Packer*
===============================

Las instancias de la clase "Packer" poseen los siguientes métodos:

Packer.get_buffer()

   Retorna el búfer del paquete actual como una cadena de caracteres.

Packer.reset()

   Restablece el búfer del paquete a la cadena de caracteres vacía.

En general, puedes empaquetar cualquiera de los tipos de datos XDR más
comunes, invocando el método "pack_tipo()" apropiado.  Cada método
toma un solo argumento, el valor a empaquetar.  Los siguientes métodos
simples de empaquetado de tipos de datos son soportados:
"pack_uint()", "pack_int()", "pack_enum()", "pack_bool()",
"pack_uhyper()", y "pack_hyper()".

Packer.pack_float(value)

   Empaqueta el número de punto flotante de precisión simple, *value*.

Packer.pack_double(value)

   Empaqueta el número de punto flotante de doble precisión, *value*.

Los siguientes métodos soportan el empaquetado de cadenas de
caracteres, bytes y datos opacos:

Packer.pack_fstring(n, s)

   Empaqueta una cadena de caracteres de longitud fija, *s*.  *n* es
   la longitud de la cadena de caracteres pero *no* es empaquetada en
   el búfer de datos.  La cadena de caracteres es rellenada con bytes
   nulos si es necesario, para garantizar que la longitud de los datos
   sea un múltiplo de 4 bytes.

Packer.pack_fopaque(n, data)

   Empaqueta un flujo de datos opaco de longitud fija, similar a
   "pack_fstring()".

Packer.pack_string(s)

   Empaqueta una cadena de caracteres de longitud variable, *s*.  En
   primer lugar, la longitud de la cadena de caracteres es empaquetada
   como un entero sin signo, luego los datos de la cadena de
   caracteres son empaquetados con "pack_fstring()".

Packer.pack_opaque(data)

   Empaqueta una cadena de caracteres de datos opacos de longitud
   variable, similar a "pack_string()".

Packer.pack_bytes(bytes)

   Empaqueta una secuencia de bytes de longitud variable, similar a
   "pack_string()".

Los siguientes métodos soportan el empaquetamiento de arreglos y
listas:

Packer.pack_list(list, pack_item)

   Empaqueta una *lista* de elementos homogéneos.  Este método es útil
   para listas con longitud indeterminada; en otras palabras, el
   tamaño no está disponible hasta que se haya recorrido toda la
   lista.  Para cada elemento de la lista, un entero sin signo "1" se
   empaqueta primero, seguido del valor de datos de la lista.
   *pack_item* es la función que se llama para empaquetar el elemento
   individual.  Al final de la lista, se empaqueta un entero sin signo
   "0".

   Por ejemplo, para empaquetar una lista de enteros, el código podría
   parecerse a esto:

      import xdrlib
      p = xdrlib.Packer()
      p.pack_list([1, 2, 3], p.pack_int)

Packer.pack_farray(n, array, pack_item)

   Empaqueta una lista (*arreglo*) de elementos homogéneos de longitud
   fija.  *n* es la longitud de la lista; *no* es empaquetada en el
   búfer, pero una excepción "ValueError" es lanzada si "len(array)"
   no es igual a *n*.  Al igual que en el método anterior, *pack_item*
   es la función usada para empaquetar cada elemento.

Packer.pack_array(list, pack_item)

   Empaqueta una *lista* de elementos homogéneos de longitud variable.
   Primero, la longitud de la lista es empaquetada como un entero sin
   signo, luego cada elemento es empaquetado como en el método
   "pack_farray()" de arriba.


Instancias de la clase *Unpacker*
=================================

La clase "Unpacker" ofrece los siguientes métodos:

Unpacker.reset(data)

   Restablece el búfer de cadena de caracteres a la *data*
   especificada.

Unpacker.get_position()

   Retorna la posición actual desempaquetada en el búfer de datos.

Unpacker.set_position(position)

   Establece la posición de desempaquetado del búfer de datos en la
   posición *position*. Debes tener cuidado al usar los métodos
   "get_position()" y "set_position()".

Unpacker.get_buffer()

   Retorna el búfer de datos actual desempaquetado como una cadena de
   caracteres.

Unpacker.done()

   Indica se ha completado el proceso de desempaquetado.  Lanza una
   excepción "Error" si no se han desempaquetado todos los datos.

Además, cada tipo de datos que puede ser empaquetados con un "Packer",
puede ser desempaquetado con un "Unpacker".  Los métodos de
desempaquetados son de la forma "unpack_tipo()", y no tienen
argumentos.  Estos retornan el objeto desempaquetado.

Unpacker.unpack_float()

   Desempaqueta un número de punto flotante de precisión simple.

Unpacker.unpack_double()

   Desempaqueta un número de punto flotante de doble precisión,
   similar a "unpack_float()".

Adicionalmente, los siguientes métodos desempaquetan cadenas de
caracteres, bytes y datos opacos:

Unpacker.unpack_fstring(n)

   Desempaqueta y retorna una cadena de caracteres de longitud fija.
   *n* es el número de caracteres esperados.  Se asume un relleno con
   bytes nulos hasta que la longitud de los datos sea un múltiplo de 4
   bytes.

Unpacker.unpack_fopaque(n)

   Desempaqueta y retorna un flujo de datos opaco de longitud fija,
   similar a "unpack_fstring()".

Unpacker.unpack_string()

   Desempaqueta y retorna una cadena de caracteres de longitud
   variable.  La longitud de la cadena de caracteres es desempaquetada
   primero como un entero sin signo, luego los datos de la cadena de
   caracteres son desempaquetados con el método "unpack_fstring()".

Unpacker.unpack_opaque()

   Desempaqueta y retorna un flujo de datos opaco de longitud
   variable, similar a "unpack_string()".

Unpacker.unpack_bytes()

   Desempaqueta y retorna una secuencia de bytes de longitud variable,
   similar a "unpack_string()".

Los siguientes métodos soportan el desempaquetado de arreglos y
listas:

Unpacker.unpack_list(unpack_item)

   Desempaqueta y retorna una lista de elementos homogéneos.  La lista
   se desempaqueta un elemento a la vez desempaquetando primero un
   indicador entero sin signo.  Si el flag es "1", el elemento se
   desempaqueta y se agrega a la lista.  Un flag de "0" indica el
   final de la lista.  *unpack_item* es la función a la que se invoca
   para desempaquetar los elementos.

Unpacker.unpack_farray(n, unpack_item)

   Desempaqueta y retorna (como una lista) un arreglo de elementos
   homogéneos de longitud fija.  *n* es el número de elementos de la
   lista que se esperan en el búfer. Como se mostró anteriormente,
   *unpack_item* es la función empleada para desempaquetar cada
   elemento.

Unpacker.unpack_array(unpack_item)

   Desempaqueta y retorna una *lista* de elementos homogéneos de
   longitud variable. En primer lugar, la longitud de la lista se
   desempaqueta como un entero sin signo, luego cada elemento se
   desempaqueta como en el método "unpack_farray()" de arriba.


Excepciones
===========

En este módulo, las excepciones se codifican como instancias de clase:

exception xdrlib.Error

   La clase de excepción base.  "Error" tiene un único atributo
   público, "msg", que contiene la descripción del error.

exception xdrlib.ConversionError

   Clase derivada de "Error".  No contiene variables de instancia
   adicionales.

A continuación se muestra un ejemplo de cómo detectarías una de estas
excepciones:

   import xdrlib
   p = xdrlib.Packer()
   try:
       p.pack_double(8.01)
   except xdrlib.ConversionError as instance:
       print('packing the double failed:', instance.msg)
