پشتیبانی از مارشالینگ داده

این روتین‌ها به کد C اجازه می‌دهند تا با اشیاء سریال‌سازی‌شده، با استفاده از همان قالب داده‌ی ماژول marshal کار کند. توابعی برای نوشتن داده‌ها در قالب سریال‌سازی وجود دارند و علاوه بر آن‌ها، توابع دیگری نیز هستند که می‌توان از آن‌ها برای بازخوانی داده‌ها استفاده کرد. پرونده‌هایی که برای ذخیره‌سازی داده‌های مارشال‌شده استفاده می‌شوند، باید در حالت دودویی باز شوند.

مقادیر عددی به‌گونه‌ای ذخیره می‌شوند که کم‌ارزش‌ترین بایت در ابتدا قرار گیرد.

این ماژول از چندین نسخه از قالب داده پشتیبانی می‌کند؛ برای جزئیات، مستندات ماژول پایتون را ببینید.

Py_MARSHAL_VERSION

نسخه‌ی فعلی قالب. به marshal.version مراجعه کنید.

void PyMarshal_WriteLongToFile(long value, FILE *file, int version)

یک عدد صحیح long به نام value را در file مارشال می‌کند. این تابع تنها ۳۲ بیت کم‌ارزش value را می‌نویسد؛ صرف‌نظر از اندازه‌ی نوع بومی long. version قالب پرونده را نشان می‌دهد.

این تابع می‌تواند شکست بخورد، که در این صورت نشانگر خطا را تنظیم می‌کند. برای بررسی این موضوع از PyErr_Occurred() استفاده کنید.

نکته

In Python 3.15 and earlier, this function does not set the error indicator if writing to file fails. The same caveat applies as for PyMarshal_WriteObjectToFile().

void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)

یک شیء پایتون، value، را به file مارشال کنید. version قالب پرونده را مشخص می‌کند.

این تابع می‌تواند شکست بخورد، که در این صورت نشانگر خطا را تنظیم می‌کند. برای بررسی این موضوع از PyErr_Occurred() استفاده کنید.

نکته

In Python 3.15 and earlier, this function can write only part of the data to file and return without setting the error indicator, for example if value contains an object which cannot be marshalled or if writing to file fails (see gh-155907). Code which has to support these versions cannot rely on PyErr_Occurred() alone to know that all the data was written. It can use PyMarshal_WriteObjectToString() and write the result itself, or validate what was written.

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)

مقدار بازگشتی: مرجع جدید.

یک شیء bytes حاوی نمایش مارشال‌شده‌ی value را برمی‌گرداند. version قالب پرونده را مشخص می‌کند.

توابع زیر امکان بازخوانی مقادیر مارشال‌شده را فراهم می‌کنند.

long PyMarshal_ReadLongFromFile(FILE *file)

یک long سی را از جریان داده در یک FILE* که برای خواندن باز شده است برمی‌گرداند. با استفاده از این تابع تنها می‌توان یک مقدار ۳۲ بیتی را خواند، صرف‌نظر از اندازه بومی long.

در صورت خطا، استثنای مناسب (EOFError) را تنظیم می‌کند و -1 را برمی‌گرداند.

int PyMarshal_ReadShortFromFile(FILE *file)

بازگرداندن یک short از زبان C از جریان داده در یک FILE* که برای خواندن باز شده است. با استفاده از این تابع فقط می‌توان یک مقدار ۱۶ بیتی را خواند، صرف‌نظر از اندازه بومی short.

در صورت خطا، استثنای مناسب (EOFError) را تنظیم می‌کند و -1 را برمی‌گرداند.

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)

مقدار بازگشتی: مرجع جدید.

یک شیء پایتون را از جریان داده در یک FILE* که برای خواندن باز شده است، برمی‌گرداند.

در صورت خطا، استثنای مناسب (EOFError، ValueError یا TypeError) را تنظیم می‌کند و NULL را برمی‌گرداند.

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)

مقدار بازگشتی: مرجع جدید.

یک شیء پایتون را از جریان داده در یک FILE* باز‌شده برای خواندن برمی‌گرداند. برخلاف PyMarshal_ReadObjectFromFile()، این تابع فرض می‌کند که هیچ شیء دیگری از پرونده خوانده نخواهد شد و همین فرض به آن اجازه می‌دهد که داده‌های پرونده را به‌طور پرخاشگرانه در حافظه بارگذاری کند تا سریال‌زدایی بتواند به‌جای خواندن بایت‌به‌بایت از پرونده، بر اساس داده‌های موجود در حافظه عمل کند. تنها در صورتی از این گونه استفاده کنید که مطمئن باشید هیچ چیز دیگری از پرونده نخواهید خواند.

در صورت خطا، استثنای مناسب (EOFError، ValueError یا TypeError) را تنظیم می‌کند و NULL را برمی‌گرداند.

PyObject *PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)

مقدار بازگشتی: مرجع جدید.

یک شیء پایتون را از جریان داده در یک بافر بایت شامل len بایت که data به آن اشاره می‌کند، برمی‌گرداند.

در صورت خطا، استثنای مناسب (EOFError، ValueError یا TypeError) را تنظیم می‌کند و NULL را برمی‌گرداند.