plistlib — .plist-Dateien von Apple erzeugen und zerlegen

Quellcode: Lib/plistlib.py

Dieses Modul stellt eine Schnittstelle bereit, um die von Apple verwendeten „Property List“-Dateien zu lesen und zu schreiben, vor allem unter macOS und iOS. Dieses Modul unterstützt plist-Dateien sowohl im Binär- als auch im XML-Format.

Das Dateiformat der Property List (.plist) ist eine einfache Serialisierung, die grundlegende Objekttypen wie Dictionarys, Listen, Zahlen und Zeichenketten unterstützt. Das Objekt der obersten Ebene ist üblicherweise ein Dictionary oder ein eingefrorenes Dictionary.

Verwende die Funktionen dump() und load(), um eine plist-Datei zu schreiben und zu zerlegen.

Verwende dumps() und loads(), um mit plist-Daten in bytes- oder Zeichenkettenobjekten zu arbeiten.

Werte können Zeichenketten, ganze Zahlen, Gleitkommazahlen, Wahrheitswerte, Tupel, Listen, Dictionarys (aber nur mit Zeichenketten als Schlüsseln), bytes-, bytearray- oder datetime.datetime-Objekte sein.

Geändert in Version 3.4: Neue API, alte API veraltet. Unterstützung für plists im Binärformat hinzugefügt.

Geändert in Version 3.8: Unterstützung zum Lesen und Schreiben von UID-Tokens in binären plists hinzugefügt, wie NSKeyedArchiver und NSKeyedUnarchiver sie verwenden.

Geändert in Version 3.9: Alte API entfernt.

Siehe auch

Man-Page zu PList

Apples Dokumentation des Dateiformats.

Dieses Modul legt die folgenden Funktionen fest:

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

Liest eine plist-Datei. fp sollte ein lesbares, binäres Dateiobjekt sein. Gibt das entpackte Wurzelobjekt zurück (üblicherweise ein Dictionary).

fmt ist das Format der Datei, und die folgenden Werte sind gültig:

dict_type ist der Typ, der für Dictionarys verwendet wird, die aus der plist-Datei gelesen werden.

Ist aware_datetime wahr, werden Felder vom Typ datetime.datetime als zeitzonenbewusstes Objekt erzeugt, mit tzinfo als datetime.UTC.

XML-Daten für das Format FMT_XML werden mit dem Expat-Parser aus xml.parsers.expat zerlegt – welche Ausnahmen bei fehlerhaft gebildetem XML möglich sind, steht in dessen Dokumentation. Unbekannte Elemente werden vom plist-Parser einfach übergangen.

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

Added in version 3.4.

Geändert in Version 3.13: Der nur über Schlüsselwort angebbare 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. Eine Erklärung der Schlüsselwortargumente steht unter load().

Added in version 3.4.

Geändert in Version 3.13: data darf 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 schreibbares, binäres Dateiobjekt sein.

Das Argument fmt gibt das Format der plist-Datei an und kann einen der folgenden Werte haben:

Ist sort_keys wahr (die Voreinstellung), werden die Schlüssel von Dictionarys in sortierter Reihenfolge in die plist geschrieben, sonst in der Iterationsreihenfolge des Dictionarys.

Ist skipkeys falsch (die Voreinstellung), löst die Funktion TypeError aus, wenn ein Schlüssel eines Dictionarys keine Zeichenkette ist, sonst werden solche Schlüssel übersprungen.

Ist aware_datetime wahr und ist ein Feld vom Typ datetime.datetime als zeitzonenbewusstes Objekt gesetzt, wird es vor dem Schreiben in die Zeitzone UTC umgerechnet.

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

Ein OverflowError wird für ganzzahlige Werte ausgelöst, die sich in (binären) plist-Dateien nicht darstellen lassen.

Added in version 3.4.

Geändert in Version 3.13: Der nur über Schlüsselwort angebbare Parameter aware_datetime wurde hinzugefügt.

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

Gibt value als bytes-Objekt im plist-Format zurück. Eine Erklärung der Schlüsselwortargumente dieser Funktion steht in der Dokumentation zu dump().

Added in version 3.4.

Die folgenden Klassen sind verfügbar:

class plistlib.UID(data)

Hüllt einen int ein. Das wird beim Lesen oder Schreiben von NSKeyedArchiver-kodierten Daten verwendet, die eine UID enthalten (siehe das PList-Handbuch).

data

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

Added in version 3.8.

Die folgenden Konstanten sind verfügbar:

plistlib.FMT_XML

Das XML-Format für plist-Dateien.

Added in version 3.4.

plistlib.FMT_BINARY

Das Binärformat für plist-Dateien

Added in version 3.4.

Das Modul legt die folgenden Ausnahmen fest:

exception plistlib.InvalidFileException

Wird ausgelöst, wenn eine Datei nicht zerlegt werden kann.

Added in version 3.4.

Beispiele

Eine plist erzeugen:

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

Eine plist zerlegen:

import plistlib

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