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

To work with plist data in bytes objects, use dumps() and 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)

Load a plist from a bytes object. See load() for an explanation of the keyword arguments.

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"])