اشیاء دیکشنری¶

type PyDictObject¶: این زیرنوع «subtype» از PyObject نمایانگر یک شیء دیکشنری پایتون است.

PyTypeObject PyDict_Type¶: قسمتی از ABI پایدار.
این نمونه از PyTypeObject نوع دیکشنری پایتون را نمایندگی می‌کند. این همان شیء dict در لایه پایتون است.

int PyDict_Check(PyObject *p)¶: Thread safety: Atomic.
اگر p یک شیء dict یا نمونه‌ای از یک زیرنوع از نوع dict باشد، true را برمی‌گرداند. این تابع همیشه موفق می‌شود.

int PyDict_CheckExact(PyObject *p)¶: Thread safety: Atomic.
در صورتی که p یک شیء dict باشد اما نمونه‌ای از یک زیرنوع از نوع dict نباشد، مقدار true را برمی‌گرداند. این تابع همیشه موفق می‌شود.

PyObject *PyDict_New()¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.
یک دیکشنری خالی جدید برمی‌گرداند، یا در صورت شکست NULL.

PyObject *PyDictProxy_New(PyObject *mapping)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
یک شیء types.MappingProxyType برای نگاشتی که رفتار فقط‌خواندنی را اعمال می‌کند بازمی‌گرداند. این معمولاً برای ایجاد نمایی استفاده می‌شود که از تغییر دیکشنری در نوع‌های کلاس غیرپویا جلوگیری کند.

PyTypeObject PyDictProxy_Type¶: قسمتی از ABI پایدار.
شیء نوع برای اشیاء پراکسی نگاشت ایجاد‌شده توسط PyDictProxy_New() و برای ویژگی __dict__ فقط‌خواندنی بسیاری از نوع‌های توکار. یک نمونه‌ی PyDictProxy_Type نمای پویا و فقط‌خواندنی از یک دیکشنری زیرین ارائه می‌دهد: تغییرات دیکشنری زیرین در پراکسی منعکس می‌شوند، اما خود پراکسی از عملیات تغییر پشتیبانی نمی‌کند. این معادل types.MappingProxyType در پایتون است.

void PyDict_Clear(PyObject *p)¶: قسمتی از ABI پایدار. Thread safety: Atomic.
یک دیکشنری موجود را از تمام جفت‌های کلید-مقدار خالی می‌کند.

int PyDict_Contains(PyObject *p, PyObject *key)¶: قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.
تعیین می‌کند که آیا دیکشنری p شامل key است یا خیر. اگر آیتمی در p با key مطابقت داشته باشد، 1 را برمی‌گرداند، در غیر این صورت 0 را برمی‌گرداند. در صورت خطا، -1 را برمی‌گرداند. این معادل عبارت پایتونی key in p است.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

int PyDict_ContainsString(PyObject *p, const char *key)¶: Thread safety: Atomic.
این همان PyDict_Contains() است، اما key به‌صورت یک رشته‌ی بایتیِ کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه از نوع PyObject*.

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

PyObject *PyDict_Copy(PyObject *p)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.
یک دیکشنری جدید برمی‌گرداند که شامل همان جفت‌های کلید-مقدار p است.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶: قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.
val را با کلید key در دیکشنری p درج می‌کند. key باید هش‌پذیر باشد؛ در غیر این صورت، استثنای TypeError ایجاد خواهد شد. در صورت موفقیت 0 یا در صورت شکست -1 برمی‌گرداند. این تابع ارجاعی به val را «دزدی» نمی‌کند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶: قسمتی از ABI پایدار. Thread safety: Atomic.
این همان PyDict_SetItem() است، اما key به‌جای یک PyObject*، به‌صورت یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

int PyDict_DelItem(PyObject *p, PyObject *key)¶: قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.
ورودی دارای کلید key را از دیکشنری p حذف می‌کند. key باید hashable باشد؛ در غیر این صورت، TypeError مطرح می‌شود. اگر key در دیکشنری نباشد، KeyError مطرح می‌شود. در صورت موفقیت 0 و در صورت شکست -1 را برمی‌گرداند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

int PyDict_DelItemString(PyObject *p, const char *key)¶: قسمتی از ABI پایدار. Thread safety: Atomic.
این همان PyDict_DelItem() است، اما key به‌عنوان یک رشته‌ی بایتی کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه به‌عنوان PyObject*.

int PyDict_GetItemRef(PyObject *p, PyObject *key, PyObject **result)¶

قسمتی از ABI پایدار از نسخه‌ی 3.13. Thread safety: Safe for concurrent use on the same object.

بازگرداندن یک ارجاع قوی جدید به شیء موجود در دیکشنری p که کلید key را دارد:

اگر کلید موجود باشد، *result را برابر یک ارجاع قوی جدید به مقدار قرار می‌دهد و 1 را برمی‌گرداند.
اگر کلید وجود نداشته باشد، *result برابر NULL قرار می‌گیرد و 0 بازگردانده می‌شود.
در صورت خطا، یک استثنا برمی‌انگیزد، *result را برابر NULL قرار می‌دهد و -1 برمی‌گرداند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

همچنین تابع PyObject_GetItem() را ببینید.

PyObject *PyDict_GetItem(PyObject *p, PyObject *key)¶: مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.
ارجاع امانتی به شیء دارای کلید key را از دیکشنری p برمی‌گرداند. اگر کلید key موجود نباشد، NULL را بدون تنظیم استثنا برمی‌گرداند.

توجه

استثناهایی که هنگام فراخوانی متدهای __hash__() و __eq__() توسط این تابع رخ می‌دهند، بی‌صدا نادیده گرفته می‌شوند. به‌جای آن، استفاده از تابع PyDict_GetItemWithError() را ترجیح دهید.

توجه

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

تغییر یافته در نسخه‌ی 3.10: فراخوانی این API بدون وضعیت نخ متصل به دلایل تاریخی مجاز بود. این کار دیگر مجاز نیست.

PyObject *PyDict_GetItemWithError(PyObject *p, PyObject *key)¶: مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.
گونه‌ای از PyDict_GetItem() که استثناها را فرونمی‌نشاند. اگر استثنایی رخ داده باشد، NULL را همراه با استثنای تنظیم‌شده برمی‌گرداند. اگر کلید موجود نباشد، NULL را بدون استثنای تنظیم‌شده برمی‌گرداند.

توجه

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

PyObject *PyDict_GetItemString(PyObject *p, const char *key)¶: مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار. Thread safety: Safe to call from multiple threads with external synchronization only.
این همان PyDict_GetItem() است، اما key به‌جای PyObject*، به‌صورت یک رشته بایت کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود.

توجه

استثناهایی که هنگام فراخوانی متدهای __hash__() و __eq__() توسط این تابع یا هنگام ایجاد شیء موقت str رخ می‌دهند، به‌صورت خاموش نادیده گرفته می‌شوند. به‌جای آن، بهتر است از تابع PyDict_GetItemWithError() به‌همراه key PyUnicode_FromString() خودتان استفاده کنید.

توجه

در free-threaded build، اگر نخ دیگری دیکشنری را به‌صورت هم‌زمان تغییر دهد، ممکن است borrowed reference بازگردانده‌شده نامعتبر شود. ترجیحاً از PyDict_GetItemStringRef() استفاده کنید که یک strong reference برمی‌گرداند.

int PyDict_GetItemStringRef(PyObject *p, const char *key, PyObject **result)¶: قسمتی از ABI پایدار از نسخه‌ی 3.13. Thread safety: Atomic.
مشابه PyDict_GetItemRef()، اما key به‌عنوان یک رشته بایت کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه به‌صورت PyObject*.

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

PyObject *PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *defaultobj)¶: مقدار بازگشتی: مرجع امانتی. Thread safety: Safe to call from multiple threads with external synchronization only.
این همان dict.setdefault() در سطح پایتون است. در صورت وجود، مقدار متناظر با key را از دیکشنری p برمی‌گرداند. اگر کلید در دیکشنری نباشد، با مقدار defaultobj درج می‌شود و defaultobj برگردانده می‌شود. این تابع، تابع هش key را تنها یک بار ارزیابی می‌کند، به‌جای اینکه آن را به‌طور مستقل برای جستجو و درج ارزیابی کند.

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

توجه

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

int PyDict_SetDefaultRef(PyObject *p, PyObject *key, PyObject *default_value, PyObject **result)¶

Thread safety: Safe for concurrent use on the same object.

در صورتی که کلید از قبل در دیکشنری وجود نداشته باشد، default_value را با کلید key در دیکشنری p درج می‌کند. اگر result برابر NULL نباشد، *result به یک strong reference به default_value (در صورتی که کلید وجود نداشته باشد) یا به مقدار موجود (در صورتی که key از قبل در دیکشنری وجود داشته باشد) تنظیم می‌شود. اگر کلید وجود داشته باشد و default_value درج نشده باشد، 1 را برمی‌گرداند، و اگر کلید وجود نداشته باشد و default_value درج شده باشد، 0 را برمی‌گرداند. در صورت شکست، -1 را برمی‌گرداند، یک استثنا تنظیم می‌کند و *result را برابر NULL قرار می‌دهد.

برای شفافیت: اگر پیش از فراخوانی این تابع، ارجاع قوی به default_value داشته باشید، پس از بازگشت آن، ارجاع قوی به هر دو default_value و *result را در اختیار دارید (اگر NULL نباشد). این دو ممکن است به یک شیء واحد اشاره داشته باشند: در این صورت دو ارجاع جداگانه به آن در اختیار دارید.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

int PyDict_Pop(PyObject *p, PyObject *key, PyObject **result)¶

Thread safety: Safe for concurrent use on the same object.

کلید key را از دیکشنری p حذف می‌کند و به‌صورت اختیاری مقدار حذف‌شده را برمی‌گرداند. اگر کلید وجود نداشته باشد، استثنای KeyError صادر نمی‌شود.

اگر کلید موجود باشد، *result را در صورتی که result برابر NULL نباشد، برابر ارجاعی جدید به مقدار حذف‌شده قرار می‌دهد و 1 را برمی‌گرداند.
اگر کلید وجود نداشته باشد، *result را در صورتی که result برابر NULL نباشد برابر NULL قرار می‌دهد و 0 را برمی‌گرداند.
در صورت بروز خطا، یک استثنا ایجاد کرده و -1 را برمی‌گرداند.

شبیه dict.pop() است، اما بدون مقدار پیش‌فرض و در صورت نبود کلید، استثنای KeyError ایجاد نمی‌کند.

توجه

این عملیات در نخ‌بندی آزاد زمانی که key str، int، float، bool یا bytes باشد، اتمی است.

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

int PyDict_PopString(PyObject *p, const char *key, PyObject **result)¶: Thread safety: Atomic.
مشابه PyDict_Pop()، اما key به‌عنوان یک رشته بایت کدگذاری‌شده با UTF-8 از نوع const char* مشخص می‌شود، نه یک PyObject*.

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

PyObject *PyDict_Items(PyObject *p)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.
یک PyListObject حاوی همه‌ی آیتم‌های دیکشنری را برمی‌گرداند.

PyObject *PyDict_Keys(PyObject *p)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.
یک PyListObject شامل همه‌ی کلیدهای دیکشنری برمی‌گرداند.

PyObject *PyDict_Values(PyObject *p)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار. Thread safety: Atomic.
یک PyListObject شامل تمام مقادیر دیکشنری p برمی‌گرداند.

Py_ssize_t PyDict_Size(PyObject *p)¶: قسمتی از ABI پایدار. Thread safety: Atomic.
تعداد آیتم‌های موجود در دیکشنری را برمی‌گرداند. این معادل len(p) روی یک دیکشنری است.

Py_ssize_t PyDict_GET_SIZE(PyObject *p)¶: Thread safety: Atomic.
مشابه PyDict_Size()، اما بدون بررسی خطا.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

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

تمام جفت‌های کلید-مقدار در دیکشنری p را پیمایش می‌کند. مقدار Py_ssize_t که توسط ppos مشخص می‌شود، باید پیش از نخستین فراخوانی این تابع برای آغاز پیمایش، با 0 مقداردهی اولیه شود؛ این تابع برای هر جفت موجود در دیکشنری مقدار true و پس از گزارش همه‌ی جفت‌ها مقدار false را برمی‌گرداند. پارامترهای pkey و pvalue باید به متغیرهایی از نوع PyObject* اشاره کنند که به‌ترتیب با هر کلید و مقدار پر می‌شوند، یا می‌توانند NULL باشند. هر ارجاعی که از طریق آن‌ها بازگردانده می‌شود، امانتی است. ppos نباید در طول پیمایش تغییر داده شود. مقدار آن نشان‌دهنده‌ی آفست‌هایی در ساختار داخلی دیکشنری است و از آنجا که این ساختار خلوت است، این آفست‌ها متوالی نیستند.

برای مثال:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

دیکشنری p نباید در حین پیمایش تغییر داده شود. تغییر دادن مقدارهای کلیدها هنگام پیمایش دیکشنری ایمن است، اما تنها تا زمانی که مجموعه‌ی کلیدها تغییر نکند. برای مثال:

PyObject *key, *value;
Py_ssize_t pos = 0;

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    long i = PyLong_AsLong(value);
    if (i == -1 && PyErr_Occurred()) {
        return -1;
    }
    PyObject *o = PyLong_FromLong(i + 1);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

این تابع در ساخت‌ِ نخ‌آزاد بدون همگام‌سازی بیرونی، نخ‌ایمن نیست. می‌توانید از Py_BEGIN_CRITICAL_SECTION برای قفل کردن دیکشنری در حین پیمایش آن استفاده کنید:

Py_BEGIN_CRITICAL_SECTION(self->dict);
while (PyDict_Next(self->dict, &pos, &key, &value)) {
    ...
}
Py_END_CRITICAL_SECTION();

توجه

در نسخه‌ی نخ‌آزاد، می‌توان از این تابع به‌طور ایمن درون بخش بحرانی استفاده کرد. با این حال، ارجاع‌های برگردانده‌شده برای pkey و pvalue امانتی هستند و تنها تا زمانی که بخش بحرانی برقرار است معتبرند. اگر نیاز دارید از این اشیاء خارج از بخش بحرانی یا در زمانی که بخش بحرانی ممکن است معلق شود استفاده کنید، یک ارجاع قوی ایجاد کنید (برای مثال، با استفاده از Py_NewRef()).

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶: قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.
بر روی شیء نگاشت b پیمایش می‌کند و جفت‌های کلید-مقدار را به دیکشنری a اضافه می‌کند. b می‌تواند یک دیکشنری یا هر شیئی باشد که از PyMapping_Keys() و PyObject_GetItem() پشتیبانی کند. اگر override درست باشد، جفت‌های موجود در a در صورتی که کلید مطابقی در b یافت شود جایگزین می‌شوند، در غیر این صورت جفت‌ها تنها در صورتی اضافه می‌شوند که کلید مطابقی در a وجود نداشته باشد. در صورت موفقیت 0 و در صورت ایجاد استثنا -1 بازگردانده می‌شود.

توجه

در free-threaded build، وقتی b یک dict (با پیمایش‌گر استاندارد) باشد، هر دو a و b در طول عملیات قفل می‌شوند. وقتی b یک نگاشت غیردیکشنری باشد، فقط a قفل می‌شود؛ b ممکن است توسط نخ دیگری به‌طور هم‌زمان تغییر یابد.

int PyDict_Update(PyObject *a, PyObject *b)¶: قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.
این همان PyDict_Merge(a, b, 1) در C است و مشابه a.update(b) در پایتون است، با این تفاوت که PyDict_Update() در صورتی که آرگومان دوم ویژگی «keys» نداشته باشد، به پیمایش دنباله‌ای از جفت‌های کلید-مقدار بازنمی‌گردد. در صورت موفقیت 0 و در صورت بروز استثنا -1 را برمی‌گرداند.

توجه

در free-threaded build، وقتی b یک dict (با پیمایش‌گر استاندارد) باشد، هر دو a و b در طول عملیات قفل می‌شوند. وقتی b یک نگاشت غیردیکشنری باشد، فقط a قفل می‌شود؛ b ممکن است توسط نخ دیگری به‌طور هم‌زمان تغییر یابد.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶

قسمتی از ABI پایدار. Thread safety: Safe for concurrent use on the same object.

به‌روزرسانی یا ادغام در دیکشنری a، از جفت‌های کلید-مقدار در seq2. seq2 باید یک شیء پیمایش‌پذیر باشد که اشیاء پیمایش‌پذیر با طول ۲ تولید می‌کند که به‌عنوان جفت‌های کلید-مقدار در نظر گرفته می‌شوند. در صورت وجود کلیدهای تکراری، اگر override درست باشد آخری برنده می‌شود، در غیر این صورت اولی برنده می‌شود. در صورت موفقیت 0 و در صورت پرتاب استثنا -1 برمی‌گرداند. معادل پایتونی (به‌جز مقدار بازگشتی):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

توجه

در ساخت‌ نخ‌آزاد، فقط a قفل می‌شود. پیمایش روی seq2 همگام‌سازی نمی‌شود؛ ممکن است seq2 به‌طور هم‌زمان توسط نخ دیگری تغییر یابد.

int PyDict_AddWatcher(PyDict_WatchCallback callback)¶: Thread safety: Safe to call from multiple threads with external synchronization only.
callback را به‌عنوان دیده‌بان (watcher) دیکشنری ثبت می‌کند. یک شناسه‌ی عدد صحیح نامنفی برمی‌گرداند که باید به فراخوانی‌های آتی PyDict_Watch() پاس داده شود. در صورت خطا (برای مثال، وقتی دیگر شناسه‌ی دیده‌بانی در دسترس نباشد)، مقدار -1 را برمی‌گرداند و یک استثنا تنظیم می‌کند.

توجه

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

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

int PyDict_ClearWatcher(int watcher_id)¶: Thread safety: Safe to call from multiple threads with external synchronization only.
پایشگر (watcher) شناسایی‌شده با watcher_id را که پیش‌تر از PyDict_AddWatcher() برگردانده شده است، پاک می‌کند. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند (مثلاً اگر watcher_id داده‌شده هرگز ثبت نشده باشد.)

توجه

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

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

int PyDict_Watch(int watcher_id, PyObject *dict)¶: Thread safety: Safe to call without external synchronization on distinct objects.
دیکشنری dict را به‌عنوان تحت نظر علامت‌گذاری می‌کند. کال‌بکی که PyDict_AddWatcher() شناسه‌ی watcher_id را به آن اعطا کرده است، هنگامی که dict تغییر داده شود یا تخصیص‌گشایی شود فراخوانی خواهد شد. در صورت موفقیت 0 و در صورت خطا -1 برمی‌گرداند.

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

int PyDict_Unwatch(int watcher_id, PyObject *dict)¶: Thread safety: Safe to call without external synchronization on distinct objects.
دیکشنری dict را به‌عنوان دیگر دیده‌بانی‌نشده علامت‌گذاری می‌کند. کال‌بکی که PyDict_AddWatcher() شناسه‌ی watcher_id را به آن اعطا کرده است، دیگر زمانی که dict تغییر داده یا آزادسازی شود، فراخوانی نخواهد شد. دیکشنری باید پیش‌تر توسط این دیده‌بان دیده‌بانی شده باشد. در صورت موفقیت 0 و در صورت خطا -1 را برمی‌گرداند.

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

type PyDict_WatchEvent¶: برشمردن رویدادهای ممکن دیده‌بان دیکشنری: PyDict_EVENT_ADDED، PyDict_EVENT_MODIFIED، PyDict_EVENT_DELETED، PyDict_EVENT_CLONED، PyDict_EVENT_CLEARED یا PyDict_EVENT_DEALLOCATED.

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

typedef int (*PyDict_WatchCallback)(PyDict_WatchEvent event, PyObject *dict, PyObject *key, PyObject *new_value)¶

نوع تابع کال‌بک ناظر دیکشنری.

اگر event برابر PyDict_EVENT_CLEARED یا PyDict_EVENT_DEALLOCATED باشد، هر دو key و new_value برابر NULL خواهند بود. اگر event برابر PyDict_EVENT_ADDED یا PyDict_EVENT_MODIFIED باشد، new_value مقدار جدید برای key خواهد بود. اگر event برابر PyDict_EVENT_DELETED باشد، key در حال حذف شدن از دیکشنری است و new_value برابر NULL خواهد بود.

PyDict_EVENT_CLONED زمانی رخ می‌دهد که dict قبلاً خالی بوده و دیکشنری دیگری در آن ادغام شود. برای حفظ کارایی این عملیات، در این حالت رویدادهای PyDict_EVENT_ADDED به ازای هر کلید صادر نمی‌شوند؛ در عوض یک PyDict_EVENT_CLONED واحد صادر می‌شود و key دیکشنری منبع خواهد بود.

کال‌بک می‌تواند dict را بازرسی کند، اما نباید آن را تغییر دهد؛ انجام این کار می‌تواند اثرات غیرقابل پیش‌بینی، از جمله بازگشت بی‌نهایت، داشته باشد. در کال‌بک، اجرای کد پایتون را فعال نکنید، زیرا ممکن است به عنوان یک عارضه جانبی، دیکشنری را تغییر دهد.

اگر event برابر PyDict_EVENT_DEALLOCATED باشد، گرفتن یک ارجاع جدید به دیکشنریِ در آستانه‌ی نابودی از درون کال‌بک، آن را احیا می‌کند و جلوی آزاد شدن آن را در این لحظه می‌گیرد. هنگامی که شیء احیا‌شده بعداً نابود شود، هر کال‌بکِ ناظری که در آن زمان فعال باشد، دوباره فراخوانی خواهد شد.

کال‌بک‌ها پیش از انجام تغییر اطلاع‌رسانی‌شده در dict رخ می‌دهند، بنابراین می‌توان وضعیت پیشین dict را بررسی کرد.

اگر کال‌بک استثنایی تنظیم کند، باید -1 را برگرداند؛ این استثنا با استفاده از PyErr_WriteUnraisable() به‌عنوان یک استثنای غیرقابل‌پرتاب (unraisable) چاپ خواهد شد. در غیر این صورت، بهتر است 0 را برگرداند.

ممکن است هنگام ورود به کال‌بک، از قبل استثنایی در انتظار تنظیم‌شده باشد. در این حالت، کال‌بک باید 0 را بازگرداند، در حالی که همان استثنا همچنان تنظیم‌شده است. این بدان معناست که کال‌بک نمی‌تواند هیچ API دیگری که می‌تواند استثنا تنظیم کند فراخوانی کند، مگر آنکه ابتدا وضعیت استثنا را ذخیره و پاک کند و پیش از بازگشت، آن را بازگردانی کند.

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

اشیاء نمای دیکشنری¶

int PyDictViewSet_Check(PyObject *op)¶: اگر op نمایی از یک مجموعه درون یک دیکشنری باشد، مقدار true را برمی‌گرداند. این تابع در حال حاضر معادل PyDictKeys_Check(op) || PyDictItems_Check(op) است. این تابع همیشه با موفقیت اجرا می‌شود.

PyTypeObject PyDictKeys_Type¶: قسمتی از ABI پایدار.
شیء نوع برای نمای کلیدهای دیکشنری. در پایتون، این نوع شیء‌ای است که dict.keys() برمی‌گرداند.

int PyDictKeys_Check(PyObject *op)¶: اگر op نمونه‌ای از نمای کلیدهای دیکشنری باشد، مقدار true برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyTypeObject PyDictValues_Type¶: قسمتی از ABI پایدار.
شیء نوع برای نمای مقادیر دیکشنری. در پایتون، این نوع شیء‌ای است که توسط dict.values() بازگردانده می‌شود.

int PyDictValues_Check(PyObject *op)¶: اگر op نمونه‌ای از نمای مقادیر دیکشنری باشد، مقدار true برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

PyTypeObject PyDictItems_Type¶: قسمتی از ABI پایدار.
شیء نوع برای نمای آیتم‌های دیکشنری. در پایتون، این نوع شیءی است که توسط dict.items() برگردانده می‌شود.

int PyDictItems_Check(PyObject *op)¶: اگر op نمونه‌ای از نمای آیتم‌های دیکشنری باشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

دیکشنری‌های ترتیب‌دار¶

API زبان C پایتون رابطی برای collections.OrderedDict از C فراهم می‌کند. از پایتون 3.7 به بعد، دیکشنری‌ها به‌طور پیش‌فرض مرتب هستند، بنابراین معمولاً نیاز اندکی به این توابع وجود دارد؛ در صورت امکان PyDict* را ترجیح دهید.

PyTypeObject PyODict_Type¶: شیء نوع برای دیکشنری‌های مرتب. این همان شیء collections.OrderedDict در لایه‌ی پایتون است.

int PyODict_Check(PyObject *od)¶: اگر od یک شیء دیکشنری مرتب یا نمونه‌ای از یک زیرنوع از نوع OrderedDict باشد، مقدار true را برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

int PyODict_CheckExact(PyObject *od)¶: اگر od یک شیء دیکشنری مرتب باشد، اما نمونه‌ای از یک زیرنوع از نوع OrderedDict نباشد، مقدار درست را برمی‌گرداند. این تابع همیشه موفق است.

PyTypeObject PyODictKeys_Type¶: مشابه PyDictKeys_Type برای دیکشنری‌های مرتب.

PyTypeObject PyODictValues_Type¶: مشابه PyDictValues_Type برای دیکشنری‌های مرتب.

PyTypeObject PyODictItems_Type¶: مشابه PyDictItems_Type برای دیکشنری‌های مرتب است.

PyObject *PyODict_New(void)¶

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

این مشابه PyDict_New() است.

int PyODict_SetItem(PyObject *od, PyObject *key, PyObject *value)¶

value را با کلید key در دیکشنری مرتب od درج می‌کند. در صورت موفقیت 0 و در صورت شکست -1 همراه با تنظیم یک استثنا برمی‌گرداند.

این مشابه PyDict_SetItem() است.

int PyODict_DelItem(PyObject *od, PyObject *key)¶

ورودی با کلید key را از دیکشنری مرتب od حذف می‌کند. در صورت موفقیت 0 و در صورت شکست -1 همراه با تنظیم یک استثنا برمی‌گرداند.

این مشابه PyDict_DelItem() است.

این‌ها نام‌های مستعار soft deprecated برای API‌های PyDict هستند:

`PyODict`	`PyDict`
PyODict_GetItem(od, key)¶	`PyDict_GetItem()`
PyODict_GetItemWithError(od, key)¶	`PyDict_GetItemWithError()`
PyODict_GetItemString(od, key)¶	`PyDict_GetItemString()`
PyODict_Contains(od, key)¶	`PyDict_Contains()`
PyODict_Size(od)¶	`PyDict_Size()`
PyODict_SIZE(od)¶	`PyDict_GET_SIZE()`

اشیاء دیکشنری¶

اشیاء نمای دیکشنری¶

دیکشنری‌های ترتیب‌دار¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه