اشیاء تاپل

type PyTupleObject

این زیرنوع از PyObject معرف یک شیء تاپل پایتون است.

PyTypeObject PyTuple_Type

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

این نمونه از PyTypeObject نوع تاپل پایتون را نشان می‌دهد؛ این همان شیء tuple در لایه‌ی پایتون است.

int PyTuple_Check(PyObject *p)

اگر p یک شیء تاپل یا نمونه‌ای از یک زیرنوع از نوع تاپل باشد، مقدار true را برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyTuple_CheckExact(PyObject *p)

اگر p یک شیء تاپل باشد، اما نمونه‌ای از زیرنوعی از نوع تاپل نباشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyObject *PyTuple_New(Py_ssize_t len)

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

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

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)

Thread safety: Atomic.

Create a tuple of size items and copy references from array to the new tuple.

array can be NULL if size is 0.

On success, return a new reference. On error, set an exception and return NULL.

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

PyObject *PyTuple_Pack(Py_ssize_t n, ...)

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

یک شیء تاپل جدید با اندازه‌ی n برمی‌گرداند، یا در صورت شکست NULL به همراه یک استثنای تنظیم‌شده برمی‌گرداند. مقادیر تاپل به n آرگومان C بعدی که به اشیاء پایتون اشاره می‌کنند، مقداردهی اولیه می‌شوند. PyTuple_Pack(2, a, b) معادل Py_BuildValue("(OO)", a, b) است.

Py_ssize_t PyTuple_Size(PyObject *p)

قسمتی از ABI پایدار. Thread safety: Atomic.

یک اشاره‌گر به شیء تاپل می‌گیرد و اندازه‌ی آن تاپل را برمی‌گرداند. در صورت خطا، -1 همراه با استثنای تنظیم‌شده برمی‌گرداند.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)

Thread safety: Atomic.

مانند PyTuple_Size()، اما بدون بررسی خطا.

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

شیء در موقعیت pos در تاپلی که توسط p به آن اشاره می‌شود را برمی‌گرداند. اگر pos منفی یا خارج از محدوده باشد، NULL را برمی‌گرداند و یک استثنای IndexError تنظیم می‌کند.

ارجاع بازگردانده‌شده از تاپل p امانت گرفته شده است (یعنی: تنها تا زمانی که شما ارجاعی به p را در اختیار دارید معتبر است). برای به دست آوردن ارجاع قوی، از Py_NewRef(PyTuple_GetItem(...)) یا PySequence_GetItem() استفاده کنید.

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.

مانند PyTuple_GetItem()، اما هیچ بررسی‌ای روی آرگومان‌های خود انجام نمی‌دهد.

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)

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

اسلایس تاپلی را که p به آن اشاره می‌کند، بین low و high برمی‌گرداند، یا در صورت شکست NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند.

این معادل عبارت پایتونی p[low:high] است. اندیس‌گذاری از انتهای تاپل پشتیبانی نمی‌شود.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

Insert a reference to object o at position pos of the tuple pointed to by p. Return 0 on success. If pos is out of bounds, return -1 and set an IndexError exception. This function should only be used to fill in brand new tuples; using it on an existing tuple is thread-unsafe.

توجه

این تابع ارجاعی به o را «می‌دزدد (steal)» و ارجاع به آیتمی را که از قبل در جایگاه مورد تأثیر تاپل قرار دارد، دور می‌ریزد (مگر اینکه NULL بوده باشد).

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)

Thread safety: Safe to call from multiple threads with external synchronization only.

Like PyTuple_SetItem(), but does no error checking, and should only be used to fill in brand new tuples, using it on an existing tuple is thread-unsafe.

اگر پایتون در حالت اشکال‌زدایی یا با ادعاها ساخته شده باشد، بررسی کران‌ها به‌صورت یک ادعا انجام می‌شود.

توجه

این تابع ارجاعی به o را «می‌دزدد» و برخلاف PyTuple_SetItem()، ارجاع به هیچ آیتمی را که در حال جایگزینی است دور نمی‌اندازد؛ هر ارجاعی که در جایگاه pos از تاپل باشد، نشت خواهد شد.

هشدار

این ماکرو باید تنها روی تاپل‌هایی که به‌تازگی ایجاد شده‌اند استفاده شود. استفاده از این ماکرو روی تاپلی که از قبل در حال استفاده است (یا به عبارت دیگر، شمارش ارجاع آن بزرگ‌تر از ۱ است) ممکن است به رفتار تعریف‌نشده منجر شود.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)

Thread safety: Safe to call from multiple threads with external synchronization only.

می‌تواند برای تغییر اندازه‌ی یک تاپل استفاده شود. newsize طول جدید تاپل خواهد بود. از آنجا که تاپل‌ها قرار است تغییرناپذیر باشند، این تابع فقط باید زمانی استفاده شود که تنها یک ارجاع به شیء وجود داشته باشد. اگر ممکن است تاپل از قبل توسط بخش دیگری از کد شناخته شده باشد، از این تابع استفاده نکنید. تاپل همیشه از انتها بزرگ‌تر یا کوچک‌تر می‌شود. این کار را به‌عنوان نابود کردن تاپل قدیمی و ایجاد یک تاپل جدید در نظر بگیرید، فقط با کارایی بیشتر. در صورت موفقیت 0 را برمی‌گرداند. کد کلاینت هرگز نباید فرض کند که مقدار حاصل *p با مقدار قبل از فراخوانی این تابع یکسان خواهد بود. اگر شیء ارجاع‌شده توسط *p جایگزین شود، *p اصلی نابود می‌شود. در صورت شکست، -1 را برمی‌گرداند، *p را برابر NULL قرار می‌دهد و MemoryError یا SystemError ایجاد می‌کند.

اشیاء دنباله ساختاری

A struct sequence object is a named tuple, that is, a sequence whose items can also be accessed through attributes. It is similar to collections.namedtuple(), but provides a slightly different interface.

To create a struct sequence, you first have to create a specific struct sequence type.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)

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

نوع دنباله ساختاری جدیدی از داده‌های موجود در desc که در ادامه توضیح داده شده است، ایجاد می‌کند. نمونه‌های نوع حاصل را می‌توان با PyStructSequence_New() ایجاد کرد.

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

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

نوع دنباله ساختاری type را از روی desc به‌صورت درجا مقداردهی اولیه می‌کند.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)

Thread safety: Safe to call without external synchronization on distinct objects.

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

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

type PyStructSequence_Desc

قسمتی از ABI پایدار شامل تمام اعضا.

شامل فراطلاعات نوع دنباله ساختاری‌ای است که باید ایجاد شود.

const char *name

نام کامل نوع؛ پایان‌یافته با تهی و کدگذاری‌شده با UTF-8. نام باید شامل نام ماژول باشد.

const char *doc

اشاره‌گر به رشته‌ی مستند برای نوع، یا NULL برای حذف آن.

PyStructSequence_Field *fields

اشاره‌گر به آرایه‌ی خاتمه‌یافته با NULL حاوی نام فیلدهای نوع جدید.

int n_in_sequence

تعداد فیلدهای قابل مشاهده برای سمت پایتون (در صورت استفاده به‌عنوان تاپل).

type PyStructSequence_Field

قسمتی از ABI پایدار شامل تمام اعضا.

یک فیلد از دنباله ساختاری را توصیف می‌کند. از آنجا که دنباله ساختاری به‌صورت یک تاپل مدل‌سازی می‌شود، همه‌ی فیلدها از نوع PyObject* هستند. اندیس در آرایه‌ی fields از PyStructSequence_Desc تعیین می‌کند که کدام فیلد از دنباله ساختاری توصیف می‌شود.

const char *name

نام فیلد یا NULL برای پایان دادن به فهرست فیلدهای نام‌دار؛ برای بی‌نام گذاشتن فیلد، روی PyStructSequence_UnnamedField تنظیم می‌شود.

const char *doc

رشته مستند فیلد یا NULL برای حذف.

const char *const PyStructSequence_UnnamedField

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

مقدار ویژه برای نام فیلد که آن را بی‌نام باقی می‌گذارد.

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

PyObject *PyStructSequence_New(PyTypeObject *type)

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

یک نمونه از type ایجاد می‌کند که باید با PyStructSequence_NewType() ایجاد شده باشد.

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

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

Return the object at position pos in the struct sequence pointed to by p. The returned reference is borrowed from the struct sequence p (that is: it is only valid as long as you hold a reference to p).

اگر پایتون در حالت اشکال‌زدایی یا با ادعاها ساخته شده باشد، بررسی کران‌ها به‌صورت یک ادعا انجام می‌شود.

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)

مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.

نام مستعاری برای PyStructSequence_GetItem() است.

تغییر یافته در نسخه‌ی 3.13: اکنون به عنوان مستعاری برای PyStructSequence_GetItem() پیاده‌سازی شده است.

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)

قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.

فیلد در اندیس pos از دنباله ساختاری p را به مقدار o تنظیم می‌کند. مانند PyTuple_SET_ITEM()، این باید فقط برای پر کردن نمونه‌های کاملاً جدید استفاده شود.

اگر پایتون در حالت اشکال‌زدایی یا با ادعاها ساخته شده باشد، بررسی کران‌ها به‌صورت یک ادعا انجام می‌شود.

توجه

این تابع ارجاعی به o را «می‌دزدد».

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)

Thread safety: Safe to call from multiple threads with external synchronization only.

نام مستعاری برای PyStructSequence_SetItem() است.

تغییر یافته در نسخه‌ی 3.13: اکنون به عنوان نامی مستعار برای PyStructSequence_SetItem() پیاده‌سازی شده است.