"plistlib" --- Generate and parse Mac OS X ".plist" files
*********************************************************

**Código-fonte:** Lib/plistlib.py

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

This module provides an interface for reading and writing the
"property list" files used mainly by Mac OS X and supports both binary
and XML plist files.

O formato de arquivo de lista de propriedades (".plist") é uma
serialização simples que oferece suporte a tipos básicos de objetos,
como dicionários, listas, números e strings. Normalmente, o objeto de
nível superior é um dicionário.

Para escrever e analisar um arquivo plist, use as funções "dump()" e
"load()".

Para trabalhar com dados plist em objetos bytes, use "dumps()" e
"loads()".

Values can be strings, integers, floats, booleans, tuples, lists,
dictionaries (but only with string keys), "Data", "bytes",
"bytesarray" or "datetime.datetime" objects.

Alterado na versão 3.4: Nova API, API antiga descontinuada. Suporte
para plists de formato binário adicionado.

Alterado na versão 3.8: Adicionado suporte para leitura e escrita de
tokens "UID" em plists binários, conforme usado por NSKeyedArchiver e
NSKeyedUnarchiver.

Ver também:

  PList manual page
     Documentação da Apple sobre o formato de arquivo.

Este módulo define as seguintes funções:

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

   Lê um arquivo plist. *fp* deve ser um objeto arquivo binário e
   legível. Retorna o objeto raiz desempacotado (que geralmente é um
   dicionário).

   *fmt* é o formato do arquivo e os seguintes valores são válidos:

   * "None": Detecta automaticamente o formato do arquivo

   * "FMT_XML": Formato de arquivo XML

   * "FMT_BINARY": Formato binário plist

   If *use_builtin_types* is true (the default) binary data will be
   returned as instances of "bytes", otherwise it is returned as
   instances of "Data".

   O *dict_type* é o tipo usado para dicionários que são lidos do
   arquivo plist.

   Dados XML para o formato "FMT_XML" são analisados ​​usando o
   analisador sintático Expat de "xml.parsers.expat" -- veja sua
   documentação para possíveis exceções em XML malformado. Elementos
   desconhecidos serão simplesmente ignorados pelo analisador de
   plist.

   O analisador sintático para o formato binário levanta
   "InvalidFileException" quando o arquivo não pode ser analisado.

   Novo na versão 3.4.

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

   Carrega um plist de um objeto bytes. Veja "load()" para uma
   explicação dos argumentos nomeados.

   Novo na versão 3.4.

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

   Escreve *value* em um arquivo plist. *Fp* deve ser um objeto
   arquivo binário gravável.

   O argumento *fmt* especifica o formato do arquivo plist e pode ser
   um dos seguintes valores:

   * "FMT_XML": Arquivo plist formatado em XML

   * "FMT_BINARY": Arquivo plist formatado em binário

   Quando *sort_keys* é verdadeiro (o padrão), as chaves dos
   dicionários serão escritas ordenadas no plist, caso contrário, elas
   serão escritas na ordem de iteração do dicionário.

   Quando *skipkeys* é falso (o padrão), a função levanta "TypeError"
   quando uma chave de um dicionário não é uma string, caso contrário,
   tais chaves são ignoradas.

   Uma "TypeError" será levantada se o objeto for de um tipo não
   suportado ou um contêiner que contém objetos de tipos não
   suportados.

   Uma "OverflowError" será levantada para valores inteiros que não
   podem ser representados em arquivos plist (binários).

   Novo na versão 3.4.

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

   Retorna *value* como um objeto bytes formatado em plist. Veja a
   documentação para "dump()" para uma explicação dos argumentos
   nomeados desta função.

   Novo na versão 3.4.

The following functions are deprecated:

plistlib.readPlist(pathOrFile)

   Read a plist file. *pathOrFile* may be either a file name or a
   (readable and binary) file object. Returns the unpacked root object
   (which usually is a dictionary).

   This function calls "load()" to do the actual work, see the
   documentation of "that function" for an explanation of the keyword
   arguments.

   Obsoleto desde a versão 3.4: Use "load()".

   Alterado na versão 3.7: Dict values in the result are now normal
   dicts.  You no longer can use attribute access to access items of
   these dictionaries.

plistlib.writePlist(rootObject, pathOrFile)

   Write *rootObject* to an XML plist file. *pathOrFile* may be either
   a file name or a (writable and binary) file object

   Obsoleto desde a versão 3.4: Use "dump()" instead.

plistlib.readPlistFromBytes(data)

   Read a plist data from a bytes object.  Return the root object.

   See "load()" for a description of the keyword arguments.

   Obsoleto desde a versão 3.4: Use "loads()" instead.

   Alterado na versão 3.7: Dict values in the result are now normal
   dicts.  You no longer can use attribute access to access items of
   these dictionaries.

plistlib.writePlistToBytes(rootObject)

   Return *rootObject* as an XML plist-formatted bytes object.

   Obsoleto desde a versão 3.4: Use "dumps()" instead.

As seguintes classes estão disponíveis:

class plistlib.Data(data)

   Return a "data" wrapper object around the bytes object *data*.
   This is used in functions converting from/to plists to represent
   the "<data>" type available in plists.

   It has one attribute, "data", that can be used to retrieve the
   Python bytes object stored in it.

   Obsoleto desde a versão 3.4: Use a "bytes" object instead.

class plistlib.UID(data)

   Envolve um "int". Isso é usado ao ler ou escrever dados codificados
   NSKeyedArchiver, que contém UID (veja o manual de PList).

   It has one attribute, "data", which can be used to retrieve the int
   value of the UID.  "data" must be in the range *0 <= data < 2**64*.

   Novo na versão 3.8.

As seguintes constantes estão disponíveis:

plistlib.FMT_XML

   O formato XML para arquivos plist.

   Novo na versão 3.4.

plistlib.FMT_BINARY

   O formato binário para arquivos plist

   Novo na versão 3.4.


Exemplos
========

Gerando um 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)

Analisando um plist:

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