14.5. plistlib – Генерация и разбор файлов Mac OS X .plist¶plistlib – Generate and parse Mac OS X .plist files

Исходный код: Lib/plistlib.py

Этот модуль предоставляет интерфейс для чтения и записи файлов «property list» (списков свойств), используемых в основном в Mac OS X, и поддерживает как двоичные, так и XML-файлы plist.

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

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

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

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

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

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

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

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

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

Если use_builtin_types равен true (по умолчанию), двоичные данные будут возвращены в виде экземпляров bytes, в противном случае они возвращаются в виде экземпляров Data.

Параметр dict_type – это тип, используемый для словарей, читаемых из файла plist. Точную структуру plist можно восстановить, используя collections.OrderedDict (хотя порядок ключей не должен быть важен в файлах 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 в 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)¶

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

Новое в версии 3.4.

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

plistlib.readPlist(pathOrFile)¶

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

Эта функция вызывает load() для выполнения фактической работы; описание именованных аргументов см. в документации этой функции.

Примечание

Словарные значения в результате имеют метод __getattr__, который делегирует вызов __getitem_. Это означает, что для доступа к элементам этих словарей можно использовать доступ к атрибутам.

Устарело с версии 3.4: Вместо этого используйте load().

plistlib.writePlist(rootObject, pathOrFile)¶

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

Устарело с версии 3.4: Вместо этого используйте dump().

plistlib.readPlistFromBytes(data)¶

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

Описание именованных аргументов см. в load().

Примечание

Значения-словари в результате имеют метод __getattr__, который делегирует __getitem_. Это означает, что для доступа к элементам этих словарей можно использовать обращение через атрибуты.

Устарело с версии 3.4: Вместо этого используйте loads().

plistlib.writePlistToBytes(rootObject)¶

Возвращает rootObject в виде объекта bytes, отформатированного как XML plist.

Устарело с версии 3.4: Вместо этого используйте dumps().

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

Dict([dict]):

Return an extended mapping object with the same value as dictionary dict.

Этот класс является подклассом dict, в котором для доступа к элементам можно использовать обращение через атрибуты. То есть aDict.key эквивалентно aDict['key'] для получения, установки и удаления элементов отображения.

Устарело с версии 3.0.

class plistlib.Data(data)¶

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

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

Устарело с версии 3.4: Вместо этого используйте объект bytes.

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

plistlib.FMT_XML¶

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

Новое в версии 3.4.

plistlib.FMT_BINARY¶

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

Новое в версии 3.4.

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)

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