اشیاء پرونده¶

این API‌ها شبیه‌سازی حداقلی از C API پایتون 2 برای اشیای پرونده توکار هستند، که پیش‌تر به پشتیبانی ورودی/خروجی بافرشده (FILE*) از کتابخانه استاندارد C تکیه داشت. در پایتون 3، پرونده‌ها و جریان‌ها از ماژول جدید io استفاده می‌کنند که چندین لایه را روی ورودی/خروجی سطح پایین و بدون بافر سیستم‌عامل تعریف می‌کند. توابعی که در ادامه توضیح داده شده‌اند، پوشش‌های C راحتی روی این API‌های جدید هستند و عمدتاً برای گزارش خطای داخلی در مفسر در نظر گرفته شده‌اند؛ به کد شخص ثالث توصیه می‌شود که به جای آن‌ها به API‌های io دسترسی داشته باشد.

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)¶

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

یک شیء پرونده‌ی پایتون از توصیف‌گر پرونده‌ی از پیش باز‌شده‌ی fd ایجاد می‌کند. آرگومان‌های name، encoding، errors و newline می‌توانند NULL باشند تا از مقادیر پیش‌فرض استفاده شود؛ buffering می‌تواند -1 باشد تا از مقدار پیش‌فرض استفاده شود. name نادیده گرفته می‌شود و برای سازگاری با نسخه‌های قبلی نگه داشته شده است. در صورت شکست، NULL برگردانده می‌شود. برای توضیحات جامع‌تر درباره‌ی آرگومان‌ها، لطفاً به مستندات تابع io.open() مراجعه کنید.

هشدار

از آنجا که جریان‌های پایتون لایه بافرینگ اختصاصی خود را دارند، ترکیب آن‌ها با توصیف‌گرهای پرونده در سطح سیستم‌عامل می‌تواند مشکلات گوناگونی (مانند ترتیب غیرمنتظره داده‌ها) ایجاد کند.

تغییر یافته در نسخه‌ی 3.2: ویژگی name را نادیده بگیرید.

int PyObject_AsFileDescriptor(PyObject *p)¶

قسمتی از ABI پایدار.

توصیف‌گر پرونده مرتبط با p را به‌صورت int برمی‌گرداند. اگر شیء یک عدد صحیح باشد، مقدار آن برگردانده می‌شود. در غیر این صورت، متد fileno() شیء در صورت وجود فراخوانی می‌شود؛ این متد باید یک عدد صحیح برگرداند که به‌عنوان مقدار توصیف‌گر پرونده برگردانده می‌شود. در صورت شکست، یک استثنا تنظیم می‌کند و -1 برمی‌گرداند.

PyObject *PyFile_GetLine(PyObject *p, int n)¶

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

این تابع معادل p.readline([n]) است و یک سطر از شیء p می‌خواند. p می‌تواند یک شیء پرونده یا هر شیء دارای متد readline() باشد. اگر n برابر 0 باشد، دقیقاً یک سطر خوانده می‌شود، بدون توجه به طول سطر. اگر n بزرگ‌تر از 0 باشد، بیش از n بایت از پرونده خوانده نمی‌شود؛ ممکن است سطر ناقصی برگردانده شود. در هر دو حالت، اگر بلافاصله به پایان پرونده برسیم، رشته‌ای خالی برگردانده می‌شود. اما اگر n کوچک‌تر از 0 باشد، یک سطر بدون توجه به طول خوانده می‌شود، ولی اگر بلافاصله به پایان پرونده برسیم، EOFError پرتاب می‌شود.

char *Py_UniversalNewlineFgets(char *buf, int n, FILE *stream, PyObject *fobj)¶

یک سطر را از جریان (stream) C با نام stream در بافر buf بخوانید، درست مانند تابع کتابخانه‌ی استاندارد C یعنی fgets()، با این تفاوت که تمام موارد \n، \r و \r\n را به عنوان پایان‌دهنده‌های سطر در نظر می‌گیرد (به سطرهای جدید همگانی مراجعه کنید). هر \r یا \r\n خوانده‌شده از جریان، به عنوان یک \n واحد در buf ذخیره می‌شود.

حداکثر n - 1 نویسه در buf ذخیره می‌شود؛ خواندن پس از ذخیره‌شدن یک نویسه‌ی سطر جدید یا رسیدن به انتهای پرونده متوقف می‌شود. نتیجه همیشه دارای پایان‌دهنده‌ی تهی (null-terminated) است. stream باید در حالت دودویی باز شود تا کتابخانه‌ی C ترجمه‌ی سطر جدید خود را انجام ندهد.

در صورت موفقیت، buf را برگردانید. اگر هیچ نویسه‌ای قابل خواندن نباشد، به این دلیل که stream در انتهای پرونده است، خطای خواندنی رخ داده است، یا n کمتر از ۲ است، NULL را برگردانید. درست مانند fgets()، این تابع بین انتهای پرونده و خطای خواندن تمایز قائل نمی‌شود و استثنایی را تنظیم نمی‌کند.

مورد fobj صرفاً برای سازگاری عقبگرد وجود دارد و باید NULL باشد.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)¶

رفتار عادی io.open_code() را بازتعریف می‌کند تا پارامتر خود را از هندلر ارائه‌شده عبور دهد.

هندلر تابعی از نوع زیر است:

typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)¶

معادل PyObject *(*)(PyObject *path, void *userData) است که در آن تضمین می‌شود path از نوع PyUnicodeObject باشد.

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

از آنجا که این قلاب عمداً در زمان ایمپورت استفاده می‌شود، از ایمپورت کردن ماژول‌های جدید در حین اجرای آن خودداری کنید، مگر آنکه مشخص باشد که فریزشده هستند یا در sys.modules موجود هستند.

پس از آنکه یک قلاب تنظیم شده باشد، نمی‌توان آن را حذف یا جایگزین کرد و فراخوانی‌های بعدی PyFile_SetOpenCodeHook() شکست خواهند خورد. در صورت شکست، تابع مقدار -1 را برمی‌گرداند و اگر مفسر مقداردهی اولیه شده باشد، یک استثنا تنظیم می‌کند.

فراخوانی این تابع پیش از Py_Initialize() ایمن است.

رویداد حسابرسی setopencodehook را بدون هیچ آرگومانی ایجاد می‌کند.

اضافه شده در نسخه‌ی 3.8.

PyObject *PyFile_OpenCodeObject(PyObject *path)¶

path را با حالت 'rb' باز می‌کند. path باید یک شیء str پایتون باشد. رفتار این تابع ممکن است توسط PyFile_SetOpenCodeHook() بازنویسی شود تا امکان انجام پیش‌پردازش‌هایی روی متن فراهم شود.

این مشابه io.open_code() در پایتون است.

در صورت موفقیت، این تابع یک strong reference به یک شیء پرونده‌ی پایتون برمی‌گرداند. در صورت شکست، این تابع NULL را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

اضافه شده در نسخه‌ی 3.8.

PyObject *PyFile_OpenCode(const char *path)¶

مشابه PyFile_OpenCodeObject()، اما path یک const char* کدگذاری‌شده با UTF-8 است.

اضافه شده در نسخه‌ی 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)¶

قسمتی از ABI پایدار.

شیء obj را در شیء پرونده p می‌نویسد. تنها پرچم پشتیبانی‌شده برای flags، Py_PRINT_RAW است؛ در صورت ارائه، str() شیء به‌جای repr() آن نوشته می‌شود.

اگر obj برابر NULL باشد، رشته‌ی "<NULL>" نوشته می‌شود.

در صورت موفقیت 0 و در صورت شکست -1 را برمی‌گرداند؛ استثنای مناسب تنظیم خواهد شد.

int PyFile_WriteString(const char *s, PyObject *p)¶

قسمتی از ABI پایدار.

رشته s را در شیء پرونده p می‌نویسد. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند؛ استثنای مناسب تنظیم خواهد شد.