plistlib — Generate and parse Apple .plist files

Вихідний код: Lib/plistlib.py

---

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

Формат файлу списку властивостей (.plist) — це проста серіалізація, яка підтримує базові типи об’єктів, як-от словники, списки, числа та рядки. Зазвичай об’єктом верхнього рівня є словник.

Щоб вивести та проаналізувати файл plist, використовуйте функції dump() і load().

To work with plist data in bytes or string objects, use dumps() and loads().

Значеннями можуть бути рядки, цілі числа, числа з плаваючою точкою, логічні значення, кортежі, списки, словники (але лише з рядковими ключами), об’єкти bytes, bytearray або datetime.datetime.

Змінено в версії 3.4: Новий API, старий API застарів. Додано підтримку бінарних форматів plists.

Змінено в версії 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.

When aware_datetime is true, fields with type datetime.datetime will be created as aware object, with tzinfo as datetime.UTC.

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

Синтаксичний аналізатор двійкового формату викликає InvalidFileException, коли файл не може бути проаналізований.

Added in version 3.4.

Змінено в версії 3.13: The keyword-only parameter aware_datetime has been added.

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

Load a plist from a bytes or string object. See load() for an explanation of the keyword arguments.

Added in version 3.4.

Змінено в версії 3.13: data can be a string when fmt equals 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, коли ключ словника не є рядком, інакше такі ключі пропускаються.

When aware_datetime is true and any field with type datetime.datetime is set as an aware object, it will convert to UTC timezone before writing it.

Якщо тип об’єкта не підтримується або контейнер містить об’єкти непідтримуваних типів, виникне TypeError.

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

Added in version 3.4.

Змінено в версії 3.13: The keyword-only parameter aware_datetime has been added.

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

Повертає значення як об’єкт bytes у форматі 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"])