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

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

---

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

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

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

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

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

تغییر یافته در نسخه‌ی 3.4: API جدید، API قدیمی منسوخ شد. پشتیبانی از plistهای قالب دودویی افزوده شد.

تغییر یافته در نسخه‌ی 3.8: پشتیبانی از خواندن و نوشتن توکن‌های UID در plistهای دودویی که NSKeyedArchiver و NSKeyedUnarchiver از آن‌ها استفاده می‌کنند، افزوده شد.

تغییر یافته در نسخه‌ی 3.9: API قدیمی حذف شد.

همچنین ملاحظه نمائید

صفحه‌ی راهنمای PList

مستندات اپل درباره‌ی قالب پرونده.

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

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.

مثال‌ها

تولید یک 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"])