"plistlib" --- Genera y analiza archivos ".plist" de Mac OS X
*************************************************************

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

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

Este módulo provee una interfaz para lectura y escritura de archivos
de "listas de propiedades" usados principalmente por Mac OS X y
soporta tanto archivos plist binarios como XML.

El formato de lista de propiedades (".plist") es una serialización
simple que soporta tipos de objetos básicos, como diccionarios,
listas, números y cadenas. Generalmente el objeto de nivel superior es
un diccionario.

Para escribir y analizar un archivo plist usa las funciones "dump()" y
"load()".

Para trabajar con datos plist en objetos de bytes usa "dumps()" y
"loads()".

Los valores pueden ser cadenas de caracteres, enteros, coma flotantes,
booleanos, tuplas, listas, diccionarios (pero sólo con cadenas como
claves), "Data", "bytes", "bytesarray" u objetos "datetime.datetime".

Distinto en la versión 3.4: Nueva API, API antigua obsoleta. Añadido
soporte para plists en formato binario.

Distinto en la versión 3.8: Añadido soporte para lectura y escritura
de tokens "UID" en plists binarios como lo usan NSKeyedArchiver y
NSKeyedUnarchiver.

Ver también:

  Página del manual PList
     Documentación de Apple del formato de archivo.

Este módulo define las siguientes funciones:

plistlib.load(fp, *, fmt=None, use_builtin_types=True, dict_type=dict)

   Lee un archivo plist. *fp* debe ser un objeto de archivo binario y
   legible. Retorna el objeto raíz desempaquetado (el cual
   generalmente es un diccionario).

   El *fmt* es el formato del archivo y los siguientes valores son
   válidos:

   * "None": Autodetecta el formato de archivo

   * "FMT_XML": Formato de archivo XML

   * "FMT_BINARY": Formato binario plist

   Si *use_builtin_types* es verdadero (el valor por defecto) los
   datos binarios serán retornados como instancias de "bytes", si no
   serán retornados como instancias de "Data".

   EL *dict_type* es el tipo usado por los diccionarios que son leídos
   del archivo plist.

   Los datos XML para el formato "FMT_XML" son analizados usando el
   analizador Expat desde "xml.parsers.expat" -- consulte su
   documentación para conocer las posibles excepciones en XML mal
   formado. Elementos desconocidos serán simplemente ignorados por el
   analizador plist.

   El analizar para el formato binario lanza "InvalidFileException"
   cuando el archivo no puede ser analizado.

   Nuevo en la versión 3.4.

plistlib.loads(data, *, fmt=None, use_builtin_types=True, dict_type=dict)

   Carga un plist desde un objeto de bytes. Consulte "load()" para una
   explicación de los argumentos de palabra clave.

   Nuevo en la versión 3.4.

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

   Escribe *value* a un archivo plist. *Fp* debe ser un objeto de
   archivo binario escribible.

   El argumento *fmt* especifica el formato del archivo plist y puede
   ser uno de los siguientes valores:

   * "FMT_XML": Archivo plist con formato XML

   * "FMT_BINARY": Archivo plist con formato binario

   Cuando *sort_keys* es verdadero (el valor por defecto) las claves
   para los diccionarios serán escritas al plist ordenadamente, si no
   serán escritas en el orden de iteración del diccionario.

   Cuando *skipkeys* es falso (el valor por defecto) la función
   levanta "TypeError" cuando una clave del diccionario no es una
   cadena de caracteres, si no tales claves serán omitidas.

   Una excepción "TypeError" será levantada si el objeto es un tipo no
   admitido o el contenedor que contiene tipos no admitidos.

   Una excepción "OverflowError" será levantada para valores enteros
   que no pueden ser representados en archivos plist (binarios).

   Nuevo en la versión 3.4.

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

   Retorna *value* como un objeto de bytes con formato plist. Consulte
   la documentación de "dump()" para una explicación de los argumentos
   de palabra clave de esta función.

   Nuevo en la versión 3.4.

La siguientes funciones están obsoletas:

plistlib.readPlist(pathOrFile)

   Lee un archivo plist. *pathOrFile* puede ser tanto un nombre de
   archivo o un (legible y binario) objeto de archivo. Retorna el
   objeto raíz desempaquetado (el cual generalmente es un
   diccionario).

   Esta función llama a "load()" para hacer el trabajo actual,
   consulte la documentación de "esa función" para una explicación de
   los argumentos de palabra clave.

   Obsoleto desde la versión 3.4: Usa "load()" en su lugar.

   Distinto en la versión 3.7: Los valores de diccionario en el
   resultado son ahora diccionarios normales. No puedes usar más el
   acceso mediante atributo para acceder a elementos de esos
   diccionarios.

plistlib.writePlist(rootObject, pathOrFile)

   Escribe *rootObject* a un archivo plist XML. *pathOrFile* puede ser
   tanto un nombre de archivo o un (escribible y binario) archivo de
   objeto

   Obsoleto desde la versión 3.4: Usa "dump()" en su lugar.

plistlib.readPlistFromBytes(data)

   Lee datos plist de un objeto de bytes. Retorna el objeto raíz.

   Consulta "load()" para una descripción de los argumentos de palabra
   clave.

   Obsoleto desde la versión 3.4: Usa "loads()" en su lugar.

   Distinto en la versión 3.7: Los valores de diccionario en el
   resultado son ahora diccionarios normales. No puedes usar más el
   acceso mediante atributo para acceder a elementos de esos
   diccionarios.

plistlib.writePlistToBytes(rootObject)

   Retorna *rootObject* como un objeto de bytes con formato XML plist.

   Obsoleto desde la versión 3.4: Usa "dumps()" en su lugar.

Las siguientes clases están disponibles:

class plistlib.Data(data)

   Retorna un objeto contenedor de "datos" alrededor del objeto de
   bytes *data*. Este es usado en funciones convirtiendo desde/hacia
   plists para representar el tipo "<data>" disponible en plists.

   Tiene un atributo, "data", que puede ser usado para recuperar el
   objeto de bytes de Python almacenado en él.

   Obsoleto desde la versión 3.4: Usa un objeto "bytes" en su lugar.

class plistlib.UID(data)

   Envuelve un "int". Este es usado leyendo o escribiendo datos
   codificados NSKeyedArchiver, los cuales contienen UID (ver manual
   PList).

   Tiene un atributo, "data", el cual puede ser usado para recuperar
   el valor int del UID. "data" debe estar en el rango *0 <= data <
   2**64*.

   Nuevo en la versión 3.8.

Las siguientes constantes están disponibles:

plistlib.FMT_XML

   El formato XML para archivos plist.

   Nuevo en la versión 3.4.

plistlib.FMT_BINARY

   El formato binario para archivos plist

   Nuevo en la versión 3.4.


Ejemplos
========

Generar un plist:

   pl = dict(
       aString = "Doodah",
       aList = ["A", "B", 12, 32.1, [1, 2, 3]],
       aFloat = 0.1,
       anInt = 728,
       aDict = dict(
           anotherString = "<hello & hi there!>",
           aThirdString = "M\xe4ssig, Ma\xdf",
           aTrueValue = True,
           aFalseValue = False,
       ),
       someData = b"<binary gunk>",
       someMoreData = b"<lots of binary gunk>" * 10,
       aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
   )
   with open(fileName, 'wb') as fp:
       dump(pl, fp)

Analizar un plist:

   with open(fileName, 'rb') as fp:
       pl = load(fp)
   print(pl["aKey"])
