خانه / آموزش‌ها / آموزش ماژول tomllib در پایتون (Parsing TOML)

آموزش ماژول tomllib در پایتون (Parsing TOML)

🐍 HomeOfPython
|
📅 1404/10/17

سطح مقدماتی (Beginner Level)

در نسخه‌ی ۳.۱۱ پایتون، ماژول tomllib به کتابخانه استاندارد اضافه شد. این ماژول برای تجزیه (Parsing) فرمت TOML (Tom's Obvious, Minimal Language) استفاده می‌شود که امروزه یکی از محبوب‌ترین فرمت‌ها برای فایل‌های پیکربندی (Configuration Files) است.

اگر با ابزارهایی مثل Poetry یا زبان Rust کار کرده باشید، حتما فایل‌های pyproject.toml یا Cargo.toml را دیده‌اید. با tomllib می‌توانید این فایل‌ها را مستقیماً در پایتون بخوانید.

نکته مهم: ماژول tomllib فقط قابلیت خواندن (Read-only) را دارد و نمی‌تواند فایل TOML تولید (Write) کند. برای نوشتن، نیاز به کتابخانه‌های جانبی مثل tomli-w دارید.

۱. خواندن رشته‌های TOML با loads

ساده‌ترین روش استفاده، متد loads (Load String) است که یک رشته متنی با فرمت TOML را گرفته و آن را به یک دیکشنری پایتون تبدیل می‌کند.

مثال اول: تبدیل رشته ساده

در این مثال یک ساختار ساده TOML را پردازش می‌کنیم.

Python

مثال دوم: کار با آرایه‌ها و انواع داده

فرمت TOML از آرایه‌ها و انواع داده مختلف پشتیبانی می‌کند که به لیست‌ها و تایپ‌های متناظر در پایتون تبدیل می‌شوند.

Python

۲. نگاشت انواع داده (Type Mapping)

دانستن اینکه هر نوع داده در TOML به چه چیزی در پایتون تبدیل می‌شود ضروری است:

  • TOML String -> Python str
  • TOML Integer -> Python int
  • TOML Float -> Python float
  • TOML Boolean -> Python bool
  • TOML Array -> Python list
  • TOML Table (Inline/Standard) -> Python dict
  • TOML DateTime -> Python datetime.datetime

مثال سوم: بررسی نوع داده‌ها

Python

سطح پیشرفته (Professional Level)

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

۱. خواندن فایل با load (حالت باینری)

برخلاف بسیاری از کتابخانه‌های متنی، tomllib.load() انتظار دارد که فایل در حالت باینری (rb) باز شود، نه متنی. این موضوع برای مدیریت صحیح انکدینگ (UTF-8) ضروری است.

مثال اول: خواندن صحیح فایل کانفیگ

از آنجا که ما در اینجا فایل خارجی نداریم، این کد به صورت static نمایش داده می‌شود، اما این روش استاندارد خواندن فایل‌های .toml در پروژه‌های واقعی است.

python 
# Example 1: Reading a file correctly (Static because file doesn't exist here)
import tomllib

# ALWAYS open in binary mode 'rb'
with open("config.toml", "rb") as f:
    config = tomllib.load(f)

print(config)

مثال دوم: خطای رایج (باز کردن متنی)

اگر فایل را با مود r باز کنید، با خطا مواجه می‌شوید.

python 
# Example 2: Wrong approach (Snippet)
import tomllib

# This will raise TypeError: File must be opened in binary mode, e.g. use "rb"
# with open("config.toml", "r") as f:
#     data = tomllib.load(f)

۲. مدیریت خطاها (Error Handling)

اگر فرمت TOML نامعتبر باشد، tomllib خطای tomllib.TOMLDecodeError را برمی‌گرداند. مدیریت این خطا برای جلوگیری از کرش کردن برنامه حیاتی است.

مثال سوم: مدیریت رشته نامعتبر

Python

۳. کنترل اعداد اعشاری (Parse Float)

به طور پیش‌فرض، اعداد اعشاری TOML به float پایتون تبدیل می‌شوند. اما ممکن است بخواهید برای دقت بیشتر از decimal.Decimal استفاده کنید. متدهای load و loads آرگومان parse_float را می‌پذیرند.

مثال چهارم: استفاده از Decimal

Python

۴. مقایسه با کتابخانه‌های جانبی (tomli)

قبل از پایتون ۳.۱۱، کتابخانه tomli استاندارد دفاکتو بود. در واقع tomllib همان tomli است که به هسته پایتون اضافه شده است.

  • اگر از پایتون ۳.۱۱+ استفاده می‌کنید: از tomllib (Built-in) استفاده کنید.
  • اگر از پایتون قدیمی‌تر استفاده می‌کنید: باید pip install tomli را انجام دهید و از tomli استفاده کنید (API کاملاً یکسان است).
python 
# Example 5: Compatibility snippet (Static)
import sys

if sys.version_info >= (3, 11):
    import tomllib
else:
    import tomli as tomllib

# Now usage is identical across versions
# tomllib.loads(...)
← بازگشت به لیست آموزش‌ها