marshal --- سریال‌سازی داخلی اشیای پایتون

این ماژول شامل توابعی است که می‌توانند مقادیر پایتون را در یک قالب دودویی بخوانند و بنویسند. این قالب مختص پایتون است، اما از مسائل معماری ماشین مستقل است (برای مثال، می‌توانید یک مقدار پایتون را در پرونده‌ای روی یک رایانه شخصی بنویسید، پرونده را به یک مک منتقل کنید و آن را در آنجا بازخوانی کنید). جزئیات این قالب عمداً مستند نشده است؛ ممکن است بین نسخه‌های پایتون تغییر کند (اگرچه به‌ندرت این اتفاق می‌افتد). [1]

این یک ماژول عمومی برای «ماندگاری» نیست. برای ماندگاری عمومی و انتقال اشیای پایتون از طریق فراخوانی‌های RPC، ماژول‌های pickle و shelve را ببینید. ماژول marshal عمدتاً برای پشتیبانی از خواندن و نوشتن کد «شبه‌کامپایل‌شده» برای ماژول‌های پایتون در پرونده‌های .pyc وجود دارد. بنابراین، نگه‌دارندگان پایتون این حق را برای خود محفوظ می‌دارند که در صورت نیاز، قالب marshal را به‌صورت ناسازگار با نسخه‌های قبلی تغییر دهند. قالب اشیای کد بین نسخه‌های پایتون سازگار نیست، حتی اگر نسخه‌ی قالب یکسان باشد. سریال‌زدایی یک شیء کد در نسخه‌ی نادرست پایتون، رفتار تعریف‌نشده دارد. اگر اشیای پایتون را سریال‌سازی و سریال‌زدایی می‌کنید، به‌جای آن از ماژول pickle استفاده کنید — عملکرد آن قابل‌مقایسه است، استقلال از نسخه تضمین می‌شود، و pickle از طیف بسیار گسترده‌تری از اشیاء نسبت به marshal پشتیبانی می‌کند.

هشدار

ماژول marshal برای ایمن بودن در برابر داده‌های نادرست یا بدخواهانه ساخته‌شده طراحی نشده است. هرگز داده‌های دریافت‌شده از منبع نامعتبر یا احراز هویت‌نشده را unmarshal نکنید.

توابعی وجود دارند که پرونده‌ها را می‌خوانند/می‌نویسند، و همچنین توابعی که روی اشیاء شبه‌بایت (bytes-like) عمل می‌کنند.

از همه انواع شیء پایتون پشتیبانی نمی‌شود؛ به‌طور کلی، فقط اشیایی که مقدارشان مستقل از اجرای خاصی از پایتون باشد را می‌توان با این ماژول نوشت و خواند. از انواع زیر پشتیبانی می‌شود:

  • انواع عددی: int، bool، float، complex.

  • رشته‌ها (str) و bytes. اشیاء شبه‌بایت مانند bytearray به‌صورت bytes مارشال (marshalled) می‌شوند.

  • ظرف‌ها: tuple، list، set، frozenset و slice (از version 5). باید توجه داشته باشید که این موارد تنها در صورتی پشتیبانی می‌شوند که مقادیر درون آن‌ها نیز پشتیبانی شوند. ظرف‌های بازگشتی از version 3 پشتیبانی می‌شوند.

  • مقادیر تک‌نمونه None، Ellipsis و StopIteration.

  • اشیای code، اگر allow_code درست باشد. یادداشت بالا درباره وابستگی به نسخه را ببینید.

تغییر یافته در نسخه‌ی 3.4:

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

  • نسخه‌ی 4 قالب افزوده شد، که از بازنمایی‌های کارآمد رشته‌های کوتاه پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.14: نسخه‌ی 5 قالب افزوده شد که امکان مارشال‌کردن اسلایس‌ها را فراهم می‌کند.

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

marshal.dump(value, file, version=version, /, *, allow_code=True)

مقدار را در پرونده باز بنویسید. مقدار باید از یک نوع پشتیبانی‌شده باشد. پرونده باید یک binary file قابل‌نوشتن باشد.

اگر مقدار دارای نوعی پشتیبانی‌نشده باشد (یا شامل شیءای باشد که چنین نوعی دارد)، استثنای ValueError پرتاب می‌شود --- اما داده‌های نامعتبر نیز در پرونده نوشته خواهند شد. شیء به‌درستی توسط load() بازخوانی نخواهد شد. اشیاء کد فقط در صورتی پشتیبانی می‌شوند که allow_code برابر true باشد.

آرگومان version قالب داده‌ای را مشخص می‌کند که dump باید از آن استفاده کند (در زیر ببینید).

یک رویداد حسابرسی marshal.dumps را با آرگومان‌های value و version پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: پارامتر allow_code اضافه شد.

marshal.load(file, /, *, allow_code=True)

یک مقدار را از پرونده باز می‌خواند و آن را برمی‌گرداند. اگر هیچ مقدار معتبری خوانده نشود (مثلاً به این دلیل که داده‌ها قالب marshal ناسازگارِ نسخه‌ای متفاوت از پایتون دارند)، EOFError، ValueError یا TypeError را پرتاب می‌کند. از اشیای کد فقط در صورتی پشتیبانی می‌شود که allow_code مقدار true باشد. پرونده باید یک پرونده دودویی قابل‌خواندن باشد.

یک رویداد حسابرسی marshal.load را بدون آرگومان پرتاب می‌کند.

توجه

اگر شیءای که حاوی یک نوع پشتیبانی‌نشده است با dump() مارشال‌شده باشد، load() نوع غیرقابل‌مارشال را با None جایگزین می‌کند.

تغییر یافته در نسخه‌ی 3.10: این فراخوانی پیش‌تر برای هر شیء کد یک رویداد حسابرسی (audit event) code.__new__ را پرتاب می‌کرد. اکنون یک رویداد واحد marshal.load را برای کل عملیات بارگذاری پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: پارامتر allow_code اضافه شد.

marshal.dumps(value, version=version, /, *, allow_code=True)

شیء bytes را برمی‌گرداند که توسط dump(value, file) در یک پرونده نوشته می‌شد. مقدار باید از یک نوع پشتیبانی‌شده باشد. اگر مقدار از یک نوع پشتیبانی‌نشده باشد (یا شامل شیءای باشد که از یک نوع پشتیبانی‌نشده باشد)، استثنای ValueError را پرتاب می‌کند. اشیاء کد فقط در صورتی پشتیبانی می‌شوند که allow_code درست باشد.

آرگومان version قالب داده‌ای را مشخص می‌کند که dumps باید از آن استفاده کند (در زیر ببینید).

یک رویداد حسابرسی marshal.dumps را با آرگومان‌های value و version پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: پارامتر allow_code اضافه شد.

marshal.loads(bytes, /, *, allow_code=True)

bytes-like object را به یک مقدار تبدیل می‌کند. اگر هیچ مقدار معتبری یافت نشود، EOFError، ValueError یا TypeError پرتاب می‌شود. اشیاء کد فقط در صورتی پشتیبانی می‌شوند که allow_code درست باشد. بایت‌های اضافی در ورودی نادیده گرفته می‌شوند.

یک رویداد حسابرسی marshal.loads را با آرگومان bytes پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.10: این فراخوانی پیش‌تر برای هر شیء کد، یک رویداد حسابرسی code.__new__ پرتاب می‌کرد. اکنون یک رویداد marshal.loads را برای کل عملیات بارگذاری پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.13: پارامتر allow_code اضافه شد.

علاوه بر این، ثابت‌های زیر تعریف شده‌اند:

marshal.version

قالب مورد استفاده‌ی ماژول را نشان می‌دهد. نسخه‌ی 0 نخستین نسخه از نظر تاریخی است؛ نسخه‌های بعدی قابلیت‌های جدیدی اضافه می‌کنند. به‌طور معمول، یک نسخه‌ی جدید هنگام معرفی به پیش‌فرض تبدیل می‌شود.

نسخه

در دسترس از

قابلیت‌های جدید

1

Python 2.4

اشتراک‌گذاری رشته‌های درونی‌سازی‌شده (interned strings)

۲

Python 2.5

نمایش دودویی اعداد اعشاری

3

Python 3.4

پشتیبانی از نمونه‌سازی شیء و بازگشت

۴

Python 3.4

بازنمایی کارآمد رشته‌های کوتاه

۵

Python 3.14

پشتیبانی از اشیاء slice

پانویس‌ها