plistlib --- تولید و پارس پرونده‌های .plist اپل¶

کد منبع: Lib/plistlib.py

این ماژول رابطی برای خواندن و نوشتن پرونده‌های «فهرست ویژگی» (property list) فراهم می‌کند که اپل عمدتاً در macOS و iOS از آن‌ها استفاده می‌کند. این ماژول از هر دو نوع پرونده plist دودویی و XML پشتیبانی می‌کند.

ساختار پرونده‌ی فهرست ویژگی‌ها (.plist) یک سریال‌سازی ساده است که از انواع داده‌ی پایه‌ای مانند دیکشنری‌ها، فهرست‌ها، اعداد و رشته‌ها پشتیبانی می‌کند. معمولاً شیء سطح بالا یک دیکشنری یا دیکشنری فریز‌شده است.

برای نوشتن و تجزیه یک پرونده plist، از توابع dump() و load() استفاده کنید.

برای کار با داده‌های plist در شیءهای bytes یا رشته، از dumps() و loads() استفاده کنید.

مقادیر می‌توانند رشته‌ها، اعداد صحیح، اعداد اعشاری، بولی‌ها، تاپل‌ها، فهرست‌ها، دیکشنری‌ها (اما فقط با کلیدهای رشته‌ای)، اشیای bytes، bytearray یا datetime.datetime باشند.

این ماژول توابع زیر را تعریف می‌کند:

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

یک پرونده plist را می‌خواند. fp باید یک شیء پرونده دودویی و قابل‌خواندن باشد. شیء ریشه واگشایی‌شده را برمی‌گرداند (که معمولاً یک دیکشنری است).

fmt قالب پرونده است و مقادیر زیر معتبر هستند:

• None: تشخیص خودکار قالب پرونده

• FMT_XML: قالب پرونده XML

• FMT_BINARY: قالب plist دودویی

dict_type نوع مورد استفاده برای دیکشنری‌هایی است که از پرونده plist خوانده می‌شوند.

هنگامی که aware_datetime true باشد، فیلدهایی با نوع datetime.datetime به‌صورت شیء آگاه ایجاد می‌شوند و tzinfo آن‌ها برابر با datetime.UTC است.

داده‌های XML برای قالب FMT_XML با استفاده از پارسر Expat از xml.parsers.expat تجزیه می‌شوند — برای استثناهای ممکن در XML بدشکل، مستندات آن را ببینید. عناصر ناشناخته به‌سادگی توسط پارسر plist نادیده گرفته می‌شوند.

پارسر هنگامی که پرونده قابل تجزیه نباشد، InvalidFileException را پرتاب می‌کند.

اضافه شده در نسخه‌ی 3.4.

تغییر یافته در نسخه‌ی 3.13: پارامتر فقط کلیدواژه‌ای aware_datetime افزوده شده است.

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

بارگذاری یک plist از یک شیء bytes یا رشته‌ای. برای توضیح آرگومان‌های کلیدواژه‌ای، load() را ببینید.

اضافه شده در نسخه‌ی 3.4.

تغییر یافته در نسخه‌ی 3.13: هنگامی که fmt برابر با FMT_XML باشد، data می‌تواند یک رشته باشد.

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

value را در یک پرونده plist بنویسید. fp باید یک شیء پرونده دودویی قابل‌نوشتن باشد.

آرگومان fmt قالب پرونده plist را مشخص می‌کند و می‌تواند یکی از مقدارهای زیر باشد:

• FMT_XML: پرونده plist با قالب XML

• FMT_BINARY: پرونده plist قالب‌بندی‌شده به‌صورت دودویی

هنگامی که sort_keys مقدار true باشد (پیش‌فرض)، کلیدهای دیکشنری‌ها به ترتیب مرتب‌شده در plist نوشته می‌شوند، در غیر این صورت به ترتیب پیمایش دیکشنری نوشته می‌شوند.

هنگامی که skipkeys نادرست باشد (پیش‌فرض)، اگر کلید یک دیکشنری رشته نباشد، تابع TypeError را پرتاب می‌کند؛ در غیر این صورت از چنین کلیدهایی صرف‌نظر می‌شود.

هنگامی که aware_datetime برابر true باشد و هر فیلدی با نوع datetime.datetime به‌عنوان یک شیء آگاه تنظیم شده باشد، پیش از نوشتن آن، به منطقه زمانی UTC تبدیل می‌شود.

اگر شیء از نوع پشتیبانی‌نشده یا ظرفی حاوی اشیایی از انواع پشتیبانی‌نشده باشد، یک TypeError پرتاب خواهد شد.

برای مقادیر عدد صحیحی که نمی‌توان آن‌ها را در پرونده‌های plist (دودویی) بازنمایی کرد، OverflowError پرتاب می‌شود.

اضافه شده در نسخه‌ی 3.4.

تغییر یافته در نسخه‌ی 3.13: پارامتر فقط کلیدواژه‌ای aware_datetime افزوده شده است.

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

value را به‌عنوان یک شیء بایتی با قالب plist برمی‌گرداند. برای توضیح آرگومان‌های کلیدواژه‌ای این تابع، مستندات dump() را ببینید.

اضافه شده در نسخه‌ی 3.4.

کلاس‌های زیر در دسترس هستند:

class plistlib.UID(data)¶

یک int را می‌پوشاند. این برای خواندن یا نوشتن داده‌های کدگذاری‌شده با NSKeyedArchiver استفاده می‌شود، که شامل UID است (به راهنمای PList مراجعه کنید).

data¶

مقدار عدد صحیح UID. باید در محدوده 0 <= data < 2**64 باشد.

اضافه شده در نسخه‌ی 3.8.

ثابت‌های زیر در دسترس هستند:

plistlib.FMT_XML¶

قالب XML برای پرونده‌های plist.

اضافه شده در نسخه‌ی 3.4.

plistlib.FMT_BINARY¶

قالب دودویی برای پرونده‌های plist

اضافه شده در نسخه‌ی 3.4.

این ماژول استثناهای زیر را تعریف می‌کند:

exception plistlib.InvalidFileException¶

هنگامی که یک پرونده نتواند تجزیه شود، پرتاب می‌شود.

اضافه شده در نسخه‌ی 3.4.

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

import plistlib

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