plistlib — Generieren und Parsen von Apple .plist-Dateien

Quellcode: Lib/plistlib.py

Dieses Modul bietet eine Schnittstelle zum Lesen und Schreiben der von Apple verwendeten "Property List"-Dateien, hauptsächlich unter macOS und iOS. Dieses Modul unterstützt sowohl binäre als auch XML-Plist-Dateien.

Das Property List-Dateiformat (.plist) ist eine einfache Serialisierung, die grundlegende Objekttypen wie Wörterbücher, Listen, Zahlen und Zeichenketten unterstützt. Normalerweise ist das Top-Level-Objekt ein Wörterbuch.

Zum Schreiben und Parsen einer Plist-Datei verwenden Sie die Funktionen dump() und load().

Um mit Plist-Daten in Bytes- oder Zeichenkettenobjekten zu arbeiten, verwenden Sie dumps() und loads().

Werte können Zeichenketten, Ganzzahlen, Gleitkommazahlen, Booleans, Tupel, Listen, Wörterbücher (aber nur mit Zeichenketten-Schlüsseln), bytes, bytearray oder datetime.datetime-Objekte sein.

Geändert in Version 3.4: Neue API, alte API veraltet. Unterstützung für das binäre Format von Plists hinzugefügt.

Geändert in Version 3.8: Unterstützung für das Lesen und Schreiben von UID-Tokens in binären Plists hinzugefügt, wie sie von NSKeyedArchiver und NSKeyedUnarchiver verwendet werden.

Geändert in Version 3.9: Alte API entfernt.

Siehe auch

PList Handbuchseite

Apples Dokumentation des Dateiformats.

Dieses Modul definiert die folgenden Funktionen

plistlib.load(fp, *, fmt=None, dict_type=dict, aware_datetime=False)

Liest eine Plist-Datei. fp sollte ein lesbares und binäres Dateiobjekt sein. Gibt das entpackte Wurzelobjekt zurück (das normalerweise ein Wörterbuch ist).

Das Argument fmt ist das Format der Datei und die folgenden Werte sind gültig

dict_type ist der Typ, der für Wörterbücher verwendet wird, die aus der Plist-Datei gelesen werden.

Wenn aware_datetime wahr ist, werden Felder vom Typ datetime.datetime als bewusstes Objekt erstellt, mit tzinfo als datetime.UTC.

XML-Daten für das FMT_XML-Format werden mit dem Expat-Parser aus xml.parsers.expat geparst – siehe dessen Dokumentation für mögliche Ausnahmen bei fehlerhaftem XML. Unbekannte Elemente werden vom Plist-Parser einfach ignoriert.

Der Parser löst InvalidFileException aus, wenn die Datei nicht geparst werden kann.

Hinzugefügt in Version 3.4.

Geändert in Version 3.13: Der Nur-Schlüsselwort-Parameter aware_datetime wurde hinzugefügt.

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

Lädt eine Plist aus einem Bytes- oder Zeichenkettenobjekt. Siehe die Dokumentation für load() für eine Erklärung der Schlüsselwortargumente.

Hinzugefügt in Version 3.4.

Geändert in Version 3.13: data kann eine Zeichenkette sein, wenn fmt gleich FMT_XML ist.

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

Schreibt value in eine Plist-Datei. fp sollte ein beschreibbares, binäres Dateiobjekt sein.

Das Argument fmt gibt das Format der Plist-Datei an und kann einer der folgenden Werte sein

Wenn sort_keys wahr ist (Standardwert), werden die Schlüssel für Wörterbücher in sortierter Reihenfolge in die Plist geschrieben, andernfalls werden sie in der Iterationsreihenfolge des Wörterbuchs geschrieben.

Wenn skipkeys falsch ist (Standardwert), löst die Funktion TypeError aus, wenn ein Schlüssel eines Wörterbuchs keine Zeichenkette ist, andernfalls werden solche Schlüssel übersprungen.

Wenn aware_datetime wahr ist und jedes Feld vom Typ datetime.datetime als bewusstes Objekt gesetzt ist, wird es vor dem Schreiben in die UTC-Zeitzone konvertiert.

Eine TypeError wird ausgelöst, wenn das Objekt einen nicht unterstützten Typ hat oder ein Container ist, der Objekte nicht unterstützter Typen enthält.

Eine OverflowError wird für Ganzzahlwerte ausgelöst, die nicht in (binären) Plist-Dateien dargestellt werden können.

Hinzugefügt in Version 3.4.

Geändert in Version 3.13: Der Nur-Schlüsselwort-Parameter aware_datetime wurde hinzugefügt.

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

Gibt value als Plist-formatiertes Bytes-Objekt zurück. Siehe die Dokumentation für dump() für eine Erklärung der Schlüsselwortargumente dieser Funktion.

Hinzugefügt in Version 3.4.

Die folgenden Klassen sind verfügbar

class plistlib.UID(data)

Umschließt eine int. Dies wird beim Lesen oder Schreiben von NSKeyedArchiver-kodierten Daten verwendet, die UID enthalten (siehe PList-Handbuch).

data

Int-Wert der UID. Er muss im Bereich 0 <= data < 2**64 liegen.

Hinzugefügt in Version 3.8.

Die folgenden Konstanten sind verfügbar

plistlib.FMT_XML

Das XML-Format für Plist-Dateien.

Hinzugefügt in Version 3.4.

plistlib.FMT_BINARY

Das binäre Format für Plist-Dateien

Hinzugefügt in Version 3.4.

Das Modul definiert die folgenden Ausnahmen

exception plistlib.InvalidFileException

Ausgelöst, wenn eine Datei nicht geparst werden kann.

Hinzugefügt in Version 3.4.

Beispiele

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

Parsen einer 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"])