plistlib — Создание и парсинг файлов Mac OS .plist

Модуль предоставляет интерфейс для чтения и записи файлов «списка свойств», используемых в основном Mac OS X и поддерживающие как бинарные, так и XML-файлы.

Формат файла списка свойств (.plist) представляет собой простую сериализацию, поддерживающую базовые типы объектов, такие как словари, списки, числа и строки. Обычно объект верхнего уровня является словарем.

Для записи и синтаксического анализа файла plist используйте функции dump() и load().

Для работы с данными plist в байтах объектов используйте dumps() и loads().

Значениями могут быть строки, целые числа, числа с плавающей точкой, були, кортежи, списки, словари (но только с ключами строка), Data, bytes, bytesarray или datetime.datetime объекты.

Изменено в версии 3.4: Новый API, старый API устарел. Добавлена поддержка бинарных plist форматов.

Изменено в версии 3.8: Добавлена поддержка чтения и записи маркеров UID в двоичных plist, как используемый NSKeyedArchiver и NSKeyedUnarchiver.

См.также

PList страница справочника
Документация Apple по формату файлов.

Модуль определяет следующие функции:

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

Прочитать файл plist. fp должен быть читаемым и двоичным файловым объектом. Возвращает распакованный корневой объект (который обычно является словарем).

fmt - формат файла, и следующие значения - valid:

  • None: автообнаружение формата файла
  • FMT_XML: формат файла XML
  • FMT_BINARY: двоичный формат списка

Если use_builtin_types будет true (по умолчанию), то двоичные данные будут возвращенный как сущности bytes, иначе это - возвращенный как сущности 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)

Загрузка plist из объекта в байтах. Объяснение аргументов load() см. в ключевых аргументах.

Добавлено в версии 3.4.

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

Запись value в файл списка. Fp должен быть объектом двоичного файла с возможностью записи.

Аргумент fmt определяет формат plist файла и может быть одним из следующих значения:

  • FMT_XML: файл списка в формате XML
  • FMT_BINARY: двоичный файл plist

Когда sort_keys будет истиной (по умолчанию), ключи для словарей будут написаны plist в сортированном заказе, иначе они будут написаны в итеративном заказе словаря.

Когда skipkeys false (по умолчанию), функция вызывает TypeError, когда ключ словаря не строка, иначе такие ключи пропущены.

Будет вызван TypeError, если у объекта будет неподдерживаемый тип или контейнер, который содержит объекты неподдержанных типов.

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

Добавлено в версии 3.4.

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

Возвращает value как объект байтов в формате списка. См. документацию для dump() для объяснения ключевых аргументов этой функции.

Добавлено в версии 3.4.

Следующие функции устарели:

plistlib.readPlist(pathOrFile)

Читать файл plist. pathOrFile может быть именем файла или (читаемым и двоичным) объектом файла. Возвращает распакованный корневой объект (который обычно является словарем).

Функция вызывает load() для выполнения фактической работы, см. документацию that function для объяснения ключевых аргументов.

Не рекомендуется, начиная с версии 3.4: Вместо этого используйте load().

Изменено в версии 3.7: Dict значения в результате теперь нормальные словари. Вы больше не можете использовать атрибут доступ для доступа к элементам этих словарей.

plistlib.writePlist(rootObject, pathOrFile)

Записывает rootObject в XML-файл списка. pathOrFile может быть именем файла или (доступным для записи и двоичным) объектом файла

Не рекомендуется, начиная с версии 3.4: Вместо этого используйте dump().

plistlib.readPlistFromBytes(data)

Чтение данных plist из объекта в байтах. Возвращает корневого объекта.

Описание аргументов load() см. в разделе ключевой.

Не рекомендуется, начиная с версии 3.4: Вместо этого используйте loads().

Изменено в версии 3.7: Dict значения в результате теперь нормальные словари. Вы больше не можете использовать атрибут доступ для доступа к элементам этих словарей.

plistlib.writePlistToBytes(rootObject)

Возвращает rootObject как объект байтов в формате XML plist.

Не рекомендуется, начиная с версии 3.4: Вместо нее используйте dumps().

Доступны следующие классы:

class plistlib.Data(data)

Возвращает объект-оболочку «data» вокруг байтового объекта data. Это используемый в функциях преобразования из/в списки для представления типа <data>, доступных в списках.

У этого есть один атрибут, data, который может использоваться для восстановления байтового объекта Python, хранивший в нем.

Не рекомендуется, начиная с версии 3.4: Вместо нее используйте объект bytes.

class plistlib.UID(data)

Оборачивает int. Это - используемый, читая или сочиняя данные NSKeyedArchiver кодированный, которые содержат UID (см. руководство PList).

У него есть атрибут data, который может использоваться для восстановления значения UID. data должен находиться в диапазоне «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"])