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

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

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

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

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 قالب پرونده را مشخص می‌کند.

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

نکته

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

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 را برمی‌گرداند.