tomllib --- تجزیه پرونده‌های TOML

کد منبع: Lib/tomllib

---

این ماژول رابطی برای تجزیه کردن TOML 1.1.0 (زبان حداقل آشکار تام، https://toml.io) فراهم می‌کند. این ماژول از نوشتن TOML پشتیبانی نمی‌کند.

اضافه شده در نسخه‌ی 3.11: این ماژول با پشتیبانی از TOML 1.0.0 اضافه شد.

تغییر یافته در نسخه‌ی 3.15: پشتیبانی از TOML 1.1.0 اضافه شد. برای جزئیات، بخش چه چیزی جدید است را ببینید.

هشدار

هنگام تجزیه داده از منابع غیرقابل‌اعتماد، احتیاط کنید. یک رشته TOML مخرب ممکن است باعث شود کدگشا مقدار قابل‌توجهی از منابع پردازنده و حافظه را مصرف کند. محدود کردن اندازه داده‌ای که تجزیه می‌شود، توصیه می‌شود.

همچنین ببینید

بسته‌ی Tomli-W یک ابزار نوشتن TOML است که می‌تواند همراه با این ماژول استفاده شود و یک API نوشتن ارائه می‌دهد که برای کاربران ماژول‌های marshal و pickle کتابخانه استاندارد آشناست.

همچنین ببینید

بسته TOML Kit یک کتابخانه TOML با حفظ سبک است که هم قابلیت خواندن و هم قابلیت نوشتن دارد. این بسته به‌عنوان جایگزین توصیه‌شده برای این ماژول جهت ویرایش پرونده‌های TOML از پیش موجود پیشنهاد می‌شود.

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

tomllib.load(fp, /, *, parse_float=float)

یک پرونده TOML را می‌خواند. اولین آرگومان باید یک شیء پرونده دودویی و قابل خواندن باشد. یک dict برمی‌گرداند. انواع TOML را با استفاده از این جدول تبدیل به پایتون تبدیل می‌کند.

parse_float با رشته‌ی هر عدد اعشاری در TOML که باید کدگشایی شود فراخوانی می‌شود. به‌طور پیش‌فرض، این معادل float(num_str) است. این را می‌توان برای استفاده از یک نوع داده یا پارسرٔ دیگر برای اعداد اعشاری در TOML (برای مثال decimal.Decimal) به‌کار برد. این فراخوانی‌پذیر نباید یک dict یا یک list برگرداند، در غیر این صورت یک ValueError پرتاب می‌شود.

در صورت نامعتبر بودن سند TOML، یک TOMLDecodeError پرتاب خواهد شد.

tomllib.loads(s, /, *, parse_float=float)

TOML را از یک شیء str بارگذاری می‌کند. یک dict برمی‌گرداند. انواع TOML را با استفاده از این جدول تبدیل به پایتون تبدیل می‌کند. آرگومان parse_float همان معنایی را دارد که در load() دارد.

در صورت نامعتبر بودن سند TOML، یک TOMLDecodeError پرتاب خواهد شد.

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

exception tomllib.TOMLDecodeError(msg, doc, pos)

زیرکلاسی از ValueError با ویژگی‌های اضافی زیر:

msg

پیام خطای قالب‌بندی‌نشده.

doc

سند TOML که در حال تجزیه است.

pos

اندیس doc که در آن تجزیه شکست خورد.

lineno

سطر متناظر با pos.

colno

ستون متناظر با pos.

تغییر یافته در نسخه‌ی 3.14: پارامترهای msg، doc و pos افزوده شدند. ویژگی‌های msg، doc، pos، lineno و colno افزوده شدند.

منسوخ شده از نسخه‌ی 3.14: ارسال آرگومان‌های جایگاهی با قالب آزاد منسوخ شده است.

مثال‌ها

تجزیه یک پرونده TOML:

import tomllib

with open("pyproject.toml", "rb") as f:
    data = tomllib.load(f)

تجزیه‌ی یک رشته TOML:

import tomllib

toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""

data = tomllib.loads(toml_str)

جدول تبدیل

TOML	پایتون
سند TOML	dict
رشته	str
عدد صحیح	int
float	float (قابل پیکربندی با parse_float)
بولی	bool
تاریخ‌زمان آفست‌دار	datetime.datetime (ویژگی tzinfo به نمونه‌ای از datetime.timezone تنظیم شده است)
تاریخ‌زمان محلی	datetime.datetime (ویژگی tzinfo روی None تنظیم‌شده)
تاریخ محلی	datetime.date
زمان محلی	datetime.time
آرایه	فهرست
جدول	dict
جدول درون‌خطی	dict
آرایه‌ای از جدول‌ها	فهرستی از دیکشنری‌ها

محدودیت‌ها و ملاحظات سازگاری متقابل

tomllib محدودیت‌هایی را روی اسنادی که می‌تواند پردازش کند اعمال می‌کند و جزئیاتی را حفظ می‌کند که سایر پارسرهای TOML مجاز به نادیده گرفتن آن‌ها هستند. هنگام نوشتن پرونده‌های TOML قابل‌حمل، فقط از ویژگی‌هایی استفاده کنید که توسط استاندارد تضمین یا توصیه شده‌اند.

جزئیات پیاده‌سازی ذکر شده در اینجا ممکن است در نسخه‌های آینده‌ی پایتون تغییر کنند.

جداول/دیکشنری‌ها

مشخصات TOML تضمین نمی‌کند که جفت‌های کلید/مقدار در اسناد و جداول TOML به ترتیب خاصی باشند.

tomllib درایه‌های دیکشنری را به همان ترتیبی که در منبع ظاهر می‌شوند بارگذاری می‌کند.

اعداد صحیح

TOML پشتیبانی از اعداد صحیح در range(−2**63, 2**63) را توصیه می‌کند.

tomllib از محدودیت پایتون در تبدیل رشته‌ی عدد صحیح (به‌طور پیش‌فرض 4300 رقم) استفاده می‌کند.

اعداد اعشاری

TOML توصیه می‌کند که حداقل از مقادیر binary64 استاندارد IEEE 754 پشتیبانی شود، به این معنی که اعدادی با بیش از 15 رقم اعشار معنادار احتمالاً گرد خواهند شد.

tomllib به‌طور پیش‌فرض از float پایتون استفاده می‌کند؛ در بسیاری از پلتفرم‌های رایج، این همان مقدار binary64 توصیه شده است. برای جزئیات، sys.float_info را ببینید.

حد تو در تو بودن

TOML ۱.۱.۰ محدودیتی برای میزان تو در تو بودن آرایه‌ها و جدول‌ها درون یکدیگر پیشنهاد نمی‌کند. (محدودیتی برابر با ۱۰۰ برای نسخه‌ی آینده‌ی TOML پیشنهاد شده است.)

در tomllib، سطح تو در تو بودن عمدتاً توسط recursion limit پایتون محدود می‌شود. توجه داشته باشید که کدهایی که tomllib را فراخوانی می‌کنند ممکن است در این محدودیت نقش داشته باشند.