پروتکل tp_call¶

نمونه‌های کلاس‌هایی که tp_call را تنظیم می‌کنند، فراخوانی‌پذیر هستند. امضای این جایگاه به صورت زیر است:

PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs);

فراخوانی با استفاده از یک تاپل برای آرگومان‌های جایگاهی و یک دیکشنری برای آرگومان‌های کلیدواژه‌ای انجام می‌شود، مشابه callable(*args, **kwargs) در کد پایتون. args باید غیر NULL باشد (اگر آرگومانی وجود ندارد، از یک تاپل خالی استفاده کنید) اما kwargs در صورت نبود آرگومان‌های کلیدواژه‌ای می‌تواند NULL باشد.

این قرارداد تنها توسط tp_call استفاده نمی‌شود: tp_new و tp_init نیز آرگومان‌ها را به این روش پاس می‌دهند.

برای فراخوانی یک شیء، از PyObject_Call() یا API فراخوانی دیگری استفاده کنید.

پروتکل Vectorcall¶

پروتکل vectorcall در PEP 590 به‌عنوان پروتکلی اضافی برای کارآمدتر کردن فراخوانی‌ها معرفی شد.

به عنوان یک قاعده سرانگشتی، سی‌پایتون برای فراخوانی‌های داخلی vectorcall را ترجیح می‌دهد، مشروط به اینکه فراخوانی‌پذیر از آن پشتیبانی کند. با این حال، این یک قاعده سفت و سخت نیست. افزون بر این، برخی افزونه‌های شخص ثالث مستقیماً از tp_call استفاده می‌کنند (به‌جای استفاده از PyObject_Call()). بنابراین، کلاسی که از vectorcall پشتیبانی می‌کند باید tp_call را نیز پیاده‌سازی کند. به‌علاوه، فراخوانی‌پذیر باید فارغ از اینکه از کدام پروتکل استفاده می‌شود، رفتار یکسانی داشته باشد. راه توصیه‌شده برای دستیابی به این هدف، تنظیم tp_call روی PyVectorcall_Call() است. این نکته شایان تکرار است:

یک کلاس نباید vectorcall را پیاده‌سازی کند اگر این کار کندتر از tp_call باشد. برای مثال، اگر فراخوانی‌شونده به هر حال نیاز داشته باشد که آرگومان‌ها را به تاپل args و دیکشنری kwargs تبدیل کند، آنگاه پیاده‌سازی vectorcall فایده‌ای ندارد.

کلاس‌ها می‌توانند پروتکل vectorcall را با فعال کردن پرچم Py_TPFLAGS_HAVE_VECTORCALL و تنظیم tp_vectorcall_offset به آفست درون ساختار شیء که یک vectorcallfunc در آن قرار دارد، پیاده‌سازی کنند. این یک اشاره‌گر به تابعی با امضای زیر است:

typedef PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

• callable شیءی است که فراخوانی می‌شود.

• مقادیر آرگومان‌های کلیدواژه‌ای. در صورت نبود آرگومان، این می‌تواند NULL باشد.

• پرچم PY_VECTORCALL_ARGUMENTS_OFFSET. برای به‌دست‌آوردن تعداد واقعی آرگومان‌های جایگاهی از nargsf، از PyVectorcall_NARGS() استفاده کنید.

• به عبارت دیگر، کلیدهای دیکشنری kwargs. این نام‌ها باید رشته باشند (نمونه‌هایی از str یا یک زیرکلاس) و باید یکتا باشند. اگر آرگومان کلیدواژه‌ای وجود نداشته باشد، kwnames می‌تواند به‌جای آن NULL باشد.

PY_VECTORCALL_ARGUMENTS_OFFSET¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

اگر این پرچم در آرگومان nargsf مربوط به vectorcall تنظیم شده باشد، به فراخوانی‌شونده اجازه داده می‌شود که args[-1] را به‌طور موقت تغییر دهد. به عبارت دیگر، args به آرگومان ۱ (نه ۰) در بردار تخصیص‌یافته اشاره می‌کند. فراخوانی‌شونده باید پیش از بازگشت، مقدار args[-1] را بازگرداند.

برای PyObject_VectorcallMethod()، این پرچم در عوض به این معنا است که args[0] ممکن است تغییر کند.

هرگاه بتوانند این کار را با هزینه‌ی اندکی انجام دهند (بدون تخصیص اضافی)، به فراخوان‌کنندگان توصیه می‌شود که از PY_VECTORCALL_ARGUMENTS_OFFSET استفاده کنند. انجام این کار به فراخوانی‌پذیرهایی مانند متدهای مقید اجازه می‌دهد تا فراخوانی‌های بعدی خود (که آرگومان self در ابتدای آن‌ها افزوده شده است) را به‌طور بسیار کارآمد انجام دهند.

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

برای فراخوانی شیء‌ای که vectorcall را پیاده‌سازی می‌کند، مانند هر فراخوانی‌پذیر دیگری از یک تابع API فراخوانی استفاده کنید. PyObject_Vectorcall() معمولاً کارآمدترین خواهد بود.

API فراخوانی شیء¶

توابع گوناگونی برای فراخوانی یک شیء پایتون در دسترس هستند. هر یک از این توابع، آرگومان‌های خود را به قراردادی که شیء فراخوانی‌شده از آن پشتیبانی می‌کند — یعنی tp_call یا vectorcall — تبدیل می‌کند. برای انجام کمترین تبدیل ممکن، تابعی را انتخاب کنید که بهترین تناسب را با قالب داده‌های در دسترس شما دارد.

جدول زیر خلاصه‌ای از توابع موجود را ارائه می‌دهد؛ برای جزئیات، لطفاً به مستندات هر یک مراجعه کنید.

PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)¶

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

شیء فراخوانی‌پذیر پایتون callable را با آرگومان‌هایی که توسط تاپل args داده شده‌اند و آرگومان‌های نام‌داری که توسط دیکشنری kwargs داده شده‌اند، فراخوانی می‌کند.

args نباید NULL باشد؛ اگر هیچ آرگومانی لازم نیست، از یک تاپل خالی استفاده کنید. اگر هیچ آرگومان نام‌داری لازم نیست، kwargs می‌تواند NULL باشد.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

این معادل عبارت پایتونی callable(*args, **kwargs) است.

PyObject *PyObject_CallNoArgs(PyObject *callable)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.10.

یک شیء پایتونی فراخوانی‌پذیر callable را بدون هیچ آرگومانی فراخوانی می‌کند. این کارآمدترین راه برای فراخوانی یک شیء پایتونی فراخوانی‌پذیر بدون هیچ آرگومانی است.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

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

PyObject *PyObject_CallOneArg(PyObject *callable, PyObject *arg)¶

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

یک شیء فراخوانی‌پذیر پایتون callable را با دقیقاً ۱ آرگومان جایگاهی arg و بدون هیچ آرگومان کلیدواژه‌ای فراخوانی می‌کند.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

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

PyObject *PyObject_CallObject(PyObject *callable, PyObject *args)¶

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

شیء فراخوانی‌پذیر پایتون callable را با آرگومان‌های داده‌شده توسط تاپل args فراخوانی می‌کند. اگر نیازی به آرگومان نباشد، args می‌تواند NULL باشد.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

این معادل عبارت زیر در پایتون است: callable(*args).

PyObject *PyObject_CallFunction(PyObject *callable, const char *format, ...)¶

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

شیء پایتون فراخوانی‌پذیر callable را با تعداد متغیری از آرگومان‌های C فراخوانی می‌کند. آرگومان‌های C با استفاده از رشته قالب به سبک Py_BuildValue() توصیف می‌شوند. قالب می‌تواند NULL باشد که نشان می‌دهد هیچ آرگومانی ارائه نشده است.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

این معادل عبارت زیر در پایتون است: callable(*args).

توجه داشته باشید که اگر فقط آرگومان‌های PyObject* را ارسال کنید، PyObject_CallFunctionObjArgs() جایگزین سریع‌تری است.

تغییر یافته در نسخه‌ی 3.4: نوع format از char * تغییر کرد.

PyObject *PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)¶

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

متدی با نام name از شیء obj را با تعداد متغیری از آرگومان‌های C فراخوانی می‌کند. آرگومان‌های C توسط یک رشته قالب Py_BuildValue() توصیف می‌شوند که باید یک تاپل تولید کند.

قالب می‌تواند NULL باشد که نشان می‌دهد هیچ آرگومانی ارائه نمی‌شود.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

این معادل عبارت پایتون obj.name(arg1, arg2, ...) است.

توجه داشته باشید که اگر تنها آرگومان‌هایی از نوع PyObject* را عبور می‌دهید، PyObject_CallMethodObjArgs() جایگزین سریع‌تری است.

تغییر یافته در نسخه‌ی 3.4: نوع‌های name و format از char * تغییر یافتند.

PyObject *PyObject_CallFunctionObjArgs(PyObject *callable, ...)¶

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

یک شیء پایتونی فراخوانی‌پذیر callable را با تعداد متغیری آرگومان PyObject* فراخوانی می‌کند. آرگومان‌ها به‌صورت تعداد متغیری پارامتر و به‌دنبال آن NULL ارائه می‌شوند.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

این معادل عبارت پایتون callable(arg1, arg2, ...) است.

PyObject *PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ...)¶

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

متدی از شیء پایتونی obj را فراخوانی می‌کند که نام آن به‌صورت یک شیء رشته پایتون در name داده شده است. این متد با تعداد متغیری از آرگومان‌های PyObject* فراخوانی می‌شود. آرگومان‌ها به‌صورت تعداد متغیری از پارامترها و در پایان NULL ارائه می‌شوند.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

PyObject *PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name)¶

متدی از شیء پایتون obj را بدون آرگومان فراخوانی می‌کند، که در آن نام متد به‌صورت یک شیء رشته پایتون در name داده شده است.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

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

PyObject *PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg)¶

متدی از شیء پایتون obj را با تنها یک آرگومان جایگاهی arg فراخوانی می‌کند، که نام متد به‌صورت یک شیء رشته پایتون در name داده می‌شود.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

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

PyObject *PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames)¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

شیء پایتونی فراخوانی‌پذیر callable را فراخوانی می‌کند. آرگومان‌ها همانند آرگومان‌های vectorcallfunc هستند. اگر callable از vectorcall پشتیبانی کند، این تابع مستقیماً تابع vectorcall ذخیره‌شده در callable را فراخوانی می‌کند.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.8: به‌عنوان _PyObject_Vectorcall

تغییر یافته در نسخه‌ی 3.9: به نام کنونی تغییر نام داده شد، بدون زیرخط ابتدایی. نام آزمایشی قبلی soft deprecated است.

PyObject *PyObject_VectorcallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict)¶

فراخوانی‌پذیر callable را با آرگومان‌های جایگاهی که دقیقاً مطابق پروتکل vectorcall ارسال می‌شوند فراخوانی می‌کند، اما آرگومان‌های کلیدواژه‌ای به‌صورت دیکشنری kwdict ارسال می‌شوند. آرایه args فقط شامل آرگومان‌های جایگاهی است.

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

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

PyObject *PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames)¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

یک متد را با استفاده از قرارداد فراخوانی vectorcall فراخوانی کنید. نام متد به صورت رشته پایتون name داده می‌شود. شیء‌ای که متد آن فراخوانی می‌شود args[0] است و آرایه args که از args[1] آغاز می‌شود، آرگومان‌های فراخوانی را نشان می‌دهد. باید حداقل یک آرگومان جایگاهی وجود داشته باشد. nargsf تعداد آرگومان‌های جایگاهی شامل args[0] است، به‌علاوه PY_VECTORCALL_ARGUMENTS_OFFSET در صورتی که مقدار args[0] ممکن است به‌طور موقت تغییر کند. آرگومان‌های کلیدواژه‌ای را می‌توان دقیقاً مشابه PyObject_Vectorcall() ارسال کرد.

اگر شیء قابلیت Py_TPFLAGS_METHOD_DESCRIPTOR را داشته باشد، این، شیء متد غیرمقید را با بردار کامل args به‌عنوان آرگومان‌ها فراخوانی می‌کند.

در صورت موفقیت، نتیجه‌ی فراخوانی را برمی‌گرداند، یا در صورت شکست، استثنا ایجاد کرده و NULL را برمی‌گرداند.

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

API پشتیبانی فراخوانی¶

int PyCallable_Check(PyObject *o)¶

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

تعیین می‌کند که آیا شیء o فراخوانی‌پذیر است یا خیر. اگر شیء فراخوانی‌پذیر باشد 1 و در غیر این صورت 0 را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.