14.5. plistlib – Generate and parse Mac OS X .plist files¶

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

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

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

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

Для работы с plist-данными в виде объектов bytes используйте 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.

The dict_type is the type used for dictionaries that are read from the plist file. The exact structure of the plist can be recovered by using collections.OrderedDict (although the order of keys shouldn’t be important in plist files).

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 в виде bytes-объекта в формате plist. См. документацию для dump() с описанием ключевых аргументов этой функции.

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

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

plistlib.readPlist(pathOrFile)¶

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

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

Примечание

Dict values in the result have a __getattr__ method that defers to __getitem_. This means that you can use attribute access to access items of these dictionaries.

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

plistlib.writePlist(rootObject, pathOrFile)¶

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

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

plistlib.readPlistFromBytes(data)¶

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

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

Примечание

Dict values in the result have a __getattr__ method that defers to __getitem_. This means that you can use attribute access to access items of these dictionaries.

Устарело с версии 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.

This class is a subclass of dict where attribute access can be used to access items. That is, aDict.key is the same as aDict['key'] for getting, setting and deleting items in the mapping.

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

class plistlib.Data(data)¶

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

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

Устарело с версии 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"])