# `plistlib` — Generate and parse Apple `.plist` files

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

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

The property list (`.plist`) file format is a simple serialization supporting basic object types, like dictionaries, lists, numbers and strings. Usually the top level object is a dictionary or a frozen dictionary.

Щоб вивести та проаналізувати файл 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.

  The parser raises `InvalidFileException` when the file cannot be parsed.

  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)

  Write value to a plist file. fp should be a writable, binary file object.

  Аргумент 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 value of the UID. It must be in the range `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.

The module defines the following exceptions:

exception plistlib.InvalidFileException

  Raised when a file cannot be parsed.

  Added in version 3.4.

## Приклади

Створення plist:

    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())

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