"plistlib" --- Generate and parse Apple ".plist" files
******************************************************

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

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

Este módulo fornece uma interface para ler e escrever os arquivos
"property listas (lista de propriedades) usados pela Apple,
principalmente no macOS e iOS. Este módulo tem suporte a arquivos
plist binários e XML.

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()".

Os valores podem ser strings, inteiros, floats, booleanos, tuplas,
listas, dicionários (mas somente com chaves de string), objetos
"bytes", "bytearray" ou "datetime.datetime".

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.

Alterado na versão 3.9: API antiga removida.

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, 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

   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, 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.

As seguintes classes estão disponíveis:

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).

   Tem um atributo, "data", que pode ser usado para recuperar o valor
   int do UID. "data" deve estar no intervalo "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"])
