کپسول‌ها (Capsules)

برای اطلاعات بیشتر درباره استفاده از این اشیاء، به ارائه‌ی یک C API برای ماژول توسعه‌ای مراجعه کنید.

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

type PyCapsule

این زیرنوع از PyObject نمایانگر یک مقدار مات است و برای ماژول‌های توسعه‌ای C که نیاز دارند مقداری مات را (به‌صورت اشاره‌گر void*) از طریق کد پایتون به کد C دیگری منتقل کنند، مفید است. این نوع اغلب برای در اختیار ماژول‌های دیگر قرار دادن اشاره‌گر تابع C تعریف‌شده در یک ماژول استفاده می‌شود، به‌طوری که بتوان از سازوکار ایمپورت معمول برای دسترسی به APIهای C تعریف‌شده در ماژول‌های بارگذاری‌شده به‌صورت پویا استفاده کرد.

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

شیء نوعِ متناظر با شیءهای کپسول. این همان شیء types.CapsuleType در لایه‌ی پایتون است.

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

نوع کال‌بک مخرب برای یک کپسول. به صورت زیر تعریف می‌شود:

typedef void (*PyCapsule_Destructor)(PyObject *);

برای آگاهی از معناشناسی کال‌بک‌های PyCapsule_Destructor به PyCapsule_New() مراجعه کنید.

int PyCapsule_CheckExact(PyObject *p)
Thread safety: Atomic.

اگر آرگومان آن یک PyCapsule باشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.

یک PyCapsule ایجاد می‌کند که اشاره‌گر را کپسوله می‌کند. آرگومان اشاره‌گر نمی‌تواند NULL باشد.

در صورت شکست، یک استثنا تنظیم کرده و NULL را برگردانید.

رشته name می‌تواند NULL یا اشاره‌گری به یک رشته C معتبر باشد. اگر NULL نباشد، این رشته باید بیشتر از کپسول عمر کند. (هرچند آزاد کردن آن درون مخرب مجاز است.)

اگر آرگومان مخرب NULL نباشد، هنگامی که کپسول نابود می‌شود، با کپسول به‌عنوان آرگومان آن فراخوانی خواهد شد.

اگر این کپسول قرار است به‌عنوان ویژگی یک ماژول ذخیره شود، نام باید به‌صورت modulename.attributename مشخص شود. این کار به ماژول‌های دیگر امکان می‌دهد کپسول را با استفاده از PyCapsule_Import() ایمپورت کنند.

void *PyCapsule_GetPointer(PyObject *capsule, const char *name)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

اشاره‌گر ذخیره‌شده در کپسول را بازیابی می‌کند. در صورت شکست، یک استثنا تنظیم می‌کند و NULL را برمی‌گرداند.

پارامتر name باید دقیقاً با نام ذخیره‌شده در کپسول مقایسه شود. اگر نام ذخیره‌شده در کپسول NULL باشد، name گذرانده‌شده نیز باید NULL باشد. پایتون برای مقایسه‌ی نام کپسول‌ها از تابع C strcmp() استفاده می‌کند.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

مخرب فعلی ذخیره‌شده در کپسول را بازمی‌گرداند. در صورت شکست، یک استثنا تنظیم کرده و NULL را بازمی‌گرداند.

داشتن مخرب NULL برای یک کپسول مجاز است. این امر کد بازگشتی NULL را تا حدی مبهم می‌کند؛ برای رفع ابهام، از PyCapsule_IsValid() یا PyErr_Occurred() استفاده کنید.

void *PyCapsule_GetContext(PyObject *capsule)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

زمینه فعلی ذخیره‌شده در کپسول را بازمی‌گرداند. در صورت شکست، یک استثنا تنظیم کرده و NULL را بازمی‌گرداند.

داشتن زمینه NULL برای یک کپسول مجاز است. این امر کد بازگشتی NULL را تا حدی مبهم می‌کند؛ برای رفع ابهام از PyCapsule_IsValid() یا PyErr_Occurred() استفاده کنید.

const char *PyCapsule_GetName(PyObject *capsule)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

نام فعلی ذخیره‌شده در کپسول را برمی‌گرداند. در صورت شکست، یک استثنا تنظیم کرده و NULL را برمی‌گرداند.

مجاز است که یک کپسول نام NULL داشته باشد. این امر کد بازگشتی NULL را تا حدی مبهم می‌کند؛ برای رفع ابهام، از PyCapsule_IsValid() یا PyErr_Occurred() استفاده کنید.

void *PyCapsule_Import(const char *name, int no_block)
قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

اشاره‌گر به یک شیء C را از یک ویژگی کپسول در یک ماژول ایمپورت می‌کند. پارامتر name باید نام کامل ویژگی را مشخص کند، مانند module.attribute. name ذخیره‌شده در کپسول باید دقیقاً با این رشته مطابقت داشته باشد.

این تابع name را بر اساس نویسه‌ی . تجزیه می‌کند و اولین عنصر را ایمپورت می‌کند. سپس عناصر بعدی را با استفاده از جستجوهای ویژگی پردازش می‌کند.

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

توجه

اگر name به ویژگی‌ای از یک زیرماژول یا زیربسته اشاره کند، این زیرماژول یا زیربسته باید پیش‌تر به روشی دیگر ایمپورت شده باشد (برای مثال، با استفاده از PyImport_ImportModule()) تا جستجوی ویژگی‌ها با موفقیت انجام شود.

تغییر یافته در نسخه‌ی 3.3: no_block دیگر هیچ تأثیری ندارد.

int PyCapsule_IsValid(PyObject *capsule, const char *name)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

تعیین می‌کند که capsule یک کپسول معتبر است یا خیر. یک کپسول معتبر غیر NULL است، از PyCapsule_CheckExact() عبور می‌کند، اشاره‌گری غیر NULL در آن ذخیره شده است، و نام داخلی آن با پارامتر name مطابقت دارد. (برای اطلاعات درباره‌ی نحوه‌ی مقایسه‌ی نام‌های کپسول، PyCapsule_GetPointer() را ببینید.)

به عبارت دیگر، اگر PyCapsule_IsValid() مقداری درست برگرداند، موفقیت فراخوانی هر یک از دسترسی‌دهنده‌ها (accessor) (هر تابعی که با PyCapsule_Get شروع می‌شود) تضمین می‌شود.

اگر شیء معتبر باشد و با نام ارسال‌شده مطابقت داشته باشد، مقدار ناصفر بازگردانده می‌شود. در غیر این صورت 0 بازگردانده می‌شود. این تابع شکست نخواهد خورد.

int PyCapsule_SetContext(PyObject *capsule, void *context)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

اشاره‌گر زمینه درون capsule را برابر context قرار می‌دهد.

در صورت موفقیت 0 را برمی‌گرداند. در صورت شکست، مقداری غیر از صفر برمی‌گرداند و یک استثنا تنظیم می‌کند.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

مخرب درون capsule را برابر destructor قرار دهید.

در صورت موفقیت 0 را برمی‌گرداند. در صورت شکست، مقداری غیر از صفر برمی‌گرداند و یک استثنا تنظیم می‌کند.

int PyCapsule_SetName(PyObject *capsule, const char *name)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

نام داخل capsule را برابر name قرار می‌دهد. اگر NULL نباشد، نام باید از کپسول عمر بیشتری داشته باشد. اگر name قبلیِ ذخیره‌شده در کپسول NULL نبوده باشد، هیچ تلاشی برای آزاد کردن آن صورت نمی‌گیرد.

در صورت موفقیت 0 را برمی‌گرداند. در صورت شکست، مقداری غیر از صفر برمی‌گرداند و یک استثنا تنظیم می‌کند.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
قسمتی از ABI پایدار. Thread safety: Safe to call without external synchronization on distinct objects.

اشاره‌گر void درون capsule را برابر pointer قرار می‌دهد. این اشاره‌گر نمی‌تواند NULL باشد.

در صورت موفقیت 0 را برمی‌گرداند. در صورت شکست، مقداری غیر از صفر برمی‌گرداند و یک استثنا تنظیم می‌کند.