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

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

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

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

The following exceptions can be raised by these functions: ValueError if the value cannot be marshalled, ValueError or TypeError if the data is malformed, EOFError if the end of the data is reached before the value is complete, OSError if reading from or writing to a FILE* fails, KeyboardInterrupt if reading or writing is interrupted by a signal, and MemoryError if memory allocation fails.

تغییر یافته در نسخه‌ی 3.16: Previously, in functions taking a FILE*, the reading functions raised EOFError instead of OSError and KeyboardInterrupt, and the writing functions ignored I/O errors and interruptions.

Py_MARSHAL_VERSION

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

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

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

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

نکته

در پایتون ۳.۱۵ و قبل‌تر، این تابع نشانگری برای خطا تنظیم نمی‌کند، اگر نوشتن در file شکست بخورد، همان محدودیت مشابه برای PyMarshal_WriteObjectToFile() برقرار است.

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

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

The marshalled representation of value is built in memory and then written to file. Nothing is written if value cannot be marshalled.

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

نکته

در پایتون ۳.۱۵ و قبلتر، این تابع فقط می‌تواند قسمتی از اطلاعات را در پرونده بنویسد و بدون تنظیم کردن نشانگر خطا برگرداند، برای مثال اگر مقدار شامل یک شیء‌ای که نمی‌تواند مارشال شود یا اگر نوشتن در پرونده شکست بخورد (به gh-155907 مراجعه کنید). کدی که باید این نسخه‌ها را پشتیبانی کند نمی‌تواند به تنهایی به PyErr_Occurred() تکیه کند تا بداند همه‌ی اطلاعات نوشته شده است. می‌تواند از PyMarshal_WriteObjectToString() استفاده کند و خودش نتیجه را بنویسد یا صحت‌سنجی کند آنچه نوشته شده است.

تغییر یافته در نسخه‌ی 3.16: Previously, the data was written to file as it was produced, using a buffer of constant size, and incomplete data was written if value could not be marshalled.

PyObject *PyMarshal_WriteObjectToString(PyObject *value, int version)

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

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

On error, raises an exception and returns NULL.

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

long PyMarshal_ReadLongFromFile(FILE *file)

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

On error, raises an exception and returns -1.

int PyMarshal_ReadShortFromFile(FILE *file)

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

On error, raises an exception and returns -1.

PyObject *PyMarshal_ReadObjectFromFile(FILE *file)

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

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

On error, raises an exception and returns NULL.

PyObject *PyMarshal_ReadLastObjectFromFile(FILE *file)

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

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

On error, raises an exception and returns NULL.

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

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

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

On error, raises an exception and returns NULL.