plistlib — Generate and parse Mac OS X .plist files

Вихідний код: 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.

Формат файлу списку властивостей (.plist) — це проста серіалізація, яка підтримує базові типи об’єктів, як-от словники, списки, числа та рядки. Зазвичай об’єктом верхнього рівня є словник.

Щоб вивести та проаналізувати файл plist, використовуйте функції dump() і 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.

Змінено в версії 3.4: Новий API, старий API застарів. Додано підтримку бінарних форматів plists.

Змінено в версії 3.8: Додано підтримку для читання та запису токенів UID у бінарних списках, що використовуються NSKeyedArchiver і NSKeyedUnarchiver.

Дивись також

PList manual page

Документація Apple про формат файлу.

Цей модуль визначає такі функції:

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

Прочитайте файл plist. fp має бути читабельним і двійковим файловим об’єктом. Повертає розпакований кореневий об’єкт (який зазвичай є словником).

fmt — це формат файлу, і такі значення є дійсними:

  • None: Автоматичне визначення формату файлу

  • FMT_XML: формат файлу XML

  • FMT_BINARY: двійковий формат 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.

dict_type — це тип, який використовується для словників, які читаються з файлу plist.

XML-дані для формату FMT_XML аналізуються за допомогою синтаксичного аналізатора Expat із xml.parsers.expat — перегляньте його документацію щодо можливих винятків щодо неправильно сформованого XML. Невідомі елементи просто ігноруватимуться аналізатором plist.

Синтаксичний аналізатор двійкового формату викликає InvalidFileException, коли файл не може бути проаналізований.

Нове в версії 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.

Нове в версії 3.4.

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

Запишіть значення у файл plist. Fp має бути доступним для запису двійковим файловим об’єктом.

Аргумент fmt визначає формат файлу plist і може бути одним із таких значень:

  • FMT_XML: Plist-файл у форматі XML

  • FMT_BINARY: файл plist у двійковому форматі

Якщо sort_keys має значення true (за замовчуванням), ключі для словників будуть записані до plist у відсортованому порядку, інакше вони будуть записані в порядку ітерацій словника.

Якщо skipkeys має значення false (за замовчуванням), функція викликає TypeError, коли ключ словника не є рядком, інакше такі ключі пропускаються.

Якщо тип об’єкта не підтримується або контейнер містить об’єкти непідтримуваних типів, виникне TypeError.

Помилка OverflowError буде викликана для цілих значень, які не можуть бути представлені в (бінарних) файлах plist.

Нове в версії 3.4.

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

Повертає значення як об’єкт bytes у форматі plist. Перегляньте документацію для dump() для пояснення ключових аргументів цієї функції.

Нове в версії 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.

Застаріло починаючи з версії 3.4: Use load() instead.

Змінено в версії 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

Застаріло починаючи з версії 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.

Застаріло починаючи з версії 3.4: Use loads() instead.

Змінено в версії 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.

Застаріло починаючи з версії 3.4: Use dumps() instead.

Доступні такі класи:

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.

Застаріло починаючи з версії 3.4: Use a bytes object instead.

class plistlib.UID(data)

Обгортає int. Це використовується під час читання або запису даних, закодованих NSKeyedArchiver, які містять UID (див. посібник 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.

Нове в версії 3.8.

Доступні такі константи:

plistlib.FMT_XML

Формат XML для файлів plist.

Нове в версії 3.4.

plistlib.FMT_BINARY

Двійковий формат для файлів plist

Нове в версії 3.4.

Приклади

Створення 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)

Розбір plist:

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