plistlib — создание и разбор файлов Apple .plist

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

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

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

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

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

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

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

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 будут созданы как объекты с часовым поясом, где tzinfo — это datetime.UTC.

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

Если файл не удаётся разобрать, парсер вызывает исключение InvalidFileException.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

class plistlib.UID(data)

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

data

Целочисленное значение UID. Оно должно находиться в диапазоне 0 <= data < 2**64.

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

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

plistlib.FMT_XML

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

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

plistlib.FMT_BINARY

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

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

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

exception plistlib.InvalidFileException

Вызывается, если файл не удаётся разобрать.

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

import datetime as dt
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 = dt.datetime.now()
)
print(plistlib.dumps(pl).decode())

import plistlib

plist = b"""<plist version="1.0">
<dict>
    <key>foo</key>
    <string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])