plistlib — Генерируйте и разбирайте файлы Apple .plist.

Источник: Lib/plistlib.py

Этот модуль предоставляет интерфейс для чтения и записи файлов «списка свойств», используемых компанией Apple, в первую очередь в macOS и iOS. Модуль поддерживает как двоичные, так и XML-файлы plist.

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

Чтобы записать и разобрать файл plist, используйте функции dump() и load().

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

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

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

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

Изменено в версии 3.9: Старый API удален.

См.также

PList manual page

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

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

plistlib.load(fp, *, fmt=None, dict_type=dict, aware_datetime=False)

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

Параметр fmt - это формат файла; допустимы следующие значения:

  • None: Автоопределение формата файла

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

  • FMT_BINARY: Двоичный формат plist

Тип dict_type - это тип, используемый для словарей, которые считываются из файла plist.

Если значение aware_datetime равно true, поля с типом datetime.datetime будут создаваться как aware object, с типом tzinfo - как datetime.UTC.

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

Парсер бинарного формата выдает сообщение InvalidFileException, если файл не может быть разобран.

Added in version 3.4.

Изменено в версии 3.13: Добавился параметр aware_datetime, который можно использовать только по ключевому слову.

plistlib.loads(data, *, fmt=None, dict_type=dict, aware_datetime=False)

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

Added in version 3.4.

Изменено в версии 3.13: data может быть строкой, если fmt равно FMT_XML.

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

Запись значения в файл plist. Fp должен быть двоичным файловым объектом, доступным для записи.

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

  • FMT_XML: Файл plist в формате XML

  • FMT_BINARY: Файл plist в двоичном формате

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

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

Если значение aware_datetime равно true и любое поле с типом datetime.datetime задано как aware object, то перед записью оно будет конвертироваться в часовой пояс UTC.

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

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

Added in version 3.4.

Изменено в версии 3.13: Добавился параметр aware_datetime, который можно использовать только по ключевому слову.

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

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

Added in version 3.4.

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

class plistlib.UID(data)

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

У него есть один атрибут, data, который можно использовать для получения int-значения UID. Значение data должно находиться в диапазоне 0 <= data < 2**64.

Added in version 3.8.

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

plistlib.FMT_XML

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

Added in version 3.4.

plistlib.FMT_BINARY

Двоичный формат для файлов plist

Added in version 3.4.

Примеры

Генерация 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())

Разбор 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"])