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:

import datetime
import plistlib

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.now()
)
print(plistlib.dumps(pl).decode())

Analisando um plist:

import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])